Commentaires -

Introduction
Syntaxe de Javadoc
Génération de documentation
Commentaires – Javadoc
Outils de génie logiciel
14 avril 2009
1 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Commentaire
Objectifs
◮ Facilite la compréhension de code ancien
◮
Facilite l’utilisation par d’autres personnes
2 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Documentation d’API
◮
Documentation de code sous forme de pages HTML
◮
Liens hypertextes pour faciliter la navigation
◮
Génération automatique à partir de commentaires
◮
Javadoc, Doxygen
3 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Commentaires Javadoc
◮
Délimités par /** et */
◮
Lignes intermédiaires commençant par *
◮
Documentation de classes, méthodes et attributs
◮
Formatage HTML et balises Javadoc (introduite pas @)
4 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Commentaire sans balise
Exemple
/**
* Description de l’attribut.
*/
private int valeur ;
5 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@author et @version
Auteur de la classe et numéro de version
/**
* Classe permettant...
* @author John Doe
* @version 4.2
*/
public class Exemple {
...
}
6 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@param et @return
Paramètres et valeur retournée d’une méthode
/**
* Addition de deux entiers.
* @param a Le premier entier.
* @param b Le second entier.
* @return La somme de a et de b.
*/
public int addition (int a, int b) {
return a + b ;
}
7 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@param et @return
Méthode void
/**
* Addition d’un autre entier.
* @param e Un entier à additionner.
*/
public void addition (Entier e) {
this.valeur = e.valeur ;
}
7 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@param et @return
Méthode sans paramètre
/**
* Renvoie la valeur de l’entier.
* @return La valeur de l’entier.
*/
public int valeur () {
return this.valeur ;
}
7 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@throws
Exception
/**
* Division entière.
* @param a Le premier entier.
* @param b Le second entier.
* @return Le résulat de la division entière de a
par b.
* @throws ArithmeticException Lorsque b vaut 0.
*/
public int division (int a, int b) throws
ArithmeticException {
return a / b ;
}
8 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@see
Référence à une classe
/**
* Classe représentant un enseignant.
* @author John Doe
* @version 4.2
* @see Etudiant
* @see Cours
*/
public class Enseignant extends Personne {
...
}
9 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@see
Référence à une méthode
/**
* Recherche du zéro d’une fonction par dichotomie.
* @param f Une fonction mathématique.
* @param intervalle L’intervalle de recherche.
* @param epsilon Le seuil de précision.
* @return Le zéro de la fonction.
* @see Fonction#valeur (double)
* @see Algorithme#NewtonRaphson (Fonction, double)
*/
public double dichotomie (Fonction f, Intervalle
intervalle, double epsilon) {
...
}
10 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@since
Version d’apparition
/**
* Méthode d’initialisation.
* @since 4.2
*/
public void initialisation () {
...
}
11 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
@deprecated
Dépreciation
/**
* Méthode d’affichage.
* @deprecated Remplacé par affichageTexte ().
*/
public void affichage () {
...
}
12 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Commande javadoc
javadoc -sourcepath src -d docs/api -subpackages
exemple
Options
◮ Lien vers l’API Java : -link
http ://java.sun.com/javase/6/docs/api/
◮
Version de Java : -source 1.6
◮
Titre : -windowtitle "Titre"
◮
Uniquement les classes et membres publics : -public
◮
Toutes les classes et tous les membres : -private
13 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Doclets
Doclets
◮ Modification du comportement de Javadoc
◮
Programme Java :
public static boolean start (RootDoc doc) {
...
}
◮
Options Javadoc :
-docletpath exemple.jar -doclet exemple.Exemple
Doclets utiles
◮ DocCheck : rapport sur la cohérence du code
◮
PDFDoclet : Génération de la javadoc dans un document PDF
14 / 15
Introduction
Syntaxe de Javadoc
Génération de documentation
Questions
15 / 15