Aide-mémoire de javadoc

Aide-mémoire de javadoc
1. Introduction
javadoc est un utilitaire de jdk (inclus dans les jdr les plus récentes) qui permet de générer
la documentation des classes développées, sous réserve d’avoir commenté le code java
suivant les règles énoncées ci-dessous.
La documentation complète de javadoc est sur le site : http://java.sun.com/j2se/javadoc/.
La documentation sur les classes des API de java est générée par javadoc.
2. Les indispensables
• Format du commentaire
Chaque déclaration de package, classe, attribut, méthode. . . qui sera précédée du
commentaire /** commentaire */ sera pris en compte.
• Résumé et précisions
La première phrase du commentaire (jusqu’au premier ’.’) est utilisée comme description résumée de l’entité commentée. Les suivantes apparaissent dans la section
des précisions.
• Règles de commentaires
Commencer les commentaires de méthodes par des verbes, ceux des classes et attributs
peuvent ne pas avoir de sujet. Exemple pour une classe :
/∗ ∗
∗ Cumul d e s n o t e s d e s e t u d i a n t s par m a t i e r e
∗/
public c l a s s CumulNotes {
...
/∗ ∗ I n s e r e r une n o t e . ∗/
public void i n s e r e r N o t e ( f l o a t n ) throws BadNoteValueException { . . .
}
En règle général, selon le contexte dans lequel on travaille, écrire en anglais peut-être
utile...
• HTML
Il est possible d’insérer des balises HTML directement dans les commentaires.
/∗ ∗ Regroupement d e s m a t i e r e s en un module
∗ On p r e n d r a comme exemple l e module ‘ ‘ Java ’ ’ dont l e s m a t i e r e s s o n t :
∗ < l i >Programmation</ l i >
∗ < l i >Java Reseau</ l i >
∗ < l i >P r o j e t </ l i >
∗ <p>
∗ Les m a t i e r e s s o n t p o n d e r e e s par d e s c o e f f i c i e n t s .
∗/
public c l a s s Module { . . .
• Quelques tags
– @param p commentaire pour les paramètres de méthode
– @return commentaire pour le retour de méthodes
– @throws class-name description pour indiquer les exceptions levées
• Hiérarchie
Pour obtenir une hiérarchie avec plusieurs packages il suffit d’appliquer javadoc
à l’ensemble de la hiérarchie. Pour commenter les packages, il faut ajouter un
fichier package-info.java dans lequel on met les informations voulues. Le fichier
package-info.java doit être dans l’arborescence du package.
/∗ ∗
∗ Procure l e s c l a s s e s n e c e s s a i r e s pour g e r e r l e s n o t e s d ’ un module .
∗ <p>
∗ U t i l i s e principalement l a c l a s s e { @link java . u t i l . ArrayList }.
∗ @author moi−meme
∗/
package n o t e ;
∗/
3. Exemples
Figure 1: Documentation générée pour les packages du projet
Figure 2: Documentation générée pour le package note
Figure 3: Documentation générée pour la classe CumulNotes
Figure 4: Documentation générée pour les attributs et méthodes de CumulNotes