Comme nous l'avons déjà dit (voir 3.2.3) , Java permet d'inclure dans un programme sous forme de commentaires toute la documentation que l'on veut voir donner sur les classes et interfaces que l'on programme. L'utilitaire javadoc extrait du code Java ces commentaires pour les transformer en fichier HTML à l'image de la document des API de SUN .
Ces commentaires de documentation peuvent contenir des balises HTML et des balises javadoc facilitant la présentation de la documentation.
La documentation est constitué des caractères compris entre ``/**'' et ``*/''. De plus, si les premiers caractères non blancs (espace et tabulation ) sont des ``*'', alors ils sont ignorés. Tous les caractères blanc précédants le caractère ``*'' sont également ignorés. Ces commentaires peuvent apparaître avant chaque définition de classes , d'interface ainsi qu'avant les méthodes , les constructeurs ou champs .
/** * Ceci est un commentaire de <b>documentation</b>. */
La première phrase figurant dans ce type de commentaire servira de résumé de la documentation de l'entité commenté. Il convient donc de donner une description succincte et complète de l'entité. La fin de la première phrase est déterminée par le caractère ``.'' suivi d'un espace , d'une tabulation ou d'une retour chariot .
Attention aux phrases du genre: This is a simulation of Prof. Knuth's MIX computer.Les phrases qui suivent et qui sont placées avant toute balise javadoc serviront de texte pour la description détaillée.
Les commentaires de documentation ne analysés par l'utilitaire javadoc. Celui-ci reconnaît un certain nombre de balises qui lui sont propres. Une ligne de commentaire commençant par un des mots clés suivant: @see, @author, @version, @param, @return et @exception. Ces balises sont utiles pour mettre en forme la documentation et pour générer les références croisées.
La balise @see permet de définir des références vers d'autres classes , interfaces , méthodes , constructeurs , champs ou URL .
Le caractère ``#'' est un séparateur entre le nom de classe et le nom d'un champ, d'une méthode ou d'un constructeur. Il peut y avoir autant de balises @see que nécessaires.
@see java.lang.String @see String @see java.io.InputStream; @see String#equals @see java.lang.Object#wait(int) @see java.io.RandomAccessFile#RandomAccessFile(File, String) @see Character#MAX_RADIX @see <a href="spec.html">Java Spec</a>
Les balises @author permettent de spécifier le ou les auteurs. Elles peuvent figurer dans les documentations de classes et des interfaces.
Il peut y avoir autant de balises @author que nécessaire. On peut également spécifier plusieurs auteurs par balise:
@author Mary Wollstonecraft @author Hildegard von Bingen @author Dorothy Parker
Toutefois, les concepteurs du langage recommande d'utiliser une balise par auteur de manière permettre une mise en forme plus agréable.
@author Mary Wollstonecraft, Hildegard von Bingen Dorothy Parker
Les balises @version peuvent figurer dans les documentations de classes et des interfaces.
Il ne peut y avoir qu'au plus une balise @version par paragraphe.
@version 493.0.1beta
Les balises @param permettent de commenter les paramètres des méthodes et des constructeurs. Elles ne peuvent figurer que dans les documentations de méthodes et des constructeurs.
La structure d'un paragraphe de type @param est constitué du nom du paramètre suivi par une courte description.
@param fic le fichier dans lequel il faut effectuer la recherche @param motif le motif à rechercher @param nbre le nombre de lignes à afficher à chaque correspondance
La convention adoptée par Java veut que l'on choisisse soit de ne commenter aucun paramètre, soit de commenter tous les paramètres dans l'ordre où ils apparaissent.
Les balises @return permettent de documenter les valeurs retournées par les méthodes. Elles peuvent figurer dans les documentations des méthodes dont le type de retour est autre que void.
Par convention, la balise @return est suivi d'une courte description de la valeur retournée. Il ne peut y avoir qu'au plus une balise @return.
@return Le nombre de lignes contenant le motif recherché
Les balises @exception permettent de commenter les exceptions lancées par une méthode ou un constructeur. Elles ne peuvent donc figurer que dans les documentations de méthodes et des constructeurs.
@exception IndexOutOfBoundsException Débordement de la matrice @exception java.io.FileNotFoundException le fichier n'existe pas
/** * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> * * @author Sami Shaio * @version %I%, %G% * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... }
/** * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. * @see java.lang.Character#charValue() */ public char charAt(int index) { ... }
A field comment can contain only the @see, @since and @deprecated tags (as described above).
/** * The X-coordinate of the window. * * @see window#1 */ int x = 1263732;
La forme générale de la commande javadoc est de la forme
où les options sont les suivantes:
javadoc [ options ] [ package | source.java ]*
- -classpath
- chemin
- -public
- -protected
- -package
- -private
- -J
- flags
- -encoding
- nom
- -docencoding
- nom
- -version
- -author
- -noindex
- -notree
- -d
- répertoire
- -verbose
- -sourcepath
- chemin
- -nodeprecated