next up previous contents index
Next: 46 Le langage SQL Up: Java: Annexes Previous: Java: Annexes

Subsections

45 javadoc

 

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 .

45.1 Les balises HTML

Ces commentaires peuvent contenir des balises HTML. Il convient toutefois d'éviter les balises: <H1>, <H2>, <H3>, <H4>, <H5>, <H6>, et <HR>. Ces balises peuvent entrer en conflit avec celles générées par l'outil javadoc.
 
/**
 * Ceci est un commentaire de <b>documentation</b>.
 */

45.2 Résumé et description détaillée

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.

45.3 Les balises javadoc

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.

45.4 La balise @see

La balise @see permet de définir des références vers d'autres classes , interfaces , méthodes , constructeurs , champs ou URL .

 
@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>
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.

45.4.1 La balise @author

Les balises @author permettent de spécifier le ou les auteurs. Elles peuvent figurer dans les documentations de classes et des interfaces.

 
@author Mary Wollstonecraft
@author Hildegard von Bingen
@author Dorothy Parker
Il peut y avoir autant de balises @author que nécessaire. On peut également spécifier plusieurs auteurs par balise:
 
@author Mary Wollstonecraft, Hildegard von Bingen
        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.

45.4.2 La balise @version

Les balises @version peuvent figurer dans les documentations de classes et des interfaces.

 
@version 493.0.1beta
Il ne peut y avoir qu'au plus une balise @version par paragraphe.

45.4.3 La balise @param

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.

 
@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 structure d'un paragraphe de type @param est constitué du nom du paramètre suivi par une courte description.

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.

45.4.4 La balise @return

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.

 
@return Le nombre de lignes contenant le motif recherché
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.

45.4.5 Le balise @exception

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

45.4.6 La balise @since

45.4.7 La balise @deprecated

45.5 Résumé

45.5.1 Documentation des classes et interfaces

 
/**
 * 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 {
    ...
}

45.5.2 Documentation des méthodes et constructeurs

@param
description des paramètres
@return
description du retour de la méthode
@exception
nom-complet-de-l'exception description
@see
nom de la classe
@since
texte
@deprecated
texte ``deprecated''
 
/**
 * 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) {
    ...
}

45.5.3 Documentation des champs

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;

45.6 La commande javadoc

La forme générale de la commande javadoc est de la forme

 
javadoc [ options ] [ package | source.java ]*
où les options sont les suivantes:
-classpath
chemin
-public
-protected
-package
-private
-J
flags
-encoding
nom
-docencoding
nom
-version
-author
-noindex
-notree
-d
répertoire
-verbose
-sourcepath
chemin
-nodeprecated


next up previous contents index
Next: 46 Le langage SQL Up: Java: Annexes Previous: Java: Annexes
Touraivane
6/12/1998