Commentaires sur la documentation Java
Java n'a que trois méthodes d'annotation. Les deux premiers sont // et /* */, et le troisième type est appelé commentaire de description, qui se termine par /**Commencez par*/.
Les commentaires de description vous permettent d'intégrer des informations sur le programme au sein du programme. Vous pouvez utiliser le logiciel outil javadoc pour générer des informations et les afficher dans un fichier HTML.
Les commentaires explicatifs vous permettent d'enregistrer des informations sur votre programme de manière plus complète.
balise javadoc
Le logiciel outil javadoc reconnaît les balises suivantes :
| Balises | Description | Exemple |
|---|---|---|
| @auteur | Identifier l'auteur d'un cours | Description de l'@auteur |
| @obsolète | Nommez une classe ou un membre expiré | @description obsolète |
| {@docRoot} | Spécifiez le chemin d'accès au répertoire racine du document actuel | Chemin du répertoire |
| @exception | Marquer une exception levée par une classe | @exception explication du nom de l'exception |
| {@inheritDoc} | Annotations héritées de la classe parent directe | Hérite d'un commentaire de la surclasse immédiate. |
| {@link} | Insérer un lien vers un autre sujet | {@link name text} |
| {@linkplain} | Insérez un lien vers un autre sujet, mais affichez le lien en texte brut | Insère un lien en ligne vers un autre sujet. |
| @param | Décrire les paramètres d'une méthode | Explication du nom du paramètre @param |
| @retour | Décrivez le type de valeur de retour | @return explication |
| @voir | Spécifiez un lien vers un autre sujet | @voir l'ancre |
| @série | Décrire un attribut de sérialisation | @description de la série |
| @serialData | Décrivez les données écrites via les méthodes writeObject() et writeExternal() | @serialDatadescription |
| @serialField | Décrire un composant ObjectStreamField | Description du type de nom @serialField |
| @depuis | Marquer quand un changement spécifique est introduit | @depuis la sortie |
| @throws | Identique à la balise @exception. | La balise @throws a la même signification que la balise @exception. |
| {@value} | Affiche la valeur d'une constante, qui doit être une propriété statique. | Affiche la valeur d'une constante, qui doit être un champ statique. |
| @version | Précisez la version de la classe | @info version |
Commentaires sur la documentation
Après l'ouverture /**, la ou les premières lignes concernent les classes, les variables et les méthodes. Le principal description.
Après, vous pouvez inclure une ou plusieurs balises @ de toute nature. Chaque balise @ doit être au début d'une nouvelle ligne ou immédiatement suivie d'un astérisque (*) en début de ligne
Plusieurs balises du même type doivent être regroupées. Par exemple, si vous disposez de trois balises @see, placez-les l’une après l’autre.
Ce qui suit est un exemple de commentaire de description de classe :
/*** This class draws a bar chart. * @author Zara Ali * @version 1.2 */
Que produit javadoc ?
L'outil javadoc prend le code source de votre programme Java comme entrez et sortez quelque chose contenant un fichier HTML pour les commentaires de votre programme.
Les informations pour chaque classe seront dans un fichier HTML séparé. Javadoc peut également générer des arborescences et des index hérités.
Étant donné que l'implémentation de javadoc est différente, le travail peut être différent. Vous devez vérifier la version de votre système de développement Java et d'autres détails pour choisir la version Javadoc appropriée.
Exemple
Ce qui suit est un exemple simple d'utilisation des commentaires de description. Notez que chaque commentaire précède l'élément qu'il décrit.
Après le traitement javadoc, les commentaires de la classe SquareNum se retrouveront dans SquareNum.html.
import java.io.*;
/**
* This class demonstrates documentation comments.
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
/**
* This method returns the square of num.
* This is a multiline description. You can use
* as many lines as you like.
* @param num The value to be squared.
* @return num squared.
*/
public double square(double num) {
return num * num;
}
/**
* This method inputs a number from the user.
* @return The value input as a double.
* @exception IOException On input error.
* @see IOException
*/
public double getNumber() throws IOException {
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* This method demonstrates square().
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
SquareNum ob = new SquareNum();
double val;
System.out.println("Enter value to be squared: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("Squared value is " + val);
}
}est la suivante, utilisez l'outil javadoc pour traiter le fichier SquareNum.java :
$ javadoc SquareNum.java Loading source file SquareNum.java... Constructing Javadoc information... Standard Doclet version 1.5.0_13 Building tree for all the packages and classes... Generating SquareNum.html... SquareNum.java:39: 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... Generating stylesheet.css... 1 warning $
