La Javadoc

Qu’est-ce que la Javadoc ?

Javadoc est l’outil officiel fourni avec le JDK (Java Development Kit) permettant de documenter le code source Java sous forme de fichiers HTML générés automatiquement à partir de commentaires structurés dans le code source.

Elle sert à documenter les classes, méthodes, attributs et interfaces de manière standardisée pour les développeurs qui utiliseront ou maintiendront votre code.

La documentation rends le code auto-explicatif sans devoir lire son implémentation.

Les fichiers de documentation contiennent : - une page d’accueil, - un index des classes, méthodes et packages, - une documentation lisible des descriptions et des balises ajoutées dans le code.

Pourquoi c’est important ?

• Compréhension : facilite la lecture et la maintenance du code.
• Collaboration : standardise la manière de décrire les méthodes, paramètres et exceptions.
• Réutilisation : permet d’utiliser des bibliothèques sans lire leur code source (comme java.util.ArrayList).
• Traçabilité : la documentation évolue en même temps que le code.

---

Comment écrire un commentaire Javadoc ?

Un commentaire Javadoc commence par /** et se termine par */.

Exemple minimal :

/**
 * Calcule la somme de deux entiers.
 */
public int somme(int a, int b) {
    return a + b;
}

💡 Attention : un simple commentaire /* ... */ ne sera pas interprété par Javadoc.

---

Structure interne d’un commentaire Javadoc

Un commentaire Javadoc se compose de deux parties :

1. Description générale — ce que fait la classe, la méthode, etc.
2. Balises spécifiques (@tag) — pour préciser les paramètres, retours, exceptions, auteurs, etc.

Exemple :

/**
 * Retourne la racine carrée d'un nombre.
 *
 * @param x nombre dont on veut la racine
 * @return racine carrée du nombre
 * @throws IllegalArgumentException si x est négatif
 */
public double racine(double x) {
    if (x < 0) throw new IllegalArgumentException("Nombre négatif : " + x);
    return Math.sqrt(x);
}

---

Les balises Javadoc les plus utilisées

Balise	Description	Exemple
@author	Auteur du code	@author Louis
@version	Numéro de version du code	@version 1.0
@since	Depuis quelle version la méthode existe	@since 2025.1
@param	Paramètre de la méthode	@param nom le nom complet de l’étudiant
@return	Valeur retournée par la méthode	@return la moyenne calculée
@throws / @exception	Exception levée par la méthode	@throws IOException si le fichier est introuvable
@deprecated	Indique qu’une méthode est obsolète	@deprecated Utiliser nouvelleMethode()
@see	Référence vers une autre méthode, classe ou lien	@see Math#sqrt(double)
@link	Lien inséré dans le texte de description	Voir {@link #getSolde()}
@code	Formatage inline de code	Exemple : {@code new File("doc.txt")}
@literal	Affiche du texte sans interpréter les balises	@literal <b>gras</b>
@implNote	Note interne au développeur sur l’implémentation	@implNote Cette méthode n’est pas thread-safe.
@implSpec	Spécification du comportement à respecter	@implSpec Ne modifie pas la collection originale.
@apiNote	Indique un conseil d’utilisation pour l’API publique	@apiNote Cette méthode est lente pour de grandes listes.
@inheritDoc	Hérite la documentation de la superclasse	@inheritDoc
@serial / @serialField	Pour la sérialisation Java	@serial Champ utilisé pour la compatibilité.

---

Balises HTML dans la Javadoc

Les commentaires Javadoc acceptent le HTML simplifié : - <p> pour les paragraphes - <ul><li> pour les listes - <b> ou <strong> pour mettre en gras - <code> pour le code inline - <pre> pour les blocs de code formatés

Exemple :

/**
 * Calcule la moyenne des valeurs.
 * <p>
 * <b>Remarque :</b> Les valeurs nulles sont ignorées.
 * </p>
 * <pre>
 * Exemple :
 * Moyenne m = new Moyenne();
 * m.ajouter(10);
 * m.ajouter(20);
 * System.out.println(m.calculer()); // Affiche 15
 * </pre>
 */

---

Génération de la documentation

Commande de base

javadoc -d doc src/*.java

- -d doc → dossier de sortie. - src/*.java → fichiers à documenter.

Exemple avec options :

javadoc -d doc -author -version -windowtitle "Projet Banque" -doctitle "Documentation du projet Banque" src/*.java

Résultat :

Un dossier /doc contenant des fichiers .html :

• index.html (page principale)

• allclasses-index.html

• package-summary.html

---

Documentation officielle Javadoc

• 🔹 Spécification complète de Javadoc (Oracle)
• 🔹 Tutoriel Oracle sur la commande Javadoc
• 🔹 Exemples de la Javadoc du JDK

---

Exemples concrets

Exemple 1 — Méthode complète

/**
 * Divise deux nombres entiers.
 *
 * @param a le dividende
 * @param b le diviseur
 * @return le résultat de la division entière
 * @throws ArithmeticException si b est égal à 0
 * @see Math#floorDiv(int, int)
 */
public int division(int a, int b) {
    if (b == 0) throw new ArithmeticException("Division par zéro !");
    return a / b;
}

Exemple 2 — Classe complète

/**
 * <h2>Classe CompteBancaire</h2>
 * <p>Représente un compte bancaire simple avec dépôt et retrait.</p>
 *
 * @author 
 *     Prof. L. Simard
 * @version 
 *     2.1
 * @since 
 *     2025-11
 */
public class CompteBancaire {
    private double solde;

    /**
     * Crée un compte bancaire avec un solde initial.
     *
     * @param soldeInitial montant de départ du compte
     */
    public CompteBancaire(double soldeInitial) {
        this.solde = soldeInitial;
    }

    /**
     * Dépose un montant sur le compte.
     *
     * @param montant montant à déposer (doit être positif)
     * @throws IllegalArgumentException si le montant est négatif
     */
    public void deposer(double montant) {
        if (montant < 0) throw new IllegalArgumentException("Montant négatif");
        solde += montant;
    }

    /**
     * Retire un montant du compte.
     *
     * @param montant montant à retirer
     * @throws IllegalArgumentException si le montant est négatif ou supérieur au solde
     */
    public void retirer(double montant) {
        if (montant < 0 || montant > solde)
            throw new IllegalArgumentException("Montant invalide");
        solde -= montant;
    }

    /**
     * Retourne le solde actuel du compte.
     *
     * @return le solde
     */
    public double getSolde() {
        return solde;
    }
}

---

Bonnes pratiques professionnelles

✅ Rédiger les commentaires en français ou en anglais de manière uniforme.
✅ Employer le temps présent et une phrase descriptive courte :

Mauvais : “Cette méthode va calculer la somme”
Bon : “Calcule la somme de deux nombres.”
✅ Ne pas répéter ce que le code dit déjà (inutile de redire “Retourne le solde” si la méthode s’appelle getSolde).
✅ Indiquer les cas limites et exceptions possibles.
✅ Documenter aussi les classes privées (pour usage interne de l’équipe).
✅ Relire la documentation générée en HTML pour vérifier la cohérence.

---