Fiches / Articles

Cadre Fonctionnel

Documentation de sources

Cadre Technique

JavaDoc

Identifiant 

SYS_JDOC_01

Référent Technique 


Version 

1.0

Auteur 

Alexandre Brillant

Date 

04/01

Source

htp://java.sun.com/j2se/javadoc/writingdoccomments/index.htmll

Dépendance 

INS_EJB_01

Cible 

BD_EJB_01, OPT_ETB_EJB_01

La documentation des fichiers sources par javadoc permet :

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 :

Liste de tags indispensables

Tag

Rôle

Exemple

@author

Nom du développeur pour une classe ou une interface. Lorsque plusieurs auteurs existent, il faut répéter ce tag en respectant la chronologie

@author Alexandre Brillant

@author Jean Philippe

@version

Version d'une classe ou d'une interface. En utilisant %I%,%G% on peut automatiser la mise à jour de ce numéro

@version 1.0

@see

Permet de créer un lien vers un package, une classe ou une méthode

Quelques utilisations :

@see package

@see package.Class

@see Class

@see Class#method(Type,Type,…)

@see #method(Type,Type,…)

@see aws.core.ServiceConfig

@since

Définit depuis quand la classe, l'interface ou la méthode sont présents dans l'API

@since 1.1

@param

Description d'un paramètre de méthodes et constructeurs. Il doit suivre le schéma : @param rôle

@param message Chaîne à transmettre. Lorsque cette valeur est <code>null</code> une exception est levée

@return

Description d'une valeur de retour pour une méthode

@return <code>true</code> lorsque le message est correctement transmis

@exception

Liste toutes les exceptions même celles qui n'ont pas l'obligation d'être traitées

@exception IOException Pour un problème de connexion et d'acheminement du message

@deprecated

Indique qu'une méthode ou classe ne sera plus utilisée dans la prochaine version

@deprecated Remplaçé par {@link #setMessage}

{@link}

Permet de créer un lien vers un autre élément

La class {@link ImageObserver} est utilisée…

@see

Création d'un lien vers un package, une classe ou une méthode

@see package

@see package.Class

@see Class

@see Class#method(Type, Type,…)

@see aws.core.ServiceConfig

Règle concernant les tags

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 :

ListBug


De test1

ListBug

start

Test2 de bug