Cinquième point de notre liste des 10 erreurs à éviter en Java, le commentaire d'une application est indispensable pour assurer la pérénité de l'application, transmise de développeurs en développeurs ou resortie après de nombreux mois d'oubli...
JavaDoc est un outil permettant d'aller plus loin que le simple commentaire, en permettant de créer automatiquement, par le biais de commentaires écrits sous un certain format, une documentation de l'application en HTML. Vous pouvez ainsi, moyennant un peu plus de rigueur et de mise en forme préparer une documentation complète sur votre programme (à défaut d'en écrire le manuel) tout en écrivant votre code.
C'est le programme javadoc, fourni avec le JDK qui se charger de parser (analyse syntaxique) votre code, d'en extraire les informations et de les restituer au format HTML.

Format
Les commentaires doivent bien évidement suivre une norme d'écriture. Ils peuvent contenir du texte simple, des tags HTML de mise en forme (italique, gras... ou même <pre>, pour mettre du code dans vos commentaires, ce qui peut se révéler utile), ou des tags spéciaux réservé à JavaDoc, qui débutent par @ (@author, @version...).. Ces commentaires doivent obligatoirement se trouve juste avec le code qu'ils commentent (paquetage, classe, interface, variable d'occurence ou méthode).

Voici la forme de base d'un commentaire JavaDoc pour une classe:

/** Description du code dans un phrase complète.
  * @author <a href="http://www.le-site.com/">Jean Dupondt</a>
  * @version 1.0 (2003-01-09)
*/
public class MaClasse extends java.applet.Applet {
...

Il existe des variantes selon le type de code qui est commenté, qui se situent principalement dans les mots-clés JavaDoc à emplyer. Nous allons les passer ne revue.

Voici un exemple plus long de commentaire:

/** Décrit les paramètres que l'applet peut prendre
* @author Gustave Flaubert
* @author Jules & Edmond de Goncourt
* @version 5.3 beta, 1833-05-23
* @param pecuchet La bétise humaine
* @param bouvard Comme Pécuchet
* @return copies
* @exception IndexOutOfBoundsException Débordement de la matrice
* @exception java.io.FileNotFoundException le fichier n'existe pas
* @see java.lang.String
* @see String
* @see java.io.InputStream;
* @see String#equals @see java.lang.Object#wait(int)
*/
public voir String[][] getParameterIfno() {
...

Une fois votre application terminé, la documentation sera créée automatiquement via la commande:
javadoc monprogramme.java

La documentation HTML sera générée dans le même repertoire que le programme. Pour sauver la documentation dans un autre repertoire que le repertoire courant, il faudra taper par exemple:
javadoc -d C:\ma-doc\ monprogramme.java

D'autres options permettent de spécifier quels mots-clés prendre en compte lors de la génération de la documentation (-author, -version...), de ne générer la documentation que pour une certaine partie du code (-public, -protected (actif par défaut), -package, -private). Par exemple, pour créer une documentation de programme.java dans le repertoire voisin docs et ne prendre en compte que le mot-clé author des classes publiques:
javadoc -d ..\docs -author -public programme.java