Utilisation de javadoc

Lorsqu'on conçoit et développe un paquetage (ou un ensemble de classes), on peut souhaiter créer automatiquement une documentation concernant ce paquetage. Un utilitaire du JDK, accessible par la commande javadoc, permet d'engendrer une documentation similaire à celle de la documentation de l'API Java, à condition d'avoir mis dans le fichier source les commentaires adéquats.

Les commentaires s'adressant à l'utilitaire javadoc doivent commencer par /** et se terminer par */. Nous donnons à titre d'exemple deux classes, les classes A et B, qui ne font pas grand-chose. Les commentaires des fichiers A.java et B.java, situés dans le même répertoire, sont prévus pour que l'utilitaire javadoc puisse engendrer la documentation. Notre exemple donne la majeure partie des balises (indiquées avec le symbole @) de javadoc. On considère le fichier A.java contenant le code ci-dessous.

/** Classe inutile, juste pour essayer 
    @author 	anonyme
    @version 	fevrier 2011 
*/
public class A {
	/** Donne le nombre d'instanciations */
	public static int nb;

	public A() {
	        nb++;
	}

	/** Pour faire un essai
		@param 			c un caract&egrave;re
		@return 		la valeur enti&egrave;re de c
		@exception 	        ClassCastException si bizarre
		@see 			B
		@see			#faire(char c)
		@see			B#action()
	*/
	public int faire(char c) throws ClassCastException {
		if (c == 'a') throw new ClassCastException();
		return (int)c;
	}
}

On considère aussi le fichier B.java contenant le code ci-dessous

public class B {
	public void action() {}
}

Depuis ce répertoire, nous avons utilisé la commande :
javadoc A.java B.java

Un ensemble de fichiers HTML a été créé accessibles à partir du fichier index.html.

La commande javadoc peut aussi être utilisée pour un paquetage et accepte différentes options. On peut par exemple choisir si on ne veut commenter que les classes et les champs publiques, ou bien aussi d'autres niveaux de visibilité. On peut remarquer que des balises HTML peuvent être introduites dans les commentaires et seront prises en compte (à titre d'illustration, nous avons utilisé une balise indiquant d'écrire les mots pour essayer en gras dans l'explication de la classe A) ; il faut aussi écrire les éventuels caractères spéciaux ou accentués en html.

Sous eclipse, on peut engendrer automatiquement la documentation en utilisant dans le menu projet l'item correspondant à la fabrication de la documentation javadoc.