Rechercher
 

Améliorations / Corrections

Vous avez des améliorations (ou des corrections) à proposer pour ce document : je vous remerçie par avance de m'en faire part, cela m'aide à améliorer le site.

Emplacement :

Description des améliorations :

Mise en oeuvre de Doclets

Personnalisation HTML/CSS d'une Javadoc Introduction au GC



Accès rapide :
Qu'est-ce qu'une Doclet ?
Mise en oeuvre d'une Doclet simple
Utilisation de la Doclet

il existe aujourd'hui deux approches différentes pour la mise en oeuvre de doclets. La première API Doclet date du début de Java. Mais à partir de Java SE 9.0, une nouvelle API (non compatible avec la précédente) remplace avantageusement la précédente : elle est plus moderne et utilise les dernières évolutions du langage Java, mais elle permet aussi d'avoir un code plus évolutif. Bien naturellement, ce cours/tutoriel présente la nouvelle API DocLet : il vous faut donc avoir un Java SE (type JDK) en version 9.0 au minimum.

Qu'est-ce qu'une Doclet ?

Une Doclet constitue un module exécutable pouvant être lancé par l'outil Javadoc pour produire une documentation. On pourrait traduire le terme de Doclet par « petite application de documentation » (d'où le fait que j'ai choisi de mettre le terme de Doclet au féminin).

Par défaut, l'outil Javadoc propose une doclet : elle a la responsabilité de produire la documentation au format HTML. Mais vous pouvez configurer l'outil Javadoc pour utiliser une autre Doclet.

La responsabilité de l'outil Javadoc est d'analyser un code source Java et de produire une arborescence de noeuds en mémoire. Cette arborescence de noeuds correspond à la structure de votre code Java et peut être manipulée par programmation.

l'arborescence pourrait être comparée à un DOM XML (Document Object Model), pour ceux qui connaissent.

La responsabilité de la Doclet est de parcourir l'arborescence de noeuds, d'y trouver les informations utiles et de produire une documentation à un format quelconque (HTML, PDF...).

Mise en oeuvre d'une Doclet simple

Comme nous l'avons dit en prologue de ce document, pour développer une Doclet, il faut respecter une API particulière. Cette API propose l'interface jdk.javadoc.doclet.Doclet : votre classe de doclet doit l'implémenter. Voici un exemple de Doclet relativement basique permettant de récupérer les commentaires Javadoc de ses membres et de les afficher sur la console.

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 
 10 
 11 
 12 
 13 
 14 
 15 
 16 
 17 
 18 
 19 
 20 
 21 
 22 
 23 
 24 
 25 
 26 
 27 
 28 
 29 
 30 
 31 
 32 
 33 
 34 
 35 
 36 
 37 
 38 
 39 
 40 
 41 
 42 
 43 
 44 
 45 
 46 
 47 
 48 
 49 
 50 
 51 
 52 
 53 
 54 
 55 
 56 
 57 
 58 
 59 
 60 
 61 
 62 
 63 
 64 
 65 
 66 
 67 
 68 
 69 
 70 
 71 
 72 
 73 
 74 
 75 
 76 
 77 
 78 
 79 
 80 
 81 
 82 
 83 
 84 
 85 
 86 
 87 
 88 
 89 
 90 
 91 
 92 
 93 
 94 
 95 
 96 
 97 
 98 
 99 
 100 
 101 
 102 
 103 
 104 
 105 
 106 
 107 
 108 
 109 
 110 
 111 
package fr.koor.doclet;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Locale;
import java.util.Set;

import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.VariableElement;

import com.sun.source.doctree.DocCommentTree;
import com.sun.source.util.DocTrees;

import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.doclet.Reporter;
 

/**
 * Un exemple simple de doclet.
 */
public class SimpleDoclet implements Doclet {
    
    /**
     * Le constructeur de notre Doclet.
     */
    public SimpleDoclet() {
        super();
    }
    
    /**
     * Méthode d'initialisation de la Doclet.
     */
    @Override
    public void init(Locale locale, Reporter reporter) {  
        System.out.println( ">>> Doclet is initialized" );
    }
 
    /**
     * Renvoie le nom de la Doclet (ici, le nom de la classe).
     */
    @Override
    public String getName() {
        return getClass().getSimpleName();
    }
 
    @Override
    public Set<? extends Option> getSupportedOptions() {
        System.out.println( ">>> In getSupportedOptions" );
        return Collections.emptySet();
    }
 
    @Override
    public SourceVersion getSupportedSourceVersion() {
        System.out.println( ">>> In getSupportedSourceVersion" );
        return SourceVersion.latest();
    }
     
 
    /**
     * Le point d'entrée de notre doclet de test.
     * 
     * @param environment Représente l'environnement de la Doclet.
     */
    @Override
    public boolean run(DocletEnvironment environment) {
        System.out.println( ">>> In getSupportedSourceVersion" );

        // Un arbre de noeuds de commentaires Javadoc
        DocTrees trees = environment.getDocTrees();
        
        // On parcourt l'arbre syntaxique du code analysé.
        for ( Element element : environment.getSpecifiedElements() ) {
            
            // On affiche le nom de la classe et sa documentation.
            DocCommentTree tree = trees.getDocCommentTree( element );
            System.out.printf( "Type %s : %s\n",
                               element.getSimpleName(),
                               tree != null ? tree.toString() : "" );
            
            // On parcourt tous les membres du type courant et 
            // on affiche un éventuel commentaire Javadoc.
            for( Element member : element.getEnclosedElements() ) {
                DocCommentTree memberTree = trees.getDocCommentTree( member );
                System.out.printf( "\t%s - %s - %s\n",
                                   member.toString(),
                                   member.getKind().toString(),
                                   memberTree != null ? memberTree.toString() : "" );
                
                // Si le membre est une méthode ou un constructeur, on liste les paramètres
                if ( Arrays.asList( ElementKind.METHOD, 
                                    ElementKind.CONSTRUCTOR ).contains( member.getKind() ) ) {
                    ExecutableElement methodElement = (ExecutableElement) member;
                    List<? extends VariableElement> parameters = methodElement.getParameters();
                    for (VariableElement parameter : parameters) {
                        System.out.printf( "\t\t%s - %s\n",
                                           parameter.getSimpleName(),
                                           parameter.asType().toString() );
                    }
                }
            }
        }
        
        return true; // Le traitement se termine correctement.
    }
        
}
Un exemple simple de définition d'une Doclet
bien entendu, au lieu d'envoyer les informations sur la console, vous auriez pu produire un fichier de documentation dans un format quelconque.

Utilisation de la Doclet

Deux nouvelles options de l'outil Javadoc sont requises pour demander l'exécution d'une Doclet :

Voici un exemple de démarrage de notre Doclet sur son propre code (la Doclet analyse ses propres commentaires). On retrouve bien dans les résultats affichés les commentaires présents dans le code (notez que deux méthodes sont non documentées).

$> javadoc -docletpath bin -doclet fr.koor.doclet.SimpleDoclet src/fr/koor/doclet/*.java
>>> Doclet is initialized
>>> In getSupportedOptions
Loading source file src/fr/koor/doclet/SimpleDoclet.java...
Constructing Javadoc information...
>>> In getSupportedSourceVersion
Type SimpleDoclet : Un exemple simple de doclet.
    SimpleDoclet() - CONSTRUCTOR - Le constructeur de notre Doclet.
    init(java.util.Locale,jdk.javadoc.doclet.Reporter) - METHOD - Méthode d'initialisation de la Doclet.
        locale - java.util.Locale
        reporter - jdk.javadoc.doclet.Reporter
    getName() - METHOD - Renvoie le nom de la Doclet (ici, le nom de la classe).
    getSupportedOptions() - METHOD - 
    getSupportedSourceVersion() - METHOD - 
    run(jdk.javadoc.doclet.DocletEnvironment) - METHOD - Le point d'entrée de notre doclet de test.
@param environment Représente l'environnement de la Doclet.
        environment - jdk.javadoc.doclet.DocletEnvironment
$> 


Personnalisation HTML/CSS d'une Javadoc Introduction au GC