Programmation Java/Tags Javadoc

Java permet de documenter les classes et leurs membres en utilisant une syntaxe particulière des commentaires. Ils sont alors interprétés par le générateur automatique de documentation Javadoc, fourni par le JDK. La commande javadoc sans argument donne la syntaxe complète de la commande.

Programmation Java

Version imprimable

[ Modifier le sommaire ]

Nombre de taille arbitraire

Annotations

Ces commentaires commencent par la séquence /** et se terminent par */. Le contenu décrit l'entité qui suit (classe, interface, méthode ou attribut), suivi d'une série d'attributs dont le nom commence par un arobase @.

La documentation générée étant au format HTML, il est possible d'insérer des balises dans la description.

Exemples

Exemple 1

/**
    Une classe pour donner un <b>exemple</b> de documentation HTML.
*/
public class Exemple {
    /** ...Documentation du membre de type entier nommé exemple... */
    public int exemple;

Le commentaire de documentation se place juste avant l'entité commentée (classe, constructeur, méthode, champ).

Dans un commentaire de documentation, la première partie est un texte de description au format HTML. La seconde partie est une liste d'attributs spéciaux dont le nom commence par un arobase (@). Ces derniers sont interprétables par le compilateur et appelés tags.

Exemple 2

/**
    Une classe pour illustrer les commentaires Javadoc.
    @author Moi :-)
*/
public class Exemple {
    /**
        Une méthode <b>main</b> qui ne fait rien.
        @param args Les arguments de la ligne de commande.
    */
    public static void main(String[] args) {
    }
}

En fait, il existe un attribut Javadoc qui est pris en compte par le compilateur : l'attribut @deprecated. Cet attribut marque une classe, une méthode ou une variable comme obsolète. Ce qui signifie que si une autre classe l'utilise un avertissement est affiché à la compilation de cette classe.

Exemple :

/**
    Une méthode obsolète. Il faut utiliser get() à la place.
    @deprecated
*/
public Object getElement(int index)
{ ... }

/**
    Une nouvelle méthode.
*/
public Object get(int index)
{ ... }

Cet attribut permet de modifier une bibliothèque de classe utilisée par plusieurs applications, en la laissant compatible avec les applications utilisant l'ancienne version, mais en indiquant que les anciennes classes / méthodes / variables ne doivent plus être utilisées et pourraient ne plus apparaître dans une version ultérieure.

Exemple 3

Exemple pour la méthode suivante :

/**
    Obtenir la somme de deux entiers.
    @param a Le premier nombre entier.
    @param b Le deuxième nombre entier.
    @return La valeur de la somme des deux entiers spécifiés.
*/
public int somme(int a, int b) {
    return a + b;
}

Obtenir la somme de deux entiers.: Description de la méthode somme.
@param a Le premier nombre entier.: Attribut de description du paramètre a de la méthode.
@param b Le deuxième nombre entier.: Attribut de description du paramètre b de la méthode.
@return La valeur de la somme des deux entiers spécifiés.: Attribut de description de la valeur retournée par la méthode.

Voici une liste non exhaustive des attributs spéciaux :

Attribut et syntaxe	Dans un commentaire de ...	Description
@author auteur	classe	Nom de l'auteur de la classe.
@version version	classe	Version de la classe.
@deprecated description	classe, constructeur, méthode, champ	Marquer l'entité comme obsolète (ancienne version), décrire pourquoi et par quoi la remplacer. Si l'entité marquée comme obsolète par cet attribut est utilisée, le compilateur donne un avertissement.
@see référence	classe, constructeur, méthode, champ	Ajouter un lien dans la section "Voir aussi".
@param description de l'id	constructeur et méthode	Décrire un paramètre de méthode.
@return description	méthode	Décrire la valeur retournée par une méthode.
@exception description du type	constructeur et méthode	Décrire les raisons de lancement d'une exception du type spécifié (clause `throws`).

Exemple 4

Exemple pour une classe nommée Exemple définie dans un package nommé org.wikibooks.fr dans le fichier C:\ProgJava\org\wikibooks\fr\Exemple.java :

package org.wikibooks.fr;

/**
    Une classe d'exemple.
*/
public class Exemple {
    /**
        Obtenir la somme de deux entiers.
        @param a Le premier nombre entier.
        @param b Le deuxième nombre entier.
        @return La valeur de la somme des deux entiers spécifiés.
    */
    public int somme(int a, int b) {
        return a + b;
    }
}

Références

Dans la documentation, il est souvent nécessaire de faire référence à une autre entité (méthode, champ, classe) appartenant à la même classe, une autre classe ou un autre package. Certains tags Javadoc sont dédiés aux références :

@see permet d'ajouter des références dans une section « Voir aussi » ("See also" en anglais) de la documentation de la méthode, du champ, de la classe ou du package.
@link permet d'ajouter une référence au milieu du texte de la description.
@value permet d'ajouter la valeur d'une constante au milieu du texte de la description.

Les deux derniers tags s'insérant au milieu du texte de la description doivent être encadrés par des accolades.

Chaque référence est un lien vers la documentation de l'entité référencée, et doit suivre la syntaxe suivante :

[classe][#membre]

Elle est composée de deux parties optionnelles :

classe

Le nom de la classe (avec le nom du package sauf si importé) est optionnel quand le membre est défini dans la même classe.

#membre

Le nom du membre de la classe (champ ou méthode) est absent dans les références à une classe.

Pour les champs, le nom est suffisant.
Pour les méthodes, le nom doit être suivi du type des paramètres entre parenthèses.

/**
 * Cette méthode appelle {@link #toString()} pour obtenir...
 * @see Object#equals(Object)
 * @see #uneAutreMethod(int, java.util.Map)
 */
public void uneMethodeQuelconque()
{ /* ... */ }

public void uneAutreMethod(int index, java.util.Map mapping)
{ /* ... */ }

Générer la documentation

La documentation peut être générée dans un répertoire spécifique (C:\ProgDoc par exemple) avec la commande suivante :

javadoc -locale fr_FR -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.wikibooks.fr

Les options de cette commande sont décrites ci-dessous :

-locale fr_FR: La documentation est en français.
-use: Créer les pages sur l'utilisation des classes et paquetages (packages).
-classpath C:\ProgJava: Le chemin des classes compilées (*.class).
-sourcepath C:\ProgJava: Le chemin des classes sources (*.java).
-d C:\ProgDoc: Le chemin où la documentation doit être générée.
org.wikibooks.fr: Le nom du paquetage (package) à documenter. Il est possible de spécifier plusieurs paquetages, ou un ou plusieurs noms de classe pour ne documenter que celles-ci.

Niveau de documentation

Par défaut, javadoc ne génére pas la documentation pour les commentaires au-dessus d'une méthode ou d'un champ possédant le modificateur « private ». Ce qui est logique pour une documentation destinée à ceux qui vont utiliser les classes de manière externe, sans accès aux membres privés depuis leur propres classes.

Cependant, la documentation des membres privés peut être utile aux développeur des classes concernées. De même, les développeurs qui utilisent les classes d'un package depuis leurs propres packages n'ont pas besoin de la documentation des membres protégés. La commande javadoc possède donc des options pour le niveau de documentation voulu :

-public : ne documenter que les membres publics.
-protected : ne documenter que les membres publics et protégés.
-package : ne documenter que les membres publics, protégés et package (sans mot-clé).
-private : documenter tous les membres (publics, protégés, package, privés).

Description du package

La page de description d'un paquetage copie le texte de description à partir d'un fichier nommé package.html qui doit se situer dans le répertoire correspondant. Dans notre exemple, il faut documenter le paquetage dans le fichier C:\ProgJava\org\wikibooks\fr\package.html.

Dans les versions récentes de Java, le fichier package.html peut être remplacé par un fichier Java spécial nommé package-info.java contenant uniquement la déclaration du paquetage (package) précédée d'un commentaire de documentation.

Exemple (C:\ProgJava\org\wikibooks\fr\package-info.java) :

/**
  Ce paquetage fictif sert à illustrer le livre sur Java
  de <i>fr.wikibooks.org</i>.
*/
package org.wikibooks.fr;