I. L`outil JAVADOC
publicité
Manuel simplifié JAVADOC
I-MAP
18/04/2017
Emetteur : Samuel Kauffmann
Projet I-MAP
Manuel simplifié JAVADOC
Diffusion
Fonctions / Entreprise
Nb
Destinataire
Sébastien ARNOLD
Chargé de projet - ITIN
1
X
Samuel KAUFFMANN
Chargé de projet - ITIN
1
X
Thuong LUU NGUYEN
Chargé de projet - ITIN
1
X
Julien BERNARDO
Chargé de projet - ITIN
1
X
Frank GLANDY
Chargé de projet - ITIN
1
X
Christelle CHAN
Chargé de projet - ITIN
1
X
Version
0.1
Date
Auteur
12/04/2006
Copie
Remarque
Samuel KAUFFMANN
Création du document
Auteur :
Client
Document
Page :
Samuel KAUFFMANN
Claude DAVIAU
Manuel
1/5
Manuel simplifié JAVADOC
I-MAP
18/04/2017
Sommaire
I.
L'OUTIL JAVADOC
3
II.
INSERER UN COMMENTAIRE
3
III.
COMMENT DOCUMENTER ?
3
A.
DOCUMENTER UNE CLASSE
3
B.
DOCUMENTER UNE METHODE
4
C.
DOCUMENTER UN ATTRIBUT
4
IV.
LISTE DES DIFFERENTES BALISES
4
V.
GENERER LA DOCUMENTATION
5
A.
INTRODUCTION
5
B.
EXEMPLE
5
Auteur :
Client
Document
Page :
Samuel KAUFFMANN
Claude DAVIAU
Manuel
2/5
Manuel simplifié JAVADOC
I-MAP
18/04/2017
I. L'outil JAVADOC
Cet outil est fournit par défaut avec le JDK. Il permet de générer des fichiers de
documentations (au format HTML, RTF, PDF...) à partir de votre code Java. Son utilisation est très
simple. Il vous demande de lui spécifier un ensemble de fichiers Java à documenter. A partir de là le
reste se fait tout seul, pourvu que vous ayez semez un peu d'information dans les fichiers de code. Un
certain nombre de fichiers sont générés et permettent la navigation parmi toutes les classes
documentées. Le fichier de départ se nomme alors index.html.
II. Insérer un commentaire
Pour commenter un code, vous devez placer votre commentaire avant celui-ci.
La déclaration de documentation JAVADOC commence par /** et est suivie par un commentaire libre,
ensuite vous pouvez placer différentes baliser permettant d'approfondir la description.
Seul les classes, propriétés et méthodes publiques sont commentées avec le style JAVADOC. Le
reste doit être commenté en utilisant les commentaires standard JAVA.
/* Ceci est un commentaire classique hérité du langage C
Il peut s'étendre sur plusieurs lignes.
*/
// Ceci est un commentaire classique hérité de C++
// Ce type de commentaire ne peut pas s'étendre sur plusieurs lignes
/** Et là nous avons un commentaire javadoc. Comme vous le
* remarquez, il commence par les caractères /**.
* Il peut s'étendre sur plusieurs lignes
*/
III.Comment documenter ?
A. Documenter une classe
Pour documenter une classe vous devez insérer les commentaires après la liste de vos imports et
avant la déclaration de votre classe.
@import fr.i-map.plugins
/**
*
*
*
*
*
*/
Cette classe est la classe de gestion de plugin
@see Plugin
@see Core
@version 1.1
@since 1.0
@author Samuel KAUFFMANN, Franck GLANDY
class Manager {
Auteur :
Client
Document
Page :
Samuel KAUFFMANN
Claude DAVIAU
Manuel
3/5
Manuel simplifié JAVADOC
I-MAP
18/04/2017
B. Documenter une méthode
Vous devez placer votre commentaire avant la déclaration de la méthode. Vous pouvez spécifier le
nom de l'auteur, une description sur les paramètres reçus, la valeur retourné, les exceptions levés par
votre méthode...
/** Cette méthode permet de créer un Objet
* @param Type a Type de l'objet à créer
* @author Samuel Kauffmann
* @return En retour, vous récupérez l'objet créé
* @see Objet
* @see Manager
* @throws ObjetExeception, TypeExeception
*/
public Objet create(Type type) {
}
C. Documenter un attribut
Vous pouvez documenter les attributs d'une classe.
/** Cette attribut permet d'activer ou non le débogage de la classe.
*/
public Boolean debug = true;
IV. Liste des différentes balises
Dans n'importe quelle balise JAVADOC, vous pouvez insérer du code HTML (<br/>, <p></p>,
<u></u>...). Il est toutefois déconseillé d'utiliser les codes de gestion de paragraphes (<h1>...) pour ne
pas rentrer en conflit avec les styles générés par la JAVADOC.
@author [NOM]
Vous devez placer un ou plusieurs nom après la baliser afin d'identifier le ou les auteurs du code.
@deprecated [RAISON]
Cette balise est utilisée pour signaler que la classe ou la méthode décrite est déconseillé. Le code
n'est pas supprimer pour éviter le disfonctionnement des objets qui utilisent le code décris.
@param [NOM] [DESCRIPTION]
Vous pouvez décrire les paramètres reçus par votre méthode en utilisant cette balise.
@return [DESCRIPTION]
Vous décrivez le type de retour renvoyé par votre méthode.
@see [NOM / URL]
Permet de créer un lien "plus d'informations" dans la page JAVADOC. Vous pouvez ainsi conseiller au
lecteur de la documentation de lire la documentation d'une méthode utilisée par votre classe pour
obtenir plus d'information.
Auteur :
Client
Document
Page :
Samuel KAUFFMANN
Claude DAVIAU
Manuel
4/5
Manuel simplifié JAVADOC
I-MAP
18/04/2017
@throws [NOM DE L'EXECPTION] [DESCRIPTION]
Vous permet d'indiquer à l'utilisateur de votre méthodes quelles exceptions sont levés dans votre code
et dans quels cas.
@version [NUMERO]
Cette balise permet d'indiquer le numéro de version du code que vous commenté. Il est formé comme
ceci :
NUMERO_MAJEUR.NUMERO_MINEUR.REVISION
Par exemple :
* @version 0.0.1
V. Générer la documentation
A. Introduction
L'exécution de JavaDoc s'effectue par l'intermédiaire de l'invite de commande. Il suffit de
taper le mot " javadoc " puis la liste des fichiers " .java ", séparés par des espaces, dont
l'utilisateur souhaite générer la documentation. Quelques options permettent d'affiner la
génération de la documentation, celles-ci s'insèrent entre " javadoc " et la liste des fichiers à
convertir. Le nom d'une option est toujours précédé d'un tiret.
Options les plus couramment utilisées :
" -d ", suivit d'un nom de répertoire, permet de choisir le répertoire dans lequel sera
générée la documentation. Le répertoire doit être préalablement créé.
" -author " permet de prendre en compte le paramètre @author lors de la génération de
la documentation.
" -version " permet de prendre en compte le paramètre @version lors de la génération
de la documentation.
" -classpath " suivit de l'adresse des bibliothèques, permet à javadoc de générer la
documentation en connaissant les caractéristiques des types étrangers à la classe.
" -public " permet de générer la documentation uniquement pour les classes publiques.
" -protected " permet de générer la documentation pour les classes et membres publics
et protégés. C'est l'option par défaut.
" -package " permet de générer la documentation pour les classes et membres publics,
protégés et ceux accessibles aux classes d'un même package.
" -private " génère la documentation pour toutes les classes et tous les membres.
B. Exemple
La commande " javadoc -d doc -author -private Exemple.java " génère la documentation, dans le
répertoire doc, du fichier Exemple.java. Le paramètre @author est pris en compte et toutes les
classes du fichier et leurs membres sont documentés.
Auteur :
Client
Document
Page :
Samuel KAUFFMANN
Claude DAVIAU
Manuel
5/5
