Javadoc

Javadoc

Capture d'écran de la javadoc de Java SE 11

Informations

Développé par	Sun Microsystems
Supporte les langages	Java
Environnement	Machine virtuelle Java
Type	Générateur de documentation
Licence	Licence publique générale GNU
Site web	www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

Javadoc est un outil développé par Oracle, permettant de créer une documentation d'API en format HTML depuis les commentaires présents dans un code source en Java.

Conçu à l'origine par Sun MicroSystems (avant son rachat par Oracle), javadoc est le standard industriel pour la documentation des classes Java. La plupart des IDE génèrent automatiquement la javadoc au format HTML.

Tags Javadoc

Lorsqu'ils commentent le code-source, les développeurs Java peuvent signaler qu'un commentaire doit être intégré dans la documentation à l'aide d'une syntaxe spéciale. Un bloc de commentaire Java commençant par /** deviendra un bloc de commentaire Javadoc qui sera inclus dans la documentation du code source. Les commentaires Javadoc précèdent généralement les déclarations de classes, d'attributs et de méthodes. Il est également possible de décrire un paquetage, en créant un fichier package-info.java dans le dossier correspondant, dans lequel on inclut un commentaire Javadoc.

Un tag Javadoc commence par une @ (arobase). Le tableau suivant présente certains des tags les plus courants :

Tag	Description
@author	Nom du développeur
@deprecated	Marque la méthode comme dépréciée. Certains IDE créent un avertissement à la compilation si la méthode est appelée.
@exception	Documente une exception lancée par une méthode — voir aussi @throws.
@param	Définit un paramètre de méthode. Requis pour chaque paramètre.
@return	Documente la valeur de retour. Ce tag ne devrait pas être employé pour des constructeurs ou des méthodes définies avec un type de retour void.
@see	Documente une association à une autre méthode ou classe.
@since	Précise à quelle version de la SDK/JDK une méthode a été ajoutée à la classe.
@throws	Documente une exception lancée par une méthode. Un synonyme pour @exception disponible depuis Javadoc 1.2.
@version	Donne la version d'une classe ou d'une méthode.

Exemple

Un exemple d'utilisation de Javadoc pour documenter une méthode :

/**
 * Valide un mouvement de jeu d'Echecs.
 * @param leDepuisFile   File de la pièce à déplacer
 * @param leDepuisRangée Rangée de la pièce à déplacer
 * @param leVersFile     File de la case de destination 
 * @param leVersRangée   Rangée de la case de destination 
 * @return vrai (true) si le mouvement d'échec est valide ou faux (false) sinon
 */
 boolean estUnDeplacementValide(int leDepuisFile, int leDepuisRangée, int leVersFile, int leVersRangée)
 {
     ...
 }

Un exemple d'utilisation de Javadoc pour documenter une classe :

/**
 * Classe de gestion d'étudiants
 * @author John Doe
 * @version 2.6
 */
 public class Etudiant
 {
   ...
 }

Javadoc fournit également une API pour créer des doclets et des taglets, qui permettent d'analyser la structure d'une application de Java. C'est grâce à cela que JDiff peut produire des rapports de ce qui a changé entre deux versions d'une API.

Toutefois, le concept ne permet de produire la doc de l'API que dans une seule langue.

Annexes

Articles connexes

• Doxygen
• PHPDoc
• Java

Liens externes

• (en) JSR 260, spécifications du balisage Javadoc