Aide-mémoire de javadoc

Aide-m´emoire de javadoc
1. Introduction
javadoc est un utilitaire de jdk (inclus dans les jdr les plus r´ecentes) qui permet de g´en´erer
la documentation des classes d´evelopp´ees, sous r´eserve d’avoir comment´e le code java
suivant les r`egles ´enonc´ees ci-dessous.
La documentation compl`ete de javadoc est sur le site : http://java.sun.com/j2se/javadoc/.
La documentation sur les classes des API de java est g´en´er´ee par javadoc.
2. Les indispensables
•Format du commentaire
Chaque d´eclaration de package, classe, attribut, m´ethode. . . qui sera pr´ec´ed´ee du
commentaire /** commentaire */ sera pris en compte.
•R´esum´e et pr´ecisions
La premi`ere phrase du commentaire (jusqu’au premier ’.’) est utilis´ee comme de-
scription r´esum´ee de l’entit´e comment´ee. Les suivantes apparaissent dans la section
des pr´ecisions.
•R`egles de commentaires
Commencer les commentaires de m´ethodes par des verbes, ceux des classes et attributs
peuvent ne pas avoir de sujet. Exemple pour une classe :
/∗∗
∗Cumul des not es des e t u d i a n t s par matiere
∗/
publ ic c l a s s CumulNotes {
. . .
/∗∗ I n s e r e r une n ot e . ∗/
public void insererNote(float n ) throws BadNoteValueException {. . .
}
En r`egle g´en´eral, selon le contexte dans lequel on travaille, ´ecrire en anglais peut-ˆetre
utile...
•HTML
Il est possible d’ins´erer des balises HTML directement dans les commentaires.
/∗∗ Regroupement des ma t i er e s en un module
∗On prendra comme exemple l e module ‘ ‘ Java ’ ’ dont l e s m ati e r es s ont :
∗<l i >Programmation</ l i >
∗<l i >Java Reseau</ l i >
∗<l i >Projet</ l i >
∗<p>
∗Les ma tie r e s s o n t pond e rees par des c o e f f i c i e n t s .
∗/
publ ic c l a s s Module {. . .

•Quelques tags
–@param p commentaire pour les param`etres de m´ethode
–@return commentaire pour le retour de m´ethodes
–@throws class-name description pour indiquer les exceptions lev´ees
•Hi´erarchie
Pour obtenir une hi´erarchie avec plusieurs packages il suffit d’appliquer javadoc
`a l’ensemble de la hi´erarchie. 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 ˆetre 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 re r l e s no t es d ’un module .
∗<p>
∗U t i l i s e p r i n c i p a l e m e n t l a c l a s s e {@lin k jav a . u t i l . Ar r a y L i s t }.
∗@author moi−meme
∗/
package note ;
∗/
3. Exemples
Figure 1: Documentation g´en´er´ee pour les packages du projet

Figure 2: Documentation g´en´er´ee pour le package note
Figure 3: Documentation g´en´er´ee pour la classe CumulNotes

Figure 4: Documentation g´en´er´ee pour les attributs et m´ethodes de CumulNotes