Javadoc - Cedric

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.
*
entier premier paramètre
* @param x
chaı̂ne de caractères second paramètre
* @param y
@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