III. Javadoc

a. Présentation

JavaDoc est un outil, fournit avec le SDK, qui permet de générer automatiquement la documentation technique d'une application écrite en Java. Pour cela, le programmeur doit agrémenter son code source de quelques commentaires particuliers décrivant les principaux éléments du programme. La documentation générée se présente sous la forme d'un ensemble de pages HTML. Il existe une grande quantité d'options et de marqueurs qui permettent d'enrichir la documentation avec des informations particulières.

Le résultat obtenu est semblable à la documentation officielle des classes java consultable sur Internet. Tout programmeur Java se familiarise donc immédiatement avec la documentation générée par JavaDoc.

b. Les commentaires à ajouter

Ils se présentent sous la forme d'un commentaire multilignes qui débute par le jeu de caractères " /** ". Chaque ligne suivante commence par une étoile, et le commentaire se termine par une étoile suivit d'un slash.

Ce type de commentaire doit être ajouté avant chaque élément important de la classe:
• Un descriptif global avant la classe.
• Un descriptif avant chaque donnée et chaque méthode.

Les commentaires, sauf les paramètres spéciaux décrits ci après, ne sont pas interprétés par JavaDoc. Il est donc possible d'ajouter du code HTML au sein du commentaire afin de mettre en forme le texte, insérer des images...

c. Les paramètres spéciaux

Ils sont assez nombreux et évoluent au fil des versions du SDK. Quelques uns d'entre eux sont cependant fréquemment utilisés. Les paramètres sont séparés de la description par une ligne vide, ils débutent par une arobase, suivit du nom du paramètre, puis du commentaire correspondant.

Voici les paramètres les plus utilisés et leurs fonctions :
• @author : auteur de l'élément décrit
• @version : version
• @param : suivit du nom du paramètre puis de son descriptif, sert à lister l'ensemble des paramètres d'une méthode.
• @see : permet de faire référence à d'autres classes que l'utilisateur serait bien inspiré de consulter pour bien utiliser cette classe.
• @since : permet de spécifier la compatibilité de la classe. ex : since JDK1.3 permet de signifier l'incompatibilité de la classe avec les versions antérieures de Java.
• @return : même fonctionnement que param, mais pour décrire ce que renvoie la méthode.

d. Exécution et options de Javadoc

L'exécution de JavaDoc s'effectue par l'intermédiaire de l'invite de commande. Il suffit de taper le mot " javadoc " puis la liste des fichiers " .java ", séparés par des espaces, dont l'utilisateur souhaite générer la documentation. Quelques options permettent d'affiner la génération de la documentation, celles-ci s'insèrent entre " javadoc " et la liste des fichiers à convertir. Le nom d'une option est toujours précédé d'un tiret.

Options les plus couramment utilisées :
• " -d ", suivit d'un nom de répertoire, permet de choisir le répertoire dans lequel sera générée la documentation. Le répertoire doit être préalablement créé.
• " -author " permet de prendre en compte le paramètre @author lors de la génération de la documentation.
• " -version " permet de prendre en compte le paramètre @version lors de la génération de la documentation.
• " -classpath " suivit de l'adresse des bibliothèques, permet à javadoc de générer la documentation en connaissant les caractéristiques des types étrangers à la classe.
• " -public " permet de générer la documentation uniquement pour les classes publiques.
• " -protected " permet de générer la documentation pour les classes et membres publics et protégés. C'est l'option par défaut.
• " -package " permet de générer la documentation pour les classes et membres publics, protégés et ceux accessibles aux classes d'un même package.
• " -private " génère la documentation pour toutes les classes et tous les membres.

Exemple d'exécution :

La commande " javadoc -d doc -author -private Exemple.java " génère la documentation, dans le répertoire doc, du fichier Exemple.java. Le paramètre @author est pris en compte et toutes les classes du fichier et leurs membres sont documentés.