Introduction à la javadoc

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