Javadoc 1 Générer une documentation avec Javadoc Outil Javadoc outil standard Java permet de générer une documentation HTML pour un ensemble de classes Java Utilisation : La syntaxe d appel a plusieurs variantes, couvrant différents cas de figure : un ou plusieurs paquetages, une ou plusieurs classes, etc. Pour générer la documentation pour un ensemble de classes : % javadoc -d répertoire doc liste classes répertoire doc : répertoire où la documentation générée sera placée liste classes : liste de fichiers source contenant les classes pour lesquelles on génère la documentation 1
Exemple : % javadoc -d c: \doc\html c: \prog\*.java génère dans le répertoire c: \doc\html la documentation pour toutes les classes qui se trouvent dans le répertoire c: \prog Remarque : On peut générer la documentation pour un ou plusieurs paquetages, pour plus de détails voir http ://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html 2
2 Le contenu d une documentation Javadoc Dans le répertoire où la documentation est générée, on retrouve un ensemble de fichiers HTML, organisés en sousrépertoires : un fichier pour chaque classe un fichier pour chaque paquetage un sous-réperoire pour chaque paquetage, contenant les fichiers de documentation pour le paquetage et pour les classes de ce paquetage La page d entrée dans la documentation se trouve dans le fichier index.html du répertoire de la documentation. Elle contient : une fenêtre avec la liste de paquetages (en haut à gauche) une fenêtre avec la liste des classes (en bas à gauche) une fenêtre principale, affichant la documentation pour le paquetage courant ou la classe courante 3
Eléments de description d une classe : les classes dont la classe courante hérite une description textuelle de la classe la description succincte des variables d instance ou de classe la description succincte des constructeurs la description succincte des méthodes (d instance ou de classe) la description détaillée des variables, constructeurs et méthodes 4
3 Ecrire une documentation Javadoc Principe : On écrit un commentaire spécial (en format Javadoc) devant l élément documenté (méthode, classe, paquetage, etc). Javadoc transformera ce commentaire en documentation HTML pour l élément en question. Structure d un commentaire Javadoc : le commentaire commence par une ligne contenant /** sur chaque nouvelle ligne, le commentaire commence après un caractère * le commentaire se termine par une ligne contenant */ le texte de description peut contenir plusieurs paragraphes, séparés par un <p> la première phrase de la description sert de description courte pour l élément en question, il faut donc qu elle soit bien choisie. la dernière partie du commentaire contient un ensemble de balises Javadoc, qui commencent par @ la partie balises est séparée par une ligne vide du texte précédent ; il y a une ligne par balise décrite 5
Principale balises Javadoc : @param : suivi du nom du paramètre, description de paramètre de méthode @return : description du résultat retourné par une méthode @exception (ou @throws) : suivi du nom de l exception, décrit une exception levée par une méthode @author : nom de l auteur de la classe @version : numéro de version de la classe Exemple : /** * Classe exemple pour l outil Javadoc. * Cette classe ne sert à rien en particulier. * <p> * Elle ne contient que des exemples de commentaires Javadoc. * * @author Dan Vodislav * @version 1.0 */ public class MaClasse{ /** * Variable d instance exemple. */ private int variable; /** * Méthode exemple qui ne sert que de support. * Elle reçoit deux paramètres, retourne un résultat et * lève une exception. * * @param x entier premier paramètre * @param y chaîne de caractères second paramètre * @return boolean résultat * @throws MonException exception levée */ public boolean mamethode(int x, String y) throws MonException{...} } 6
Remarque : Par défaut, la documentation est générée seulement pour les élémens public et protected. Pour générer la documentation pour différents niveaux de protection, la commande javadoc offre les options suivantes en ligne de commande : option -public : seuls les éléments publics option -protected : seuls les éléments publics et protected (par défaut) option -package : éléments publics, protected et package option -private : tous les éléments Exemple : % javadoc -private -d c: \doc\html c: \prog\*.java 7