Introduction à Javadoc

1. Vue d'ensemble

Une bonne documentation API est l'un des nombreux facteurs contribuant au succès global d'un projet logiciel.

Heureusement, toutes les versions modernes du JDK fournissent l'outil Javadoc - pour générer la documentation API à partir des commentaires présents dans le code source.

Conditions préalables:

  1. JDK 1.4 (JDK 7+ est recommandé pour la dernière version du plugin Maven Javadoc)
  2. Le dossier JDK / bin ajouté à la variable d'environnement PATH
  3. (Facultatif) un IDE avec des outils intégrés

2. Commentaires Javadoc

Commençons par les commentaires.

La structure des commentaires Javadoc ressemble beaucoup à un commentaire standard sur plusieurs lignes , mais la principale différence est l'astérisque supplémentaire au début:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Les commentaires de style Javadoc peuvent également contenir des balises HTML.

2.1. Format Javadoc

Les commentaires Javadoc peuvent être placés au-dessus de toute classe, méthode ou champ que nous voulons documenter.

Ces commentaires sont généralement composés de deux sections:

  1. La description de ce que nous commentons
  2. Les balises de bloc autonomes (marquées du symbole « @ ») qui décrivent des méta-données spécifiques

Nous utiliserons certaines des balises de bloc les plus courantes dans notre exemple. Pour une liste complète des balises de bloc, consultez le guide de référence.

2.2. Javadoc au niveau de la classe

Voyons à quoi ressemblerait un commentaire Javadoc au niveau de la classe:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Nous avons une courte description et deux balises de bloc différentes - autonomes et en ligne:

  • Les balises autonomes apparaissent après la description avec la balise comme premier mot d'une ligne, par exemple, la balise @author
  • Les balises en ligne peuvent apparaître n'importe où et sont entourées de crochets , par exemple, la balise @link dans la description

Dans notre exemple, nous pouvons également voir deux types de balises de bloc utilisées:

  • {@link} fournit un lien intégré vers une partie référencée de notre code source
  • @author le nom de l'auteur qui a ajouté la classe, la méthode ou le champ commenté

2.3. Javadoc au niveau du terrain

Nous pouvons également utiliser une description sans balises de bloc comme celle-ci dans notre classe SuperHero :

/** * The public name of a hero that is common knowledge */ private String heroName;

Les champs privés ne seront pas générés par Javadoc, sauf si nous transmettons explicitement l' option -private à la commande Javadoc.

2.4. Javadoc au niveau de la méthode

Les méthodes peuvent contenir une variété de balises de bloc Javadoc.

Jetons un coup d'œil à une méthode que nous utilisons:

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

La méthode avec succèsAttacked contient à la fois une description et de nombreuses balises de bloc autonomes.

Il existe de nombreuses balises de bloc pour aider à générer une documentation appropriée et nous pouvons inclure toutes sortes d'informations différentes. Nous pouvons même utiliser des balises HTML de base dans les commentaires.

Passons en revue les balises que nous rencontrons dans l'exemple ci-dessus:

  • @param fournit toute description utile sur le paramètre ou l'entrée d'une méthode à laquelle elle devrait s'attendre
  • @return fournit une description de ce qu'une méthode va ou peut retourner
  • @see générera un lien similaire à la balise {@link} , mais davantage dans le contexte d'une référence et non en ligne
  • @since specifies which version the class, field, or method was added to the project
  • @version specifies the version of the software, commonly used with %I% and %G% macros
  • @throws is used to further explain the cases the software would expect an exception
  • @deprecated gives an explanation of why code was deprecated, when it may have been deprecated, and what the alternatives are

Although both sections are technically optional, we'll need at least one for the Javadoc tool to generate anything meaningful.

3. Javadoc Generation

In order to generate our Javadoc pages, we'll want to take a look at the command line tool that ships with the JDK, and the Maven plugin.

3.1. Javadoc Command Line Tool

The Javadoc command line tool is very powerful but has some complexity attached to it.

Running the command javadoc without any options or parameters will result in an error and output parameters it expects.

We'll need to at least specify what package or class we want documentation to be generated for.

Let's open a command line and navigate to the project directory.

Assuming the classes are all in the src folder in the project directory:

[email protected]:~$ javadoc -d doc src\*

This will generate documentation in a directory called doc as specified with the –d flag. If multiple packages or files exist, we'd need to provide all of them.

Utilizing an IDE with the built-in functionality is, of course, easier and generally recommended.

3.2. Javadoc With Maven Plugin

We can also make use of the Maven Javadoc plugin:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

[email protected]:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Let's now see what a generated Javadoc page looks like:

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

A detailed view of our method looks like this:

3.3. Custom Javadoc Tags

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Ce tutoriel d'introduction rapide a expliqué comment écrire des Javadocs de base et les générer avec la ligne de commande Javadoc.

Un moyen plus simple de générer la documentation serait d'utiliser toutes les options intégrées de l'EDI ou d'inclure le plugin Maven dans notre fichier pom.xml et d'exécuter les commandes appropriées.

Les exemples de code, comme toujours, peuvent être trouvés sur GitHub.