Javadoc
Un article de Wikipédia, l'encyclopédie libre.
javadoc est un outil développé par Sun Microsystems permettant de générer une documentation d'API en format HTML depuis un code source Java. Javadoc est le standard industriel pour la documentation des classes Java. La plupart des IDEs générent automatiquement le javadoc HTML.
[modifier] Tags Javadoc
Les développeurs utilisent certains styles de commentaire et des tags Javadoc quand ils documentent un code source. Un bloc de commentaire java commençant par /** deviendra un bloc de commentaire Javadoc qui sera inclus dans la documentation du code source. Un tag Javadoc commence par un "@" (arobase). Quelques tags sont donnés dans le tableau suivant.
-
Tag Description @author Nom du développeur @deprecated Marque la méthode comme dépréciée. Certains IDEs générent 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éfinis avec un type de retour void. @see Documente une association à une autre méthode ou classe. @since Précise à quelle version une méthode à é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.
[modifier] 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) si invalide */ boolean estUnDéplacementValide(int leDepuisFile, int leDepuisRangée, int leVersFile, int leVersRangée) { ... }
Un exemple d'utilisation de Javadoc pour documenter une classe :
/** * Classe de gestion d'étudiant * @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 unique langue.
[modifier] Lien externes
- Javadoc tool web site
- JSR 260 Javadoc Tag Technology Update Java Specification Requests (defines new Javadoc tags)
- Improve on Javadocs with ashkelon
- A collection of Javadoc doclets
- An index to many Javadoc generated websites
- JavadocOnline: projet de moteur de recherche, pour récuperer des javadocs publiques sur Internet
- DocJar: Un autre projet de moteur de recherche, pour récuperer des javadocs publiques sur Internet
- Globaldocs: A viewer to browse multiple Javadocs simultaneously.