Accès rapide :
Qu'est-ce qu'une Doclet ?
Mise en oeuvre d'une Doclet simple
Utilisation de la 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.
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...).
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. } } |
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 $>
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 :