Java - Commentaires sur la documentation
Le langage Java prend en charge trois types de commentaires -
| N ° Sr. | Commentaire et description |
|---|---|
| 1 | /* text */ Le compilateur ignore tout de / * à * /. |
| 2 | //text Le compilateur ignore tout de // à la fin de la ligne. |
| 3 | /** documentation */ Ceci est un commentaire de documentation et en général il s'appelle doc comment. leJDK javadocL'outil utilise les commentaires doc lors de la préparation de la documentation générée automatiquement. |
Ce chapitre explique tout sur Javadoc. Nous verrons comment nous pouvons utiliser Javadoc pour générer une documentation utile pour le code Java.
Qu'est-ce que Javadoc?
Javadoc est un outil fourni avec JDK et il est utilisé pour générer la documentation du code Java au format HTML à partir du code source Java, qui nécessite une documentation dans un format prédéfini.
Voici un exemple simple où les lignes à l'intérieur de /*….*/ sont des commentaires multi-lignes Java. De même, la ligne qui précède // est un commentaire d'une seule ligne Java.
Exemple
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}Vous pouvez inclure les balises HTML requises dans la partie description. Par exemple, l'exemple suivant utilise <h1> .... </h1> pour l'en-tête et <p> a été utilisé pour créer un saut de paragraphe -
Exemple
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}Les balises javadoc
L'outil javadoc reconnaît les balises suivantes -
| Marque | La description | Syntaxe |
|---|---|---|
| @auteur | Ajoute l'auteur d'une classe. | @author name-text |
| {@code} | Affiche le texte dans la police du code sans interpréter le texte comme un balisage HTML ou des balises javadoc imbriquées. | {@code text} |
| {@docRoot} | Représente le chemin d'accès relatif au répertoire racine du document généré à partir de n'importe quelle page générée. | {@docRoot} |
| @ déprécié | Ajoute un commentaire indiquant que cette API ne doit plus être utilisée. | @deprecated deprecatedtext |
| @exception | Ajoute un Throws sous-titre de la documentation générée, avec le nom de la classe et le texte de description. | @exception nom-classe description |
| {@inheritDoc} | Hérite d'un commentaire du nearest classe héritable ou interface implémentable. | Hérite d'un commentaire de la surperclasse immédiate. |
| {@lien} | Insère un lien en ligne avec l'étiquette de texte visible qui pointe vers la documentation pour le package, la classe ou le nom de membre spécifié d'une classe référencée. | {@link package.class # label de membre} |
| {@linkplain} | Identique à {@link}, sauf que le libellé du lien est affiché en texte brut plutôt qu'en police de code. | {@linkplain package.class # label membre} |
| @param | Ajoute un paramètre avec le nom de paramètre spécifié suivi de la description spécifiée dans la section "Paramètres". | @param nom-paramètre description |
| @revenir | Ajoute une section «Retours» avec le texte de description. | @return description |
| @voir | Ajoute un en-tête «Voir aussi» avec un lien ou une entrée de texte qui pointe vers une référence. | @voir la référence |
| @en série | Utilisé dans le commentaire doc pour un champ sérialisable par défaut. | @serial champ-description | inclure | exclure |
| @serialData | Documente les données écrites par les méthodes writeObject () ou writeExternal (). | @serialData description des données |
| @serialField | Documente un composant ObjectStreamField. | @serialField nom de champ type de champ description de champ |
| @depuis | Ajoute un en-tête «Depuis» avec le texte depuis spécifié à la documentation générée. | @depuis la sortie |
| @throws | Les balises @throws et @exception sont des synonymes. | @throws description du nom de classe |
| {@valeur} | Lorsque {@value} est utilisé dans le commentaire doc d'un champ statique, il affiche la valeur de cette constante. | {@value package.class # field} |
| @version | Ajoute un sous-titre "Version" avec le texte de version spécifié aux documents générés lorsque l'option -version est utilisée. | @version version-texte |
Exemple
Le programme suivant utilise quelques-unes des balises importantes disponibles pour les commentaires de documentation. Vous pouvez utiliser d'autres balises en fonction de vos besoins.
La documentation sur la classe AddNum sera produite dans le fichier HTML AddNum.html mais en même temps un fichier maître avec un nom index.html sera également créé.
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}Maintenant, traitez le fichier AddNum.java ci-dessus à l'aide de l'utilitaire javadoc comme suit -
$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$Vous pouvez consulter toute la documentation générée ici - AddNum . Si vous utilisez JDK 1.7, javadoc ne génère pas un excellentstylesheet.css, nous vous suggérons donc de télécharger et d'utiliser la feuille de style standard à partir de https://docs.oracle.com/javase/7/docs/api/stylesheet.css