Java - Commentaires sur la documentation
Le langage Java supporte trois types de commentaires −
| Sr.No. | Commentaire et description |
|---|---|
| 1 | |
| 2 | |
| 3 |
Ce chapitre est consacré à l'explication de 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 une documentation de code Java au format HTML à partir du code source Java, ce 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 multilignes Java. De même, la ligne qui précède // est un commentaire Java sur une seule ligne.
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
....
pour le titre eta é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 −
| Balise | Description | Syntaxe |
|---|---|---|
| @author | 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 relatif vers le répertoire racine du document généré à partir de n'importe quelle page générée. | {@docRoot} |
| @deprecated | Ajoute un commentaire indiquant que cette API ne doit plus être utilisée. | @deprecated deprecatedtext |
| @exception | Ajoute un lancer sous-titre de la documentation générée, avec le nom de la classe et le texte de description. | @exception classe-nom description |
| {@inheritDoc} | Hérite d'un commentaire du plus proche classe héritable ou interface implémentable. | Hérite d'un commentaire de la superclasse immédiate. |
| {@link} | Insère un lien en ligne avec l'étiquette de texte visible qui pointe vers la documentation du package, de la classe ou du nom de membre spécifié d'une classe référencée. | {@link package.class#member label} |
| {@linkplain} | Identique à {@link}, sauf que l'étiquette du lien est affichée en texte brut plutôt que la police du code. | {@linkplain package.class#member label} |
| @param | Ajoute un paramètre avec le nom de paramètre spécifié suivi de la description spécifiée à la section "Paramètres". | Description du nom du paramètre @param |
| @return | 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 la référence. | @voir référence |
| @série | Utilisé dans le commentaire de la documentation pour un champ sérialisable par défaut. | @description du champ série | inclure | exclure |
| @serialData | Documente les données écrites par les méthodes writeObject( ) ou writeExternal( ). | @serialData data-description |
| @serialField | Documente un composant ObjectStreamField. | @serialField field-name field-type field-description |
| @depuis | Ajoute un en-tête "Since" 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 |
| {@value} | 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 excellent stylesheet.css , nous vous suggérons donc de télécharger et d'utiliser la feuille de style standard de https://docs.oracle.com/javase/7/docs/api/stylesheet.css
Java