1. Vue d’ensemble
Une bonne documentation sur les API est l’un des nombreux facteurs contribuant au succès général d’un projet logiciel.
Heureusement, toutes les versions modernes du JDK fournissent l’outil Javadoc, permettant de générer la documentation de l’API à partir des commentaires présents dans le code source.
Conditions préalables:
-
JDK 1.4 (JDK 7+ est recommandé pour la dernière version du logiciel Maven.
Javadoc plugin) . Le dossier JDK /bin ajouté à la variable d’environnement PATH
-
(Facultatif) un IDE qui avec des outils intégrés
Commençons par les commentaires.
-
La structure des commentaires Javadoc est très similaire à celle d’un commentaire multiligne ** , mais la différence essentielle réside dans 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 souhaitons documenter. **
Ces commentaires sont généralement composés de deux sections:
-
La description de ce que nous commentons
-
Les étiquettes de bloc autonomes (marquées du symbole « @ ») qui
décrire des méta-données spécifiques
Nous allons utiliser certaines des balises de bloc les plus courantes dans notre exemple. Pour obtenir une liste complète des balises de blocage, visitez le https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html guide de référence].
2.2. Javadoc au niveau de la classe
Voyons à quoi ressemblerait un commentaire Javadoc de niveau 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 brève description et deux balises de bloc différentes - autonome et inline:
-
Les tags autonomes apparaissent après la description avec le tag en premier
mot en ligne, par exemple, la balise @ author Les tags en ligne peuvent apparaître n’importe où et sont entourés de boucles
entre 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 en ligne vers une partie référencée de notre source
code ** @ author le nom de l’auteur qui a ajouté la classe, la méthode ou le champ
c’est commenté
2.3. Javadoc sur Champ Niveau
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;
----Javadoc n’est généré pour eux dans les champs privés que si nous passons explicitement l’option -private à la commande Javadoc.
2.4. Javadoc à 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:
----/** **
** <p>This is a simple description of the method. . .
** <a href="http://www.supermanisthegreatest.com">Superman!</a>
** </p>
** @param incomingDamage the amount of incoming damage
** @return the amount of health hero has after attack
** @see <a href="http://www.link__to__jira/HERO-402">HERO-402</a>
** @since 1.0
** /public int successfullyAttacked(int incomingDamage) {
//do things
return 0;
}
----La méthode successfullyAttacked contient à la fois une description et de nombreuses balises de bloc autonomes.
Il existe de nombreuses balises de blocage pour aider à générer la documentation appropriée et nous pouvons inclure toutes sortes d’informations. Nous pouvons même utiliser des balises HTML de base dans les commentaires.
Reprenons les balises rencontrées dans l’exemple ci-dessus:
-
@ param fournit une description utile du paramètre d’une méthode ou
entrée il devrait s’attendre ** @ return fournit une description de ce qu’une méthode va ou peut retourner
-
@ see va générer un lien similaire à la balise \ {@ link} , mais plus
le contexte d’une référence et non inline ** @ Since spécifie quelle version la classe, le champ ou la méthode a été ajouté
au projet ** @ version spécifie la version du logiciel, couramment utilisée avec
% I% et% G% de macros ** @ throws est utilisé pour expliquer plus en détail les cas où le logiciel
attendre une exception ** @ deprecated donne une explication de la raison pour laquelle le code est obsolète
peut être obsolète, et quelles sont les alternatives
Bien que les deux sections soient techniquement optionnelles, nous aurons besoin d’au moins une pour que l’outil Javadoc génère quelque chose de significatif.
3. Génération Javadoc
Pour générer nos pages Javadoc, nous voudrons jeter un coup d’œil sur l’outil en ligne de commande fourni avec le JDK et le plugin Maven.
3.1. Outil de ligne de commande Javadoc
L’outil de ligne de commande Javadoc est très puissant, mais il comporte une certaine complexité.
L’exécution de la commande javadoc sans options ni paramètres entraînera une erreur et les paramètres de sortie attendus.
Nous devrons au moins spécifier le paquet ou la classe pour laquelle nous voulons que la documentation soit générée.
Ouvrons une ligne de commande et accédez au répertoire du projet.
En supposant que toutes les classes se trouvent dans le dossier src du répertoire du projet:
----[email protected]:~$ javadoc -d doc src\**
----Cela générera de la documentation dans un répertoire appelé doc , spécifié avec l’indicateur – d . Si plusieurs packages ou fichiers existent, nous ne devrions pas tous les fournir.
L’utilisation d’un IDE avec la fonctionnalité intégrée est, bien sûr, plus simple et généralement recommandée.
3.2. Javadoc avec Maven Plugin
Nous pouvons également utiliser le plugin Maven Javadoc:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
<tags>
...
</tags>
</plugin>
</plugins>
</build>Dans le répertoire de base du projet, nous exécutons la commande pour générer nos Javadocs dans un répertoire dans target \ site:
----[email protected]:~$ mvn javadoc:javadoc
----https://search.maven.org/classic/#search%7Cgav%7C1%7Cg%3A%22org.apache.maven.plugins%22%20AND%20a%3A%22maven-javadoc-plugin%22 de le plugin Maven]est très puissant et facilite la génération de documents complexes de manière transparente.
Voyons maintenant à quoi ressemble une page Javadoc générée:
lien:/uploads/overview-125x125.png%20125w[]
Nous pouvons voir une arborescence des classes de notre classe SuperHero . Nous pouvons voir notre description, nos champs et notre méthode, et nous pouvons cliquer sur les liens pour plus d’informations.
Une vue détaillée de notre méthode ressemble à ceci:
3.3. Balises Javadoc personnalisées
En plus d’utiliser des balises de bloc prédéfinies pour formater notre documentation, nous pouvons également créer des balises de bloc personnalisées.
Pour ce faire, nous devons simplement inclure une option -tag dans notre ligne de commande Javadoc au format <nom-tag>: <emplacements-autorisés>: <en-tête> .
Afin de créer une balise personnalisée appelée @ location autorisée partout, qui est affichée dans l’en-tête «Emplacements remarquables» de notre document généré, nous devons exécuter:
----[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\**
----Pour utiliser cette balise, nous pouvons l’ajouter à la section de bloc d’un commentaire Javadoc:
----/** **
** This is an example...
** @location New York
** @returns blah blah
** /----Le plugin Maven Javadoc est suffisamment souple pour permettre également la définition de nos balises personnalisées dans notre pom.xml .
Afin de configurer la même balise ci-dessus pour notre projet, nous pouvons ajouter ce qui suit à la section <tags> de notre plugin:
...
<tags>
<tag>
<name>location</name>
<placement>a</placement>
<head>Notable Places:</head>
</tag>
</tags>
...De cette façon, nous pouvons spécifier la balise personnalisée une fois au lieu de la spécifier à chaque fois.
4. Conclusion
Ce didacticiel d’introduction rapide explique comment écrire des Javadocs de base et les générer à l’aide de la ligne de commande Javadoc.
Un moyen plus simple de générer la documentation consiste à utiliser les options IDE intégrées ou à inclure le plug-in Maven dans notre fichier pom.xml et à exécuter les commandes appropriées.
Les exemples de code, comme toujours, peuvent être trouvés à over sur GitHub .