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.
Après avoir compléter les méthodes suivantes :
Voilà ce que nous obtenons :
Commentaires d'attribut
Seules les attributs publics doivent être documentés, c'est-à-dire généralement des constantes statiques :
/**
* Nombre maximum de notes stockées dans le tableau
*/
public static final NotesMax = 20;
Commentaires généraux
Javadoc connait un certain nombre de balises particulières, chacunes d'elles commençant par un caractère @. Ces balises de commentaire de documentation vous
permettent d'encoder d'une manière normalisée des informations spécifiques au sein de vos commentaire, et elles permettent à Javadoc de choisir le format approprié pour
afficher ces informations. Par exemple, comme nous l'avons vu, la balise @param vous permet de spécifier le nom et la signification d'un paramètre d'une méthode.
Balise
Description
Type de balise
@author nom
Ajoute une entrée Auteur avec le nom spécifié aux documents générés quand l'option @author est sélectionnée. Cette
balise peut être utilisée avec toutes les définitions de classes et d'interfaces, mais pas avec des méthodes et des
attributs individuels. Il peut y avoir plusieurs balises @author pour chaque auteur.
Présentation, paquet,
classe, interface
@version numéro
de version
Ajoute un sous-titre Version avec le numéro de version spécifié aux documents générés quand l'option @version est
utilisée.
Présentation, paquet,
classe, interface
@deprecated texte
désapprouvé
Cette balise ajoute un commentaire signalant que la classe, la méthode ou l'attribut est dépréciée et ne doit plus être
utilisée. Le texte doit suggérer une solution de remplacement. Par exemple :
@deprecated Utiliser <code>setVisible(true)</code> à la place
@since texte
Cette balise crée une entrée "depuis" (since). Le texte peut être toute description de la version ayant introduit cette
fonctionnalité. Par exemple @since version 1.7.1
Paquet, classe, interface,
champ, constructeur,
méthode
Paquet, classe, interface,
champ, constructeur,
méthode
Vous pouvez ajoutez des liens hypertexte vers d'autres parties connexes de la documentation javadoc, ou vers
d'autres documents externes, à l'aide la balise @see et @link
Cette balise @see ajoute un lien hypertexte dans la section "see also" (voir aussi). Elle peut être employée avec les
classes et les méthodes. Ici, référence peut être l'un des choix suivants :
@see javabean.Texte#getMessageBienvenue()
Cette première possibilité est la plus utile. Vous fournissez le nom d'une classe, d'une méthode ou d'une variable, et
javadoc insère un lien hypertexte vers la documentation. L'exemple ci-dessus crée un lien vers la méthode
getMessageBienvenue() dans la classe javabean.Texte. Vous pouvez omettre le nom du paquetage ou à la fois les
noms de paquetage et de classe. La fonctionnalité est alors recherchée dans le paquetage ou la classe courants.
@see référence
Notez que vous devez utiliser un #, et non un point, pour séparer la classe du nom de la méthode ou de la
variable. Le compilateur java lui-même est assez futé pour déterminer la signification du caractère point,
comme séparateur entre les paquetages, les sous-paquetages, les classes, les classes internes, et les
méthodes de variables. L'utilitaire javadoc, lui, n'est pas aussi pointu, et vous devez l'aider.
Présentation, paquet,
classe, interface, champ,
constructeur, méthode
Si la balise @see est suivie d'un caractère <, vous devez spécifier un lien hypertexte. Le lien peut concerner n'importe
quelle adresse URL :
@see <a href="http://emmanuel-remy.developpez.com" >Développement réseau</a>
Dans chaque cas, vous pouvez spécifier un label facultatif, qui apparaîtra en tant qu'ancre du lien. Si vous omettez le
label, le nom du code cible ou l'URL apparaîtron à l'utilisateur en tant qu'ancre.
Si la balise @see est suivi du caractère ", le texte s'affiche dans la section "see also" :
@see"Revoir la programmation réseau"
{@link
paquet.classe#
membre libellé}
Vous pouvez aussi placer les liens hypertexte vers d'autres classes ou méthodes, n'importe où dans vos
commentaires. La description de la fonctionnalité suit les mêmes règles que pour la balise @see.
Présentation, paquet,
classe, interface, champ,
constructeur, méthode
Commentaires de paquetage et d'ensemble
Vous placez les commentaires de classe, de méthode et d'attributs directement dans les fichiers source Java, délimités par les commentaires de documentation /** ... */.
Toutefois, pour générer des commentaires de paquetage, vous devez ajouter un fichier séparé dans chaque répertoire de paquetage.
Deux choix s'offrent à vous :
1. Fournir un fichier HTML intitulé package.html. Tout le texte entre les balises <body> ... </body> est extrait.
2. Fournir un fichier Java nommé package-info.html. Le fichier doit contenir un commentaire Javadoc initial, délimité par /** et */ et suivi d'une instruction package. Il
ne doit contenir aucun code ou commentaire.
Vous pouvez aussi fournir un commentaire d'ensemble pour tous les fichiers source. Placez-le dans un fichier appelé overview.html, situé dans le répertoire parent
qui contient tous les fichiers source. Tout le texte entre les balises <body> ... </body> est extrait. Ce commentaire de vue d'ensemble s'affiche lorsque l'utilisateur
sélectionne "Overview" dans la barre de navigation.