Javadoc – Site de Louis Marchand

Introduction

La documentation de code est un des aspects les plus importants de la programmation. Ça permet entre autres de facilement comprendre la mécanique de code, augmente la facilité de navigation dans le projet, diminue le risque de bogues, accélère le débogage des programmes et facilite l’entretient long terme des solutions informatiques.

Java fournit un standard et des outils qui permettent de faciliter la documentation de code et de générer des documents de documentation.

Les documentations sont annotées sous la forme de commentaire débutant avec une ligne:

/**

et se terminant avec la ligne:

*/

Chaque ligne débute par le caractère « * » aligné avec le premier caractère « * » de la première ligne de la documentation. Par exemple:

/**
 * Ceci est une documentation de code.
 */

La première ligne à l’intérieur de l’encadré de documentation correspond toujours à la description courte de la documentation. On peut ensuite mettre une description longue en séparant celle-ci de la description courte par une ligne vide. Par exemple:

/**
 * Ceci est la description courte qui doit être sur une seule ligne.
 *
 * Et ceci est la description longue de la documentation. Il est à noter qu'il
 * est possible de mettre cette dernière sur plusieurs lignes.
 * <p>
 * Il est également possible de mettre des paragraphes à la description longue,
 * ou même des:
 * <ul>
 * <li>Liste
 * <li>d'item
 * </ul>
 * en utilisant des notations similiaires à la syntaxe Web.
 */

On peut voir qu’il est possible de mettre quelques éléments de mise en page qui sera utile lorsque la documentation Web sera générée.

Javadoc fonctionne également avec un système d’étiquette (ou tag) afin de spécifier des éléments précis dans notre documentation. Les étiquettes débutent par « @ ». Voici les principales étiquettes:

- - - « @author »: Spécéfie l’auteur de la classe;
    - « @version »: Spécifie la version de la classe et la date de dernière modification;
    - « @since »: Spécifie la première version de Java que la classe est considérée comme étant fonctionnelle;
    - « {@link référence} »: Permet de mettre une référence dans une description (courte ou longue) vers une classe, méthode, attribut ou référence externe;
    - « @param »: Spécifie un argument d’une routine;
    - « @return »: Spéficie la valeur de retour d’une routine
    - « @throws » ou « @exception »: Spécifie un exception que la routine peut lancer et dans quel contexte ce dernier se lance;
    - « @deprecated »: Indique qu’une classe, méthode ou attribut a été remplacé et ne doit plus être utilisé;
    - « @see »: Spécifie une référence pertinente
      - On peut faire référence à:
        
        Un site Web,
        
        Une classe,
        
        Une méthode ou un attribut (en utilisant la notation « #nom »),
        
        etc.

La documentation de classe

Chaque classe publique (ou chaque fichier Java) doivent avoir un minimum de documentation. Il faut spécifier les informations suivantes:

- Une description courte;
- L’auteur;
- Date et version java.

On y trouve également souvent les informations suivantes:

- Une description longue;
- D’autres auteurs;
- Une licence;
- Référence vers une documentation extérieure.

Voici un exemple qui ne contient qu’une description courte, un auteur, la date et la version java de la classe:

/**
 * Un Animal correspond à un individu dans le programme de gestion vétérinaire.
 * @author Louis Marchand
 * @version 1.39, 01/31/2023
 */

public class Animal {
    ...
}

Voici maintenant un exemple avec plus d’informations:

/**
 * Permet le tri de liste.
 *
 * Cette classe permet de trier des listes en utilisant plusieurs
 * algorithmes de tri.
 * <ul>
 * <li>Tri bulle ({@link Tri#triBulle})
 * <li>Tri insertion ({@link Tri#triInsertion})
 * <li>Tri fusion ({@link Tri#triFusion})
 * <li>Tri rapide ({@link Tri#triRapide})
 * </ul>
 * <p>
 * Le tri bulle est un algorithme d'ordre n^2 qui consiste à comparer
 * répétitivement les éléments consécutifs d'une liste et à les permuter
 * quand ils sont mal placés. Cet algorithme s'effectue sur place.
 * <p>
 * Le tri insertion est un algorithme d'ordre n^2 qui consiste à insérer
 * graduellement tous les éléments dans une liste afin de les obtenir
 * en ordre. cet algorithme ne s'effectue pas sur place.
 * <p>
 * Le tri fusion est un algorithme récursif d'ordre n*log(n) qui consiste à
 * séparer la liste en deux listes, trier ces deux listes et
 * finalement fusionner les deux listes triées afin d'en obtenir un seul
 * trié. Cet algorithme ne s'effectue pas sur place.
 * <p>
 * Le tri rapide est un algorithme récursif d'ordre n*log(n) qui consiste à
 * se choisir un pivot dans la liste et déplacer tous les éléments plus petits
 * que le pivot avant ce dernier et tous les plus grands que le pivot après
 * ce dernier. Cet algorithme s'effectue sur place.
 *
 * @author Louis Marchand
 * @author Stéphane Janvier
 * @author Benoit Desrosiers
 * @version 1.39, 01/31/2023
 * @see https://fr.wikipedia.org/wiki/Tri_%C3%A0_bulles
 * @see https://fr.wikipedia.org/wiki/Tri_par_insertion
 * @see https://fr.wikipedia.org/wiki/Tri_fusion
 * @see https://fr.wikipedia.org/wiki/Tri_rapide
 *
 * Distribué sous licence MIT.
 */
public class Tri {
    ...
}

Documentation d’attribut

La documentation d’attribut ne contient, minimalement, qu’une description courte de l’attribut. Par exemple:

/**
* Chaîne qui identifie l'Animal.
*/
private String nom;

Il est par contre à noter qu’il est possible d’utiliser d’ajouter des éléments comme une description longue ou des références ({@link …} ou @see).

Documentation de routine

Cette section s’applique à n’importe quel type de routines (méthodes, routines statiques, constructeurs, etc.)

Une documentation de routine doit contenir au minimum les informations suivantes:

- Une description courte;
- Une clause « @param » pour chaque argument de notre routine (s’il y a lieu);
- Une clause « @return » si la routine est une fonction;
- Une clause « @exception » ou « @throws » pour chaque type d’exception que la routine peut retourner.

Il est par contre à noter qu’il est possible d’utiliser d’ajouter des éléments comme une description longue ou des références ({@link …} ou @see).

Voici un exemple:

    /**
     * Ajoute un Animal à la liste des enfants de l'Animal
     *
     * @param aEnfant Le nouvel enfant à ajouter à la liste
     * @throws Exception Lorsque l'Animal reçu en argument
     *                   n'est pas du même type que l'Animal
     *                   en cours.
     * @see #getEnfants
     * @see #retirerEnfant
     */
    public void ajouterEnfant(Animal aEnfant) {
        ...
    }

Le programme « javadoc »

Le standard Javadoc est plus qu’un simple standard de documentation de code. C’est également un système permettant de générer des documents de documentation de projet. En d’autres mots, si vous faites votre documentation de code en respectant le standard Javadoc, vous pourrez facilement générer une documentation Web de votre code.

Pour générer la documentation Web, vous avez besoin de la commande « javadoc ». Voici comment utiliser cette commande:

javadoc -d <répertoire_résultat> <fichiers Java>

Par exemple, si j’ai le fichier « Animal.java » dans le répertoire en cours, je peux générer la documentation Web dans le répertoire « ma_documentation » avec la commande suivante:

javadoc -d ma_documentation Animal.java

Si vous voulez prendre plus que seulement un fichier Java, vous pouvez les lister à la fin de la commande. Par exemple:

javadoc -d ma_documentation Programme.java Animal.java Tri.java

Il est également possible d’utiliser un « wildcard » dans la commande. Par exemple, la commande suivante:

javadoc -d ma_documentation *.java

générera la documentation pour tous les fichiers Java du répertoire en cours.

Il est à noter que si vous utilisez IntelliJ, vous pouvez générer la documentation Web de votre projet en utilisant l’outil disponible dans le menu « Tools->Generate JavaDoc ».

Retour

Auteur: Louis Marchand

Sauf pour les sections spécifiées autrement, ce travail est sous licence Creative Commons Attribution 4.0 International.