Commentaires de documentation Java : Maîtriser Javadoc et types de commentaires

Java prend en charge trois types de commentaires :

Ce chapitre explique Javadoc et comment l'utiliser pour générer une documentation utile à partir du code source Java.

Qu'est-ce que Javadoc ?

Javadoc est un outil fourni avec le JDK qui génère de la documentation HTML à partir du code source Java, à condition que celui-ci contienne des commentaires dans un format prédéfini.

Exemple basique

/**
 * Le programme HelloWorld affiche simplement "Hello World!" sur la sortie standard.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        // Affiche Hello, World! sur la sortie standard.
        System.out.println("Hello World!");
    }
}

Vous pouvez inclure des balises HTML dans la description :

Exemple avec HTML

/**
 * <h1>Hello, World!</h1>
 * Le programme HelloWorld implémente une application qui
 * affiche simplement "Hello World!" sur la sortie standard.
 * <p>
 * Des commentaires appropriés rendent le code plus
 * convivial et sont le signe d'un code de haute qualité.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Les balises Javadoc

L'outil javadoc reconnaît les balises suivantes :

Exemple complet

Ce programme utilise plusieurs balises importantes. La documentation de la classe AddNum sera produite dans AddNum.html, et un fichier maître index.html sera aussi créé.

import java.io.*;

/**
 * <h1>Addition de deux nombres !</h1>
 * Le programme AddNum additionne deux entiers donnés et affiche
 * le résultat à l'écran.
 * <p>
 * <b>Note :</b> Des commentaires appropriés rendent le programme plus
 * convivial et sont le signe d'un code de haute qualité.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class AddNum {
    /**
     * Cette méthode additionne deux entiers. C'est la forme la plus simple
     * d'une méthode de classe, juste pour montrer l'usage des balises Javadoc.
     * @param numA Premier paramètre de la méthode addNum
     * @param numB Second paramètre de la méthode addNum
     * @return int Somme de numA et numB
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }

    /**
     * Méthode principale utilisant addNum.
     * @param args Inutilisé.
     * @return Rien.
     * @exception IOException En cas d'erreur d'entrée.
     * @see IOException
     */
    public static void main(String[] args) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("Somme de 10 et 20 est : " + sum);
    }
}

Traitez le fichier avec javadoc :

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning

Consultez la documentation générée. Avec JDK 1.7, le stylesheet.css par défaut est basique ; téléchargez la version standard depuis Oracle.