Commentaires - Javadoc - programmer en java, programme java

Commentaires - Javadoc
Chapitres traités
Insertion des commentaires
Le JDK contient un outil très utile, appelé javadoc, qui génère une documentation automatique au format HTML à partir de vos fichiers
source. En fait, la documentation de l'API donnée avec la JDK est simplement le résultat de l'exécution javadoc sur le code source de la
bibliothèque Java standard.
Si vous ajoutez des commentaires commençant par le délimiteur spécial /** à votre code source, vous pouvez générer facilement une
documentation d'aspect très professionnel. Ce système est astucieux, car il permet de conserver votre code et votre documentation au
même endroit.
Si votre documentation se trouve dans un fichier séparé, le code et les commentaires divergeront fatalement à un moment donné. Mais puisque les commentaires de
documentation sont dans le même fichier que le code source, il est facile de les mettre à jour en même temps et d'exécuter javadoc.
Insertion des commentaires
L'utilitaire javadoc extrait les informations concernant les éléments suivants :
Les paquetages ;
Les classes publiques et les interfaces ;
les méthodes publiques et protégées ;
les attributs publics et protégés ;
Vous pouvez (et devez) fournir un commentaire pour chacune de ces fonctionnalités. Chaque commentaire doit être placé immédiatement au dessus de la
fonctionnalité qu'il décrit. Un commentaire commence par /** et se termine par */.
Chaque séquence /** ... */ contient un texte au format libre suivi par des balises. Une balise commence par un @, comme par exemple, @author ou @param.
La première phrase du commentaire au format libre doit être une instruction de sommaire. L'utilitaire javadoc génère automatiquement les pages de sommaire qui
extraient ces phrases.
Dans le texte libre, vous pouvez utiliser des balises HTML, telle que <em>...</em> pour insister, <code>...</code> pour une police à espacement fixe, <strong>...</
strong> pour des caractères gras, et même <img ...> pour inclure une image. Evitez cependant les balises <h1> ou <hr> qui peuvent interférer avec la mise en forme
du document.
Visualisation de la documentation Javadoc
Avant de voir comment construire nos propres commentaires, je vous propose tout de suite de voir le résultat, et ainsi de naviguer sur les fichiers HTML produits par
l'utilitaire javadoc sur des classes que nous avons déjà mises en oeuvres.
L'utilitaire javadoc produit un certain nombre de fichiers HTML suivant le nombre de classes à décrire :
Pour visualiser la documentation javadoc de l'ensemble du projet, il suffit de double-cliquez sur index.html.

La liste des paquets et classes se trouve dans le cadre de gauche. Le cadre de droite affiche les tableaux récapitulatifs. Pour l'instant, la partie droite du tableau des
classes est vierge puisque nous n'avons apporté aucun commentaire particulier dans le code source.
Vous avez ci-dessous un certain nombre de vues qui vous montrent l'ensemble des pages HTML créées :

Extraction des commentaires
Voyons maintenant comment utiliser l'utilitaire javadoc afin de réaliser les pages HTML ci-dessus.
Ici, répertoireDocuments est le nom du répertoire où vous désirez stocker les fichiers HTML. Voici les étapes à suivre :
1. Positionnez-vous dans le répertoire contenant les fichiers sources à documenter. Si vous devez documenter des paquetages imbriqués, tel que
com.javabean.Texte, vous devez vous trouvez dans le répertoire qui contient le sous-répertoire com.
2. Exécutez la commande :
javadoc -d répertoireDocuments nomDuPaquetage
pour un paquetage simple. Ou exécutez :
javadoc -d répertoireDocuments nomDuPaquetage1 nomDuPaquetage2
pour documenter plusiseurs paquetages. Si vos fichier se trouvent dans le paquetage par défaut, exécutez :
javadoc -d répertoireDocuments *.java
à la place.
Si vous avez omis l'option -d répertoireDocuments, les fichiers HTML sont extraits du répertoire courant. Cela peut devenir compliqué et n'est pas recommandé.
§
Le programme javadoc peut être personnalisé par de nombreuses options de ligne de commande. Vous pouvez, par exemple, employer les options -author et -version
pour inclure les balises @author et @version dans la documentation (elles sont omises par défaut). Une autre option utile est -link, pour inclure des liens hypertexte
vers les classes standard.
Par exemple, si vous utilisez la commande suivante, toutes les classes sont automatiquement liées à la documentation du site Web de Sun :
javadoc -link http://java.sun.com/javase/6/docs/api *.java
Pour découvrir d'autres options, vous pouvez consulter la documentation en ligne de l'utilitaire javadoc à l'adresse http://java.sun.com/javase/javadoc/
§
Commentaires de classe
Nous venons de découvrir toute la procédure pour créer ces pages HTML. Toutefois maintenant, il nous incombe d'écrire effectivement les commentaires associées aux
classes dans le code source afin d'obtenir le résultat requis.
Un commentaire de classe doit être placé après les instructions import, juste avant la définition class.
package javabean;
import java.awt.*;
import javax.swing.JLabel;
import java.awt.event.*;
/**
* <p><strong>Description :</strong> Il s'agit d'un texte qui peut se

* déplacer à l'aide de la souris et qui peut également
* changer de couleur dans la fenêtre principale de
* l'application <strong><em>Cadre</em></strong></p>
* @see Cadre
*/
public class Texte extends JLabel implements MouseListener, MouseMotionListener {
private int x, y;
private String messageBienvenue;
private java.awt.Color couleurSurvol;
private java.awt.Color couleurNormale;
...
}
Après cette simple écriture, voici effectivement ce que nous pouvons obtenir :
Commentaires de méthode
Chaque commentaire de méthode doit immédiatement précéder la méthode qu'il décrit. En plus des balises générales, vous pouvez utiliser les balises suivantes :
1. @param : Cette balise ajoute une entrée à la section paramètre de la méthode courante. La description peut occuper plusieurs lignes et avoir recours aux balises
HTML. Attention, toutes les balises @param pour une même méthode doivent être regroupées.
2. @return : cette balise ajoute une section renvoie (return) à la méthode courante. La description peut occuper plusieurs lignes et avoir recours aux balises HTML.
3. @throws : Cette balise ajoute une note concernant le déclenchement possible d'une exception par la méthode.