Introduction Exemples Création javadoc

Javadoc
Création de documention en Java
Cours Java - F. Michel
1 / 20
Introduction Exemples Création javadoc

Plan

1 Introduction à la Javadoc

2 Exemples

3 Création javadoc : ligne de commande / Eclipse

Cours Java - F. Michel

2 / 20
Introduction Exemples Création javadoc

Introduction Javadoc

Le programme javadoc
javadoc est le 3e programme essentiel fourni avec le SDK (java, javac).

C’est l’outil qui sert à générer la documentation au format de Sun (API).

Il permet donc à un tiers d’utiliser vos programmes et vos librairies de

manière simple et efficace.

Cela permet aussi au programmeur de s’y retrouver plus rapidement !

Utiliser cet outil est fondamental pour programmer en Java.

Les commentaires pour la javadoc : /** . . . */

/**
* documentation pour méthode/classe/attributs/paramètres/etc.
*/

Cours Java - F. Michel

4 / 20
Introduction Exemples Création javadoc

Exemple de javadoc

Personne.java

package cours . javadoc ;

/∗∗
∗ La c l a s s e personne modelise une personne .
∗ E l l e s e r t pour . . .
∗
∗ @see NegativeAgeException
∗ @author f a b
∗/
p u b l i c c l a s s Personne implements Cloneable {
/∗∗
∗ l ’ age de l a personne , d o i t e t r e p o s i t i f
∗/
p r i v a t e i n t age ;
/∗∗
∗ l e nom de l a personne , une s i m p l e chaine de c a r a t e r e s
∗/
p r i v a t e S t r i n g name ;

Cours Java - F. Michel

6 / 20
Introduction Exemples Création javadoc

Exemples

Personne.java

/∗∗
∗ C o n s t r u c t e u r pour l a c l a s s e Personne .
∗ Blabla . . .
∗
∗ @param age un e n t i e r >= 0
∗ @param name l e nom de l a personne
∗ @throws NegativeAgeException s i age < 0
∗/
p u b l i c Personne ( i n t age , S t r i n g name ) throws NegativeAgeException {
t h i s . setAge ( age ) ;
t h i s . name = name ;
}

Cours Java - F. Michel

7 / 20
Introduction Exemples Création javadoc

Exemples

Personne.java

/∗∗
∗ M o d i f i e l ’ age de l a personne .
∗
∗ @param age un e n t i e r >= 0
∗ @throws NegativeAgeException s i age < 0
∗/
p u b l i c v o i d setAge ( i n t age ) throws NegativeAgeException {
i f ( age < 0 ) {
throw ( new NegativeAgeException ( " e r r e u r : l ’ age d o i t e t r e > 0 , "
+ " v a l e u r e n t r e e : " +age ) ) ; / / s o r t de l a methode
}
t h i s . age = age ;
}

Cours Java - F. Michel

8 / 20
Introduction Exemples Création javadoc

Exemples

Personne.java

@Override
/∗∗
∗ cree une r e p r e s e n t a t i o n sous forme de s t r i n g de l ’ o b j e t
∗ personne
∗ @return une chaine de c a r a c t e r e s
∗/
public String toString () {
r e t u r n name+ " age : " +age ;
}
}

Cours Java - F. Michel

9 / 20
Introduction Exemples Création javadoc

Exemples
NegativeAgeException.java

package cours . javadoc ;

/∗∗
∗ E x c e pt i o n generee l o r s d ’ une mauvaise
∗ u t i l i s a t i o n de l a methode { @link Personne#setAge ( i n t ) } .
∗
∗ @author f a b
∗ @see Personne
∗/
p u b l i c c l a s s NegativeAgeException extends E x c ep t i o n {

/∗∗
∗ c o n s t r u c t e u r pour l ’ e x c e p t i o n
∗ @param message l e message d ’ e r r e u r
∗/
p u b l i c NegativeAgeException ( S t r i n g message ) {
super ( message ) ;
}
}

Cours Java - F. Michel

10 / 20
Introduction Exemples Création javadoc

Javadoc pour un package

Il faut ajouter, dans le répertoire du package, un fichier appelé

package-info.java et structuré comme suit :

package-info.java

/∗∗
∗ Give t h e summary o f what t h e package a l l o w s t o do .
∗ And more d e t a i l s here . b l a b l a . . .
∗
∗ @since P r o j e c t 1 . 0
∗ @author f a b
∗ @version 1 . 1
∗
∗/
package cours . javadoc ;

Cours Java - F. Michel

11 / 20
Introduction Exemples Création javadoc

Utilisation du programme javadoc

En ligne de commande :
option -sourcepath : racine des sources (= packages)
option -d : répertoire destination
arguments : noms de package (prog.nompackage) et/ou noms de fichiers
.java

Exemple

javadoc −sourcepath s r c −d doc cours . javadoc

Cours Java - F. Michel

13 / 20
Introduction Exemples Création javadoc

Plusieurs niveaux de visibilité possibles

option -public : seuls les membres public

option -protected : seuls les membres public/protected

option -package : seuls les membres public/protected/package

option -private : tout !

Exemple

javadoc − p r i v a t e −sourcepath s r c −d doc cours . javadoc

Cours Java - F. Michel

14 / 20
Introduction Exemples Création javadoc

Liaison avec d’autres javadoc

Objet : créer des hyperliens avec d’autres javadoc

option -link : liaison avec des API externes

javadoc − l i n k h t t p : / / download . o r a c l e . com / j a v a s e / 7 / docs / a p i

− p r i v a t e −sourcepath s r c −d doc cours . javadoc

Cours Java - F. Michel

15 / 20
Introduction Exemples Création javadoc

Options liées à l’encodage des caractères

-docencoding encodingType : encodage utilisé pour les

fichiers html (i.e. ISO-8859-1 ou UTF-8). Valeur de l’OS si absent.

-encoding encodingType : spécifie l’encodage des fichiers

sources (valeur de l’OS si absent)

-charset encodingType : ajoute dans le source HTML l’header

Content-Type avec l’encodage utilisé.

Exemple sous linux (UTF-8 par défaut pour l’OS)

javadoc −c h a r s e t UTF−8 −sourcepath s r c −d doc cours . javadoc

Résultat

Cours Java - F. Michel

16 / 20
Introduction Exemples Création javadoc

Sous Eclipse
File → Export → Javadoc →

Cours Java - F. Michel

17 / 20
Introduction Exemples Création javadoc

Sous Eclipse
→ Next

Cours Java - F. Michel

18 / 20
Introduction Exemples Création javadoc

Sous Eclipse
→ Next

Cours Java - F. Michel

19 / 20
Introduction Exemples Création javadoc

Quelques tags pour la javadoc

plus d’information

Cours Java - F. Michel

20 / 20