Commentaires - Javadoc

Chapitres traités   

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.

 

Choix du chapitre Insertion des commentaires

L'utilitaire javadoc extrait les informations concernant les éléments suivants :

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.

 

Choix du chapitre 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 :

 

Choix du chapitre 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/
§

 

Choix du chapitre 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 :

 

Choix du chapitre 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 :

 

Choix du chapitre 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;

 

Choix du chapitre 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
Paquet, classe, interface, champ, constructeur, méthode
@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
@see référence

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.

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.

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"

Présentation, paquet, classe, interface, champ, constructeur, méthode
{@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

 

Choix du chapitre 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.