La documentation des fichiers sources par javadoc permet :

• D'obtenir des fichiers sources auto-documentés sous une forme homogène et standard

• De rendre compte des erreurs de syntaxe lors de la génération

• De déterminer les points essentiels d'un package, d'une classe ou d'une méthode

• De rendre les liaisons concepteur/utilisateur de classes plus simples

• D'offrir une vue d'ensemble d'une API (Application Programming Interface)

• De visualiser très rapidement la cohérence du développement, la pertinence ou l'absence de documentation

• D'adapter ou d'enrichir la documentation selon les besoins grâce à des tags

I. Format

La documentation vise les packages, classes et méthodes

Tous les commentaires javadoc doivent suivent cette trame :

/**

* Description

* @tag

*/

Exemple de description d'une classe

/** Agent est une classe permettant de simuler un "publieur" et un "lecteur" autour d'un topic. En mode "publieur" un message est envoyé en boucle. En mode "lecteur" un listener se charge de rapatrier les messages d'un topic @author Alexandre Brillant @version 1.0 */ public class Agent { /** Emission d'un message vers le topic courant @param message Un texte à transmettre @return <code>true</code> lorsque le message est bien transmis*/ public boolean sendMessage( String message ); }

Règles à suivre pour la description :

• Ne pas répéter simplement le nom d'une méthode mais ajouter une information complémentaire

• Trouver un compromit suffisance/brièveté

• Encadrer tous les mots clefs par la balise code (ex <code>true</code>)

• Utiliser la balise <p> pour changer de paragraphe

Liste de tags indispensables

Règle concernant les tags

• Lorsqu'une classe dérive d'une autre classe ou implémente une interface, des liens seront établis automatiquement vers les méthodes parentes.

• Lorsqu'une méthode est surchargée mais ne contient pas de commentaire, le commentaire de la classe parente sera automatiquement repris. Cependant, il est conseillé de toujours commenter même en cas de surcharge.

• Prendre en compte toutes les exceptions même celles dérivant de "RuntimeException" qui n'ont pas l'obligation d'être traitée par l'utilisateur.

Il est possible de faire référence à des images. Par convention, ces images devront être présentes dans un répertoire doc-files. Les noms des images doivent être précédés par le nom de la classe (Ex : doc-files/Agent-1.gif).

Le fichier 'package.htmll' contient des informations sur les packages. Il doit être placer dans chaque répertoire de chaque package. Lors de la génération standard, le contenu principal sera extrait et reporté en tête des fichiers 'package-summary.htmll".

Le plus simple est d'utiliser la commande javadoc en se plaçant dans le répertoire contenant les fichiers sources.

Exemple : javadoc package1 package2 –d ..\doc

package1 et package2 sont des exemples de packages java. L'option –d est le répertoire de stockage de la documentation.

L'option sourcepath permet de spécifier la localisation des sources. Le classpath doit aussi être en accord avec les librairies utilisées.

Sinon, de nombreuses options graphiques sont disponibles concernant les feuilles de style, les en-têtes et pieds de page…

Il peut être intéressant d'étendre les tags pour prendre en compte par exemple les bugs et améliorations à apporter.

JavaDoc fait intervenir la notion de DocLet. L'utilisateur peut par cette API étendre ou créer une nouvelle forme de génération.

Exemple de génération d'une pages 'bugs.html' contenant dans une table une liste de tags bug par classe et méthode :

package hexadev; import com.sun.javadoc.*; import java.io.*; /** * Exemple de <code>DocLet</code> qui * liste tous les tag bug ainsi que les * classes les contenant. * Le résultat déposé dans un fichier bugs.html sous * forme d'une table. * @bug de test1 */ public class ListBug { /** * Méthode principale pour la génération javadoc * @bug Test2 de bug **/ public static boolean start( RootDoc root ) { try { HTMLBuilder builder = new HTMLBuilder(); ClassDoc[] classes = root.classes(); for ( int i = 0; i < classes.length; i++ ) { // Lister les tags bug de la classe Tag[] _tags = classes[ i ].tags( tag ); for( int j = 0; j < _tags.length; j++ ) { builder.append( classes[ i ].name(), "", _tags[ j ].text() ); } String _name = classes[ i ].name(); // Lister les tags bug de chaque méthode MethodDoc[] methods = classes[ i ].methods(); for ( int j = 0; j < methods.length; j++ ) { Tag[] tags = methods[ j ].tags( tag ); if ( tags.length > 0 ) { for ( int k = 0; k < tags.length; k++ ) builder.append( classes[ i ].name(), methods[ j ].name(), tags[ k ].text() ); } } } builder.stop(); } catch( Exception ex ) { ex.printStackTrace(); } return true; } /** * Construction d'une page HTML résumant les tags bug * par classe et méthode */ static class HTMLBuilder { public HTMLBuilder() throws IOException { output = new BufferedWriter( new OutputStreamWriter( new FileOutputStream( file ) ) ); output.write( "<html><body><table border=\"1\">\n" ); } public void append( String classe, String methode, String line ) throws IOException { output.write( "<tr><td>" + classe + "</td> <td>" + methode + "</td> <td>" + line + "</td></tr>" ); } public void stop() throws IOException { output.write( "</table></body></html>" ); output.close(); } private BufferedWriter output; private String file = "bugs.html"; } static String tag = "bug"; }

La méthode start est appelée par javadoc avec en paramètre des informations concernant les classes et méthodes. C'est la méthode tags qui permet de connaître les tags 'bug' d'une classe ou d'une méthode.

Pour utiliser cet exemple, il est indispensable d'utiliser la librairie tools.jar présente dans les distributions du JDK.

Compilation :

javac ListBug.java –classpath c:\jdk1.2\lib\tools.jar –d .

Test :

javadoc –doclet hexadev.ListBug –classpath c:\jdk1.2\lib\tools.jar ListBug.java

Nous obtenons le tableau suivant :