Documentation du code

Introduction à JavaDoc

JavaDoc est l'outil standard de Java qui génère automatiquement une documentation professionnelle (HTML) à partir de commentaires spéciaux placés dans le code source.

C'est l'outil intégré au JDK utilisé pour documenter tous les projets Java, y compris l'API Java elle-même.

Pourquoi JavaDoc?

1. Communication du Code

• Documente le "pourquoi", pas seulement le "quoi"
• L'IA peut lire le code, mais elle a besoin de comprendre l'intention
• Aide les autres développeurs (et votre futur vous-même!)

2. API Professionnelle

• Génère une documentation web automatiquement
• Utile pour les projets open-source ou d'équipe
• Les IDE affichent la documentation au hover/autocomplétion

3. Bonnes Pratiques

• Force à réfléchir à ce que chaque classe/méthode fait
• Fait partie des standards industriels Java
• Utilisé dans tous les projets professionnels

Les Bases de JavaDoc

Commentaires JavaDoc

En Java, JavaDoc utilise une syntaxe de commentaire spéciale avec /** et */:

/**
 * Ceci est un commentaire JavaDoc
 */
public class MaClasse {
    // Ceci est un commentaire normal
    /* Ceci est un commentaire multi-ligne normal */
}

Structure d'un Commentaire JavaDoc

/**
 * Description courte de ce que fait la méthode.
 * 
 * Description plus longue (optionnelle) - peut faire plusieurs lignes.
 * Explique le contexte, les cas spéciaux, etc.
 * 
 * @param nomParametre Description du paramètre
 * @param autrParam Description d'un autre paramètre
 * @return Description de la valeur retournée
 * @throws NomException Description de l'exception
 */

Exemples Pratiques

Exemple 1 : Une classe simple

/**
 * Représente une personne avec son nom et son âge.
 * 
 * Cette classe encapsule les informations basiques d'une personne
 * et fournit des accesseurs pour les manipuler de manière sécurisée.
 * 
 * @author Votre nom
 * @version 1.0
 */
public class Personne {
    private String nom;
    private int age;
    
    /**
     * Crée une nouvelle personne avec le nom et l'âge spécifiés.
     * 
     * @param nom Le nom de la personne (non-null)
     * @param age L'âge de la personne (doit être >= 0)
     * @throws IllegalArgumentException si age est négatif
     */
    public Personne(String nom, int age) {
        if (age < 0) {
            throw new IllegalArgumentException("L'âge ne peut pas être négatif");
        }
        this.nom = nom;
        this.age = age;
    }
    
    /**
     * Retourne le nom de la personne.
     * 
     * @return Le nom (jamais null)
     */
    public String getNom() {
        return nom;
    }
    
    /**
     * Retourne l'âge de la personne.
     * 
     * @return L'âge (>= 0)
     */
    public int getAge() {
        return age;
    }
    
    /**
     * Vérifie si la personne est majeure.
     * 
     * @return true si age >= 18, false sinon
     */
    public boolean estMajeure() {
        return age >= 18;
    }
}

Exemple 2 : Une méthode avec exceptions

/**
 * Divise deux nombres et retourne le résultat.
 * 
 * @param dividende Le nombre à diviser
 * @param diviseur Le nombre par lequel diviser
 * @return Le résultat de la division
 * @throws ArithmeticException si diviseur est 0
 */
public double diviser(double dividende, double diviseur) {
    if (diviseur == 0) {
        throw new ArithmeticException("Division par zéro impossible");
    }
    return dividende / diviseur;
}

Exemple 3 : Méthode avec ArrayList

/**
 * Filtre une liste de nombres pour ne garder que les nombres pairs.
 * 
 * Cette méthode crée une nouvelle liste contenant uniquement les éléments
 * pairs de la liste originale. La liste originale n'est pas modifiée.
 * 
 * @param nombres La liste de nombres à filtrer (ne doit pas être null)
 * @return Une nouvelle liste contenant uniquement les nombres pairs
 * @throws NullPointerException si nombres est null
 */
public ArrayList<Integer> filtrerPairs(ArrayList<Integer> nombres) {
    ArrayList<Integer> pairs = new ArrayList<>();
    for (int nombre : nombres) {
        if (nombre % 2 == 0) {
            pairs.add(nombre);
        }
    }
    return pairs;
}

Balises JavaDoc Essentielles

Balise	Description	Exemple
@param	Documente un paramètre	@param nom Description du paramètre
@return	Documente la valeur retournée	@return Description du résultat
@throws	Documente une exception	@throws Exception Description de l'erreur
@author	Spécifie l'auteur	@author Jean Dupont
@version	Spécifie la version	@version 1.0
@since	À partir de quelle version	@since 1.5
@deprecated	Marque comme obsolète	@deprecated Utiliser nouvelleMéthode() à la place
@see	Référence une autre classe/méthode	@see MaClasse#autreMéthode()
@link	Crée un lien dans le texte	{@link MaClasse}
@code	Affiche du code formaté	{@code int x = 5;}

Bonne Pratique : Documenter le "Pourquoi"

MAUVAIS (redondant avec le code):

/**
 * Incrémente la valeur de compteur.
 */
public void incrementerCompteur() {
    compteur++;
}

BON (explique l'intention):

/**
 * Incrémente le compteur de visites utilisateur.
 * 
 * Appelé chaque fois qu'un utilisateur accède à une ressource.
 * Utilisé pour des statistiques et l'analyse du trafic.
 */
public void incrementerCompteur() {
    compteur++;
}

Générer la Documentation avec JavaDoc

Depuis la ligne de commande

# Générer la documentation pour un fichier
javadoc MaClasse.java

# Générer pour un package complet
javadoc -d docs src/*.java

# Avec options avancées
javadoc -d docs -private -author -version src/*.java

Options utiles

• -d docs : Spécifie le répertoire de sortie
• -private : Inclut les membres privés
• -author : Affiche les tags @author
• -version : Affiche les tags @version
• -encoding UTF-8 : Spécifie l'encodage

Depuis votre IDE

IntelliJ IDEA

1. Menu Tools → Generate JavaDoc
2. Sélectionner le scope (tout le projet, un package, etc.)
3. Configurer les options
4. Cliquer sur OK

Eclipse

1. Menu Project → Generate Javadoc
2. Sélectionner les fichiers/packages
3. Configurer la destination
4. Cliquer sur Finish

VS Code

1. Installer l'extension "JavaDoc Tools"
2. Utiliser la commande palette (Ctrl+Shift+P)
3. Chercher "Generate JavaDoc"

Résultat

La documentation est générée en HTML dans le dossier spécifié et peut être ouverte dans un navigateur. Le fichier principal est index.html.

Formatage Avancé dans JavaDoc

Utiliser du HTML

JavaDoc supporte le HTML basique :

/**
 * Calcule la moyenne de plusieurs nombres.
 * <p>
 * La formule utilisée est : <b>somme / nombre d'éléments</b>
 * </p>
 * <ul>
 *   <li>Supporte les tableaux vides (retourne 0)</li>
 *   <li>Gère les valeurs négatives</li>
 * </ul>
 * 
 * @param nombres Tableau de nombres
 * @return La moyenne ou 0 si le tableau est vide
 */

Liens entre classes

/**
 * Cette classe utilise {@link Personne} pour stocker les données.
 * Voir aussi {@link #autreMethode()} pour plus d'informations.
 * 
 * @see Personne
 * @see #autreMethode()
 */

Exemples de code

/**
 * Utilisation typique :
 * <pre>{@code
 * Calculatrice calc = new Calculatrice();
 * double result = calc.diviser(10, 2);
 * System.out.println(result); // Affiche 5.0
 * }</pre>
 */

Intégration avec l'IA

Comment utiliser JavaDoc avec l'IA:

1. Avant de demander à l'IA : Fournissez les commentaires JavaDoc

   • L'IA comprend mieux l'intention du code

2. Demander à l'IA de compléter : "Ajoute les commentaires JavaDoc à cette classe"

   • L'IA peut générer la documentation automatiquement

3. Demander à l'IA de réviser : "Explique cette classe en utilisant ses commentaires JavaDoc"

   • Vérifie que la documentation est correcte et cohérente

Exemple de prompt:

Ajoute des commentaires JavaDoc complets à cette classe Java.
Focalise sur le "pourquoi", pas seulement le "quoi".
Inclus des exemples d'utilisation dans les commentaires.

Bonnes Pratiques JavaDoc

1. Documenter tout ce qui est public

// BON : Tout membre public est documenté
/**
 * Gère les opérations de calcul mathématique.
 */
public class Calculatrice {
    /**
     * Additionne deux nombres.
     * @param a Premier nombre
     * @param b Deuxième nombre
     * @return La somme de a et b
     */
    public int additionner(int a, int b) {
        return a + b;
    }
}

2. Utiliser des phrases complètes

// MAUVAIS
/** Retourne nom */

// BON
/** Retourne le nom complet de l'utilisateur. */

3. Commencer par un verbe à la 3e personne

// BON pour les méthodes
/** Calcule la somme... */
/** Retourne le résultat... */
/** Vérifie si... */

// BON pour les classes
/** Représente un... */
/** Gère les opérations de... */

4. Documenter les contraintes et cas limites

/**
 * Recherche un élément dans le tableau.
 * 
 * @param tableau Le tableau à parcourir (ne doit pas être null)
 * @param element L'élément à rechercher (peut être null)
 * @return L'index de l'élément, ou -1 si non trouvé
 * @throws NullPointerException si tableau est null
 */

5. Mettre à jour la documentation

// MAUVAIS : Documentation obsolète
/**
 * Retourne le nom.
 */
public String getNomComplet() {  // Le nom de la méthode a changé!
    return prenom + " " + nom;
}

// BON : Documentation à jour
/**
 * Retourne le nom complet (prénom + nom).
 */
public String getNomComplet() {
    return prenom + " " + nom;
}

Conclusion

JavaDoc est un outil essentiel pour :

• Communiquer l'intention du code
• Générer une documentation professionnelle automatiquement
• Faciliter la collaboration avec d'autres développeurs et l'IA
• Rendre le code plus maintenable et compréhensible
• Documenter les décisions architecturales importantes

Règle d'or : Si vous hésitez à documenter quelque chose, documentez-le ! Il vaut mieux avoir trop de documentation que pas assez.