Javadoc est un outils fourni par Sun avec le JDK pour permettre la génération d'une documentation technique à partir du code source.
Pour générer la documentation, il faut invoquer l'outils javadoc. Javadoc recrée à chaque utilisation la totalité de la documentation.
La documentation générée est par défaut au format HTML.
Pour formatter la documentation, javadoc utilise une doclet. Une doclet permet de préciser le format de la documentation générée. Par défaut, javadoc propose un doclet qui génère une documentation au format HTML. Il est possible de définir sa propre doclet pour changer le contenu ou le format de la documentation (pour par exemple, générer du RTF ou du XML).
Par défaut , la documentation générée contient les éléments suivants :
La documentation de l'API java fourni par Sun est réalisée grâce à javadoc :
Javadoc s'appuie sur le code source et sur un type de commentaires particuliers pour obtenir des données supplémentaires aux éléments qui composent le code source. Ces commentaires suivent des règles précises.
Ces commentaires commencent par /** et finissent par */ et contiennent toujours au minimum une phrase qui est un résumé de le l'élément. Si le commentaire utilise plusieurs ligne, javadoc ignore les premiers caractères d'espacement ainsi que le premier caractères * qui suit ces caractères. Ceci permet d'utiliser le caractère * pour aligner le contenu du commentaires
Il est possible de faire suivre cette suivre cette phrase d'un texte descriptif plus complet.
Il est possible d'utiliser des tags HTML pour formatter le texte : il ne faut pas utiliser de tags HTML de structure tel que Hn, HR ... qui sont utilisés par javadoc pour formatter la documentation.
Enfin il est possible d'utiliser des tags prédéfinis par javadoc pour fournir des informations plus précises sur des composants particuliers de l'élément (auteur, parametres, valeur de retour). Ces tags sont définis pour un ou plusieurs type d'élément.
| Exemple ( code java 1.0 ) : |
|
Par défaut, javadoc prend en compte les éléments suivants : les classes, les interfaces, les méthodes et les champs public et protected. Le placement du commentaire de documentation dans le code source est important. Le documentaire est associé à l'élément qui suit immédiatement le commentaire. Il faut ainsi pour faire précéder l'élément concerné par sa documentation et ne déclarer qu'une seule entité par ligne pour pouvoir lui associer la documentation.
Javadoc défini plusieurs tags qui permettent de précises certains composants de l'élément décrit de façon standardisée. Ces tags commencent tous par le caractère arobase @. Il existe deux types de tags :
Pour pouvoir être interprétés les tags standards doivent obligatoire commencé en début de ligne.
| Tag | Rôle | élément concerné |
version du JDK
|
| @author | permet de préciser l'auteur de l'élement | classe et interface |
1.0
|
| @deprecated | permet de préciser qu'un élément est déprécié | package, classe, interface, méthode et champ |
1.1
|
| {@docRoot} | représente le chemin relatif du répertoire principal de génération de la documentation |
1.3
|
|
| @exception | permet de préciser une exception qui peut être levée par l'élément | méthode |
1.0
|
| {@link} | permet d'inserer un lien vers un élément de la documentation dans n'importe quel texte | package, classe, interface, methode, champ |
1.2
|
| @param | permet de préciser un paramètre de l'élément | constructeur et méthode |
1.0
|
| @see | permet de préciser un élément en relation avec l'élément documenté | package, classe, interface, champ |
1.0
|
| @serial | classe, interface |
1.2
|
|
| @serialData | methode |
1.2
|
|
| @serialField | classe, interface, |
1.2
|
|
| @since | permet de préciser depuis quel version l'élément aété ajouté | package, classe, interface, méthode et champ |
1.1
|
| @throws | identique à @exception | méthode |
1.2
|
| @version | permet de préciser le numéro de version de l'élément | classe et interface |
1.0
|
| @return | permet de préciser la valeur de retour d'un élément | méthode |
1.0
|
Ce tag permet de préciser le nom du ou des auteurs du code. Ce tag doit être utilisé uniquement pour un élement de type classe ou interface.
La syntaxe est la suivante :
@author nom_de_l_auteur
Ce tag génère une entrée Author: avec le nom de l'auteur dans la documentation. Par défaut, ce tag n'est pas pris en compte par javadoc. Pour qu'il soit pris en compte il faut utiliser l'option -author.
Pour préciser plusieurs noms, il faut les séparer par une virgule ou utiliser plusieurs tags chacun contenant un nom.
Ce tag permet de donner des précisions sur un élément déprécié (deprecated).
Ce tag doit être utilisé uniquement pour un élement de type classe ou interface.
La syntaxe est la suivante :
@deprecated explication
Il est utile de préciser depuis quelle version l'élément est déprécié et de préciser si un autre élément le remplace.
Ce tag génère une entrée Deprecated avec l'explication dans la documentation.
Ce tag est particulier car il est le seul reconnu par le compilateur : celui ci prend note de cet attribut lors de la compilation pour permettre d'informer les utilisateurs de cet élément.
Ce tag permet de fournir des informations sur une exception qui peut être levée. Il faut le faire suivre du nom complétement qualifié de l'exception et d'une description des conditions de sa levée.
Ce tag doit être utilisé uniquement pour un élement de type méthode.
La syntaxe est la suivante :
@exception nom_de_la_classe description_de_l_exception
Exemple extrait de la documentation de l'API du JDK :
Il faut utiliser un tag @exception pour chaque exception déclarée dans la signature de la méthode.
Ce tag permet de fournir des informations sur les paramètres. Ce tag doit être utilisé uniquement pour un élement de type constructeur ou méthode.
La syntaxe est la suivante :
@param nom_du_parametre description_du_parametre
Ce tag génère une ligne dans la section Parameters: avec son nom et description dans la documentation. La description peut tenir sur plusieurs lignes.
Exemple extrait de la documentation de l'API du JDK :
Par défaut, ce tag n'est pas pris en compte par javadoc. Pour qu'il soit pris en compte il faut utiliser l'option -author.
Il faut utiliser un tag @param pour chaque paramètre en respectant l'ordre des paramètres dans la signature.
Ce tag permet de préciser la valeur de retour. Ce tag doit être utilisé uniquement pour un élement de type méthode qui renvoie une valeur.
La syntaxe est la suivante :
@return description_retour
Ce tag génère une ligne dans la section Returns: avec sa description dans la documentation. La description peut tenir sur plusieurs lignes.
Exemple extrait de la documentation de l'API du JDK :
Ce tag permet de définir des liens vers d'autres éléments de l'API.
Ce tag permet de preciser depuis quelle version l'élément est utilisable. Ce tag peut être utilisé avec tous les élements.
La syntaxe est la suivante :
@since numero_de_version
Ce tag génère une ligne dans la section Since: avec son numéro de version.
Exemple extrait de la documentation de l'API du JDK :
Ce tag est équivalent au tag @exception
Ce tag permet de préciser la version d'un élément. Ce tag doit être utilisé uniquement pour un élement de type classe ou interface.
La syntaxe est la suivante :
@version description_de_la_version
Ce tag génère une entrée Version: avec la description de la version dans la documentation. Par défaut, ce tag n'est pas pris en compte par javadoc. Pour qu'il soit pris en compte il faut utiliser l'option -version.
Javadoc permet de fournir un moyen de documenter les packages car ceux ci ne disposent de code source particulier : définir des fichiers dont le nom est particulier.
Ces fichiers doivent être placé dans le répertoire désigné par le package.
Le fichier package.html contient une description du package au format HTML. En plus, il est possible d'utiliser les tags @deprecated, @link, @see et @since.
Le fichier overview.html permet de fournir un résumé de plusieurs packages au format html. Ce fichier doit être placé dans le répertoire qui inclus les packages décrits.