Génération automatique de la documentation avec Javadoc

Outils de monitoring (mémoire/GC) Personnalisation HTML/CSS d'une Javadoc

Accès rapide :
Introduction
Utilisons l'outil Javadoc
Lancement manuel (en ligne de commande) de l'outil Javadoc
Lancement de l'outil Javadoc via son intégration dans l'IDE Eclipse
Injection des codes sources dans la documentation Javadoc
Les trois formes de commentaires en Java
On documente nos codes Java
Quelques règles à connaître
Les principaux marqueurs pour documenter une classe
Les principaux marqueurs pour documenter une méthode
Outils alternatifs

Introduction

Dans un processus de développement complet, l'acte de coder n'est pas la seule activité. Il faut aussi concevoir l'architecture, documenter le code, tester le code, ... Nous allons, dans ce chapitre porter notre attention sur la production de la documentation du code. A titre d'exemple, vous n'êtes pas sans savoir que l'API Java SE est documentée : c'est ce que j'ai appelé, jusqu'à présent, « la Javadoc ». Nous l'avons parcourue à de nombreuses occasions durant ce cours Java et j'espère que vous avez apprécié sa qualité. Eh bien, sachez que vous pouvez produire le même type de documentation pour vos codes.

En fait et par abus de langage, quand on parle de Javadoc on peut considérer plusieurs choses : un outil de production de documentation, la documentation de l'API standard et des blocs de commentaires dans votre code. Tout est intimement lié, mais soyons un peu plus précis.

Javadoc est un outil de JDK (Java Development Kit) qui permet de produire des documentations, au format HTML, à partir de codes Java. Cet outil est notamment utilisé pour produire la documentation officielle sur l'API Java SE à partir de ses codes sources Java. Cet outil est localisé dans le chemin $JAVA_HOME/bin/javadoc[.exe] (ou $JAVA_HOME représente le dossier d'installation de votre JDK). Cet outil peut être utilisé sur vos codes Java, même si vous n'y avait pas produit de bloc de commentaires au format Javadoc. Dans ce cas, vous produirez une documentation structurelle de votre programme, cette structure pouvant directement être déduite à partir du code Java.

L'outil Javadoc recherche dans le code source Java des blocs de commentaires particuliers qui sont censés contenir des informations de documentation sur les codes qui suivent le commentaire. Ces blocs de commentaires doivent être au format « Javadoc » : cela veut dire qu'ils doivent commencer par la séquence /** et qui doivent se terminer par la séquence */. De plus, ces blocs doivent contenir des instructions particulières à Javadoc. On reconnaît facilement ces instructions dans le bloc de commentaire, car elles commencent par le caractère @ (un peu comme les annotations Java, mais ce ne sont pas des annotations) : on appelle ces instructions Javadoc des « doclets ».

La documentation produire, parfois directement appelée « Javadoc » est au format HTML. Cela permet d'y naviguer très facilement grâce à des très nombreux liens hypertextes automatiquement générés : cela permet de passer d'un type à un autre par simple clic sur ces liens. L'autre avantage du HTML réside dans le fait que vous pourrez très simplement partager cette documentation avec d'autres personnes en la plaçant dans un serveur Web. C'est notamment le cas de la documentation officielle de l'API Java SE 11.

Utilisons l'outil Javadoc

Nous allons commencer quelques premières manipulations afin de produire une documentation structurelle de vos codes. Personnellement, je vais reprendre les classes Rational et RationalException que nous avions produite durant les chapitres relatifs à la programmation orientée objet et à la gestion des erreurs en Java. J'ai mis ces codes dans un nouveau projet Eclipse que j'ai appelé TestJavadoc et j'ai ouvert une console dans le répertoire du projet. Voici l'organisation du projet.

$> ls -al
total 28
drwxrwxr-x.  5 dominique dominique 4096  6 mars  11:21 .
drwxr-xr-x. 12 dominique dominique 4096  6 mars  11:21 ..
drwxrwxr-x.  3 dominique dominique 4096  6 mars  11:22 bin
-rw-rw-r--.  1 dominique dominique  295  6 mars  11:21 .classpath
-rw-rw-r--.  1 dominique dominique  370  6 mars  11:21 .project
drwxrwxr-x.  2 dominique dominique 4096  6 mars  11:21 .settings
drwxrwxr-x.  3 dominique dominique 4096  6 mars  11:22 src
$> ls -lR src
src:
total 4
drwxrwxr-x. 3 dominique dominique 4096  6 mars  11:22 fr

src/fr:
total 4
drwxrwxr-x. 3 dominique dominique 4096  6 mars  11:22 koor

src/fr/koor:
total 4
drwxrwxr-x. 2 dominique dominique 4096  6 mars  11:22 poo

src/fr/koor/poo:
total 12
-rw-rw-r--. 1 dominique dominique  307  6 mars  11:23 RationalException.java
-rw-rw-r--. 1 dominique dominique 1553  6 mars  11:23 Rational.java
-rw-rw-r--. 1 dominique dominique  345  6 mars  11:23 RationalStart.java
$> 

Lancement manuel (en ligne de commande) de l'outil Javadoc

Nous allons donc chercher à lancer l'outil Javadoc en mode ligne de commande. Assurez-vous préalablement que le dossier contenant l'outil Javadoc soit bien présent dans la variable d'environnement PATH de votre système d'exploitation et assurez-vous bien d'utiliser un JDK (Java Development Kit) et non pas un JRE (Java Runtime Environment). Si tout est bon, vous devriez pouvoir lancer la ligne de commande suivante pour obtenir l'aide de la commande javadoc

$> javadoc -help
Usage: javadoc [options] [packagenames] [sourcefiles] [@files]
  -overview <file>                 Read overview documentation from HTML file
  -public                          Show only public classes and members
  -protected                       Show protected/public classes and members (default)
  -package                         Show package/protected/public classes and members
  -private                         Show all classes and members
  -help                            Display command line options and exit
  -doclet <class>                  Generate output via alternate doclet
  -docletpath <path>               Specify where to find doclet class files
  -sourcepath <pathlist>           Specify where to find source files
  -classpath <pathlist>            Specify where to find user class files
  -cp <pathlist>                   Specify where to find user class files
  -exclude <pkglist>               Specify a list of packages to exclude
  -subpackages <subpkglist>        Specify subpackages to recursively load
  -breakiterator                   Compute first sentence with BreakIterator
  -bootclasspath <pathlist>        Override location of class files loaded
                                   by the bootstrap class loader
  -source <release>                Provide source compatibility with specified release
  -extdirs <dirlist>               Override location of installed extensions
  -verbose                         Output messages about what Javadoc is doing
  -locale <name>                   Locale to be used, e.g. en_US or en_US_WIN
  -encoding <name>                 Source file encoding name
  -quiet                           Do not display status messages
  -J<flag>                         Pass <flag> directly to the runtime system
  -X                               Print a synopsis of nonstandard options and exit

Provided by Standard doclet:
  -d <directory>                   Destination directory for output files
  -use                             Create class and package usage pages
  -version                         Include @version paragraphs
  -author                          Include @author paragraphs
  -docfilessubdirs                 Recursively copy doc-file subdirectories
  -splitindex                      Split index into one file per letter
  -windowtitle <text>              Browser window title for the documentation
  -doctitle <html-code>            Include title for the overview page
  -header <html-code>              Include header text for each page
  -footer <html-code>              Include footer text for each page
  -top    <html-code>              Include top text for each page
  -bottom <html-code>              Include bottom text for each page
  -link <url>                      Create links to javadoc output at <url>
  -linkoffline <url> <url2>        Link to docs at <url> using package list at <url2>
  -excludedocfilessubdir <name1>:.. Exclude any doc-files subdirectories with given name.
  -group <name> <p1>:<p2>..        Group specified packages together in overview page
  -nocomment                       Suppress description and tags, generate only declarations.
  -nodeprecated                    Do not include @deprecated information
  -noqualifier <name1>:<name2>:... Exclude the list of qualifiers from the output.
  -nosince                         Do not include @since information
  -notimestamp                     Do not include hidden time stamp
  -nodeprecatedlist                Do not generate deprecated list
  -notree                          Do not generate class hierarchy
  -noindex                         Do not generate index
  -nohelp                          Do not generate help link
  -nonavbar                        Do not generate navigation bar
  -serialwarn                      Generate warning about @serial tag
  -tag <name>:<locations>:<header> Specify single argument custom tags
  -taglet                          The fully qualified name of Taglet to register
  -tagletpath                      The path to Taglets
  -charset <charset>               Charset for cross-platform viewing of generated documentation.
  -helpfile <file>                 Include file that help link links to
  -linksource                      Generate source in HTML
  -sourcetab <tab length>          Specify the number of spaces each tab takes up in the source
  -keywords                        Include HTML meta tags with package, class and member info
  -stylesheetfile <path>           File to change style of the generated documentation
  -docencoding <name>              Specify the character encoding for the output
$> 

Le premier constat est qu'il y a beaucoup d'options de proposées. Cela vous permettra de contrôler tous les aspects de la documentation à produire. Parmi ces options, notez la présence de l'option -d <directory> : elle nous permettra de contrôler le dossier dans lequel produire la documentation.

Procédons maintenant à une première documentation structurelle de notre projet (nous n'avons pas encore injecté de commentaires Javadoc dans les sources) en exécutant la ligne de commande suivante.

$>  javadoc -d doc src/fr/koor/poo/*.java
Loading source file src/fr/koor/poo/RationalException.java...
Loading source file src/fr/koor/poo/Rational.java...
Loading source file src/fr/koor/poo/RationalStart.java...
Constructing Javadoc information...
Creating destination directory: "doc/"
Standard Doclet version 11
Building tree for all the packages and classes...
Generating doc/fr/koor/poo/Rational.html...
Generating doc/fr/koor/poo/RationalException.html...
Generating doc/fr/koor/poo/RationalStart.html...
Generating doc/fr/koor/poo/package-summary.html...
Generating doc/fr/koor/poo/package-tree.html...
Generating doc/constant-values.html...
Generating doc/serialized-form.html...
Building index for all the packages and classes...
Generating doc/overview-tree.html...
Generating doc/index-all.html...
Building index for all classes...
Generating doc/allclasses-index.html...
Generating doc/allpackages-index.html...
Generating doc/deprecated-list.html...
Building index for all classes...
Generating doc/allclasses.html...
Generating doc/allclasses.html...
Generating doc/index.html...
Generating doc/help-doc.html...
$> 

En analysant les affichages produits, vous remarquerez sur l'avant-dernière ligne qu'une page doc/index.html a été générée. Elle constitue le point d'entrée de votre documentation et vous pouvez l'ouvrir dans un navigateur. Vous pouvez consulter cette documentation en activant ce lien. N'hésitez pas à cliquer sur les différents liens proposés afin de passer dans les principales pages de cette documentation.

Vous aurez certainement remarqué que, même si nous n'avons pas encore produit de commentaires Javadoc, une telle documentation est très pratique pour prendre en main les codes d'un nouveau projet. Cela permet d'avoir une vision du projet de plus haut niveau d'abstraction.

Vous aurez, aussi, certainement remarqué que seuls les champs publics ou protégés sont documentés. Par défaut on cherche à produire une documentation à destination d'utilisateurs de ce code. Les membres privés ne sont donc pas utiles et présent dans cette documentation.

On peut, bien entendu, aussi produire une documentation du code à destination des membres de l'équipe de développement. Dans ce cas, tous les éléments du programme devront apparaître dans cette documentation. Pour ce faire, il faut rajouter l'option -private sur la ligne de commande de déclenchement de Javadoc.

$> javadoc -d doc -private src/fr/koor/poo/*.java
Loading source file src/fr/koor/poo/RationalException.java...
Loading source file src/fr/koor/poo/Rational.java...
Loading source file src/fr/koor/poo/RationalStart.java...
Constructing Javadoc information...
Standard Doclet version 11
...
$> 

Vous pouvez consulter cette documentation « privée » en activant ce lien. N'hésitez pas à la comparer avec la documentation précédente. On y trouve notamment la présence des attributs privés numerator et denominator, mais aussi la méthode privée pgcd.

Lancement de l'outil Javadoc via son intégration dans l'IDE Eclipse

Les principaux IDE Java proposent une intégration de Javadoc configurable via une interface graphique : c'est, bien entendu, le cas d'Eclipse. Certaines personnes préfèrent cette solution.

Pour contrôler le déclenchement de Javadoc dans Eclipse, veuillez ouvrir le menu « Project » et y sélectionner l'assistant « Generate Javadoc ». Voici une capture d'écran montrant ce menu.

En activant cet élément de menu, une boîte de dialogue de configuration de Javadoc doit apparaître. Il est important de bien y référencer la version de Javadoc que vous souhaitez lancer. Notez qu'on retrouve aussi sur ce premier écran le choix du dossier à documenter (ici src), le type de Javadoc (ici public) et le répertoire de destination (doc par défaut). Des écrans complémentaires peuvent être obtenus en appuyant sur le bouton « Next > ». Si ces points vous conviennent, vous pouvez directement appuyer sur le bouton « Finish ». Voici un capture d'écran pour cette configuration.

Injection des codes sources dans la documentation Javadoc

Si vous le souhaitez, vous pouvez injecter vos codes sources dans la documentation HTML. Pour ce faire, il faut rajouter l'option -linksource lors du démarrage de l'outil Javadoc.

$> javadoc -d doc src/fr/koor/poo/*.java -linksource

Les trois formes de commentaires en Java

Pour rappel, Java offre, de base, deux formes de commentaires. La première forme est le commentaire sur une seule ligne, initialement inventée par C++. On la reconnaît par ces deux caractères introductifs //. Un tel commentaire se termine à la fin de la ligne.

 1 

int counter = 1;     // Un commentaire sur cet entier qui vaut 1

La seconde forme de commentaires est héritée du langage C et permet de traiter plusieurs lignes en tant que commentaire. Elle est introduite par /* et se termine par */. En voici un exemple.

 1 
 2 
 3 
 4 
 5 

/*
 * Ce commentaire est sur plusieurs lignes
 * Les caractères * de la seconde, troisième et quatrième ligne sont facultatifs.
 * Ils sont juste là pour faire beau.
 */

Javadoc dérive donc une troisième forme à partir du commentaire multi-lignes. Ce commentaire à destination de l'outil Javadoc commence par les caractères /** et se termine par les caractères */. De même que pour le commentaire précédent, les caractères * devant les lignes intermédiaires sont visuellement agréables, mais non obligatoires. Si vous les ajoutez, Javadoc les retirera de la documentaire finale.

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 
 10 
 11 
 12 
 13 
 14 
 15 
 16 
 17 
 18 

public class Demo {
       
    /*
     * Un commentaire quelconque non exploité par Javadoc
     */   
            
    /**
     * Cette fonction est le point d'entrée de notre programme.
     * Autre blabla explicatif.
     */
    public static void main( String [] args ) {
    
        // Un commentaire simple, non exploité par Javadoc
        System.out.println( "Hello Javadoc" );
    
    }
            
}

L'exemple précédent nous montre qu'un commentaire Javadoc se place obligatoirement avant l'élément à documenter (classe, méthode, attributs, ...). Dans notre exemple, le commentaire Javadoc décrit donc la méthode main.

On documente nos codes Java

Quelques règles à connaître

La première règle, nous l'avons déjà citée : un commentaire Javadoc se place toujours au-dessus de l'élément à documenter. Voici un exemple de commentaire Javadoc décrivant la classe Rational.

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 

/**
 * Cette classe permet de manipuler le concept de nombres rationnels (de fractions).
 * Mathématiquement parlant, un nombre rationnel est constitué d'un numérateur et d'un dénominateur.
 */
public class Rational {

    // Suite de la classe
            
}

La seconde règle importante à respecter est de toujours produire une première phrase (jusqu'au premier caractère .) la plus pertinente possible. Cette première phrase ne doit pas nécessiter la lecture des phrases suivantes pour être comprise. Effectivement c'est elle qui est utilisée dans les sections « Summary » (résumé en français). Voici, à titre d'exemple, la section « Summary » présente dans la documentation du package (fr.koor.poo) contenant notre classe Rational.

Troisième règle, comme la documentation est produite au format HTML, vous pouvez utiliser des tags HTML dans vos commentaires Javadoc. Voici un exemple mettant en gras (tag HTML <b> pour bold) une portion de texte.

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 
 10 

/**
 * Cette classe permet de manipuler le concept de nombres rationnels (de fractions).
 * Mathématiquement parlant, un nombre rationnel est constitué d'un numérateur et d'un dénominateur.
 * Il est important de noter qu'<b>un  dénominateur ne peut, en aucun cas, être nul</b> (valeur 0).
 */
public class Rational {

    // Suite de la classe
            
}

Et voici l'affichage produit dans le navigateur.

Les principaux marqueurs pour documenter une classe

Loin de moi, l'idée de vouloir être exhaustif, mais voici les principaux marqueurs Javadoc utilisable pour documenter une classe.

• @author : permet de mentionner le nom de l'auteur de la classe. Cette information sera poussée dans la Javadoc qu'à la condition que l'option -author soit présente sur la ligne de commande de déclenchement de l'outil Javadoc.

• @deprecated : permet d'indiquer que cette classe est dépréciée et ne doit plus être utilisée.

• @see type : permet de produire des liens hypertextes vers d'autres éléments dans la documentation (des classes, par exemple). Ces liens seront affichés dans la section « See also » (voir aussi).

• @since x.y : permet d'indiquer le numéro de version depuis laquelle la classe est présente dans votre code.

• @version : indique la version actuelle du code.

Voici un exemple de commentaire Javadoc un peu plus riche pour notre classe Rational.

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 
 10 
 11 
 12 
 13 
 14 
 15 
 16 

/**
 * Cette classe permet de manipuler le concept de nombres rationnels (de fractions).
 * Mathématiquement parlant, un nombre rationnel est constitué d'un numérateur et d'un dénominateur.
 * Il est important de noter qu'<b>un  dénominateur ne peut, en aucun cas, être nul</b> (valeur 0).
 * 
 * @author KooR.fr
 * 
 * @see RationalException
 * 
 * @since 1.0
 */
public class Rational {

    // Suite de la classe
            
}

Les principaux marqueurs pour documenter une méthode

Voici une liste des principaux marqueurs Javadoc pouvant être utilisé pour documenter une méthode.

• @deprecated : permet d'indiquer que cette méthode est dépréciée et ne doit plus être utilisée.

• @exception exceptionType description : permet de documenter la remonter d'un type d'exception. La description de ce type d'exception cours jusqu'au prochain marqueur Javadoc.

• @param paramName description : permet de documenter un paramètre de méthode. Il faut nommer le paramètre à documenter. La description de ce paramètre cours jusqu'au prochain marqueur Javadoc.

• @return description : permet de documenter la valeur de retour de la méthode. La description de cette valeur de retour cours jusqu'au prochain marqueur Javadoc.

• @see type#member : permet de produire des liens hypertextes vers d'autres méthodes dans la documentation. Elle cas de surcharge de méthodes, il est possible de spécifier la signature de la méthode ciblée pour lever l'ambiguïté. Ces liens seront affichés dans la section « See also » (voir aussi).

• @since x.y : permet d'indiquer le numéro de version depuis laquelle la classe est présente dans votre code.

• @throws exceptionType description : synonyme de @exception.

L'exemple de code ci-dessous montre la classe Rational avec tous ses éléments, visibles de l'extérieur, documentés. Selon la nature de la méthode, certains marqueurs Javadoc sont utilisés.

 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 
 112 
 113 
 114 
 115 
 116 
 117 
 118 
 119 
 120 
 121 
 122 
 123 
 124 
 125 
 126 
 127 
 128 
 129 
 130 
 131 
 132 
 133 
 134 
 135 
 136 
 137 
 138 
 139 
 140 
 141 
 142 
 143 
 144 
 145 
 146 
 147 
 148 
 149 
 150 
 151 
 152 
 153 
 154 
 155 
 156 
 157 
 158 
 159 
 160 
 161 
 162 
 163 
 164 
 165 
 166 
 167 
 168 
 169 
 170 
 171 
 172 
 173 
 174 
 175 
 176 
 177 
 178 
 179 
 180 
 181 
 182 
 183 
 184 
 185 

package fr.koor.poo;

/*
 * Cette classe fait partie du tutoriel/cours de programmation Java disponible à l'adresse suivante :
 * http://koor.fr/Java/Tutorial/Index.wp
 */

/**
 * Cette classe permet de manipuler le concept de nombres rationnels (de fractions).
 * Mathématiquement parlant, un nombre rationnel est constitué d'un numérateur et d'un dénominateur.
 * Il est important de noter qu'<b>un  dénominateur ne peut, en aucun cas, être nul</b> (valeur 0).
 * 
 * @author KooR.fr
 * 
 * @see RationalException
 * 
 * @since 1.0
 */
public class Rational {

    private int numerator;
    private int denominator;
    
    /**
     * Ce constructeur produit un rationnel par défaut, soit [0/1].
     * 
     * @since 1.0
     */
    public Rational()  {
        this.numerator = 0;
        this.denominator = 1;
    }
        
    /**
     * Ce constructeur produit un rationnel avec le numérateur et le dénominateur spécifiés.
     * 
     * @param numerator La valeur du numérateur
     * @param denominator La valeur du dénominateur
     * 
     * @exception RationalException Déclenchée si vous passez un dénominateur à 0.
     * 
     * @since 1.0
     */
    
    public Rational( int numerator, int denominator ) throws RationalException {
        this.setNumerator( numerator );
        this.setDenominator( denominator );
    }
    
    /**
     * Retourne la valeur du numérateur pour le rationnel courant.
     * 
     * @return La valeur du numérateur.
     * 
     * @see Rational#setDenominator(int)
     * 
     * @since 1.0
     */
    public int getNumerator() {
        return this.numerator;
    }
    
    /**
     * Modifie la valeur du numérateur.
     * 
     * @param numerator La nouvelle valeur pour le numérateur.
     * 
     * @see Rational#getNumerator()
     * 
     * @since 1.0
     */
    public void setNumerator(int numerator) {
        this.numerator = numerator;
    }
    
    /**
     * Retourne la valeur du dénominateur pour le rationnel courant.
     * 
     * @return La valeur du dénominateur.
     * 
     * @see Rational#getDenominator()
     * 
     * @since 1.0
     */
    public int getDenominator() {
        return denominator;
    }
    
    /**
     * Modifie la valeur du dénominateur. Attention, celui-ci ne peut pas être fixé à 0.
     * 
     * @param denominator La nouvelle valeur, non nulle, pour le dénominateur.
     * 
     * @exception RationalException Déclenchée si vous passez un dénominateur à 0.
     * 
     * @see Rational#getNumerator()
     * 
     * @since 1.0
     */
    public void setDenominator(int denominator) throws RationalException {
        if ( denominator == 0 ) {
            throw new RationalException( "Denominator cannot be nul !!!!!" );
        }
        this.denominator = denominator;
    }

    /**
     * Ajoute deux nombres rationnels et produit un nouveau nombre rationnel.
     * 
     * @param r2 Le second rationnel à ajouter à this. 
     *  
     * @return La somme de deux rationnels.
     * 
     * @since 1.0
     */
    public Rational add( Rational r2 ) {
        Rational result = new Rational();
        result.numerator = this.numerator * r2.denominator + this.denominator * r2.numerator;
        result.denominator = this.denominator * r2.denominator;
        return result;
    }
    
    /**
     * Compare deux nombres rationnels entre eux et indique si le premier est plus petit que le second.
     * 
     * @param r2 Le second rationnel à comparer à this.
     * 
     * @return true si this est inféreur à r2, false sinon.
     * 
     * @since 1.0
     */
    public boolean lessThan( Rational r2 ) {
        return this.numerator*r2.denominator < this.denominator * r2.numerator;
    }
    
    /**
     * Simplifie la faction en divisant le numérateur et le dénominateur par leur diviseur commun.
     * 
     * @since 1.0
     */
    public void simplify() {
        int divisor = pgcd( this.numerator, this.denominator);
        this.numerator /= divisor;
        this.denominator /= divisor;
    }
    
    
    /**
     * Produit la chaîne de caractères de représentation de notre nombre rationnel.
     * Le format de sortie est [num/den].
     * 
     * @since 1.0
     */
    @Override
    public String toString() {
        return String.format( "[%d/%d]", this.numerator, this.denominator );
    }
    
    /**
     * Cette méthode permet de calculer le PGCD (plus grand diviseur commun) de deux nombres entiers.
     * L'algorithme d'Euclide est utilisé dans cette implémentation :
     * <a href="https://fr.wikipedia.org/wiki/Algorithme_d%27Euclide#Description_de_l'algorithme" target="_blank">
     *     https://fr.wikipedia.org/wiki/Algorithme_d%27Euclide#Description_de_l'algorithme
     * </a>
     * 
     * @param first Un premier entier.
     * @param second Le second entier.
     * 
     * @return Le PGCD de des entiers passés en paramètres
     * 
     * @since 1.0
     */
    private static int pgcd( int first, int second ) {
        int a = Math.max( first, second );
        int b = Math.min( first, second );
        
        while( b != 0 ) {
            int rest = a % b;
            a = b;
            b = rest;
        }
        return a;
    }

}

Vous pouvez consulter la page HTML Javadoc associée cette classe en activant ce lien hypertexte.

Outils alternatifs

Dès sa première version, l'outil Javadoc a connu un grand succès auprès des développeurs Java. A tel point que d'autres communautés de développeurs ont voulus avoir des équivalents pour leurs langages.

En octobre 1997, le projet Doxygen débute. Doxygen est la contraction de « dox » (« docs », abréviation pour documents) et de « gen » (abréviation pour generator), le « y » étant rajouté pour rendre le nom plus « sexy ». L'outil est téléchargeable sur le site http://www.doxygen.nl/.

Initialement orienté C/C++, l'outil supporte aujourd'hui un très grand nombre de langages de programmation (C, C++, Python, Perl, ...) et y compris Java. Il est donc aussi possible d'utiliser Doxygen pour produire la documentation de vos codes Java.

A l'instar de Javadoc, Doxygen permet de produire la documentation au format HTML. Mais Doxygen peut aller bien plus loin en produisant aussi des documentations aux formats RTF (Rich Text Format), PDF, Latex, Man page (linux), ...

Outils de monitoring (mémoire/GC) Personnalisation HTML/CSS d'une Javadoc