Commentaires de documentation Java

Java prend en charge trois styles de commentaires :

  • Commentaires sur une seule ligne
  • Commentaires multilignes
  • Commentaires de documentation

Les deux premiers sont respectivement//et/* */, le troisième type est appelé commentaires de documentation, qui commence/**par le délimiteur d'ouverture et se termine*/par le délimiteur de fermeture.

Vous pouvez vous référer à ce qui suit pour les deux premiers types de commentaires :Commentaires Java

Les commentaires de documentation vous permettent d'intégrer des informations sur votre programme dans le programme.

Vous pouvez utiliser l'outil javadoc pour générer les informations et les produire dans un fichier HTML.

Les commentaires de documentation facilitent l'enregistrement des informations de votre programme.

Balises javadoc

L'outil javadoc reconnaît les balises suivantes :

Balise Description Exemple
@author Identifie l'auteur d'une classe @author description
@deprecated Indique une classe ou un membre obsolète @deprecated description
{@docRoot} Indique le chemin vers le répertoire racine du document actuel Chemin du répertoire
@exception Documente une exception levée par une classe @exception exception-name explication
{@inheritDoc} Hérite d'un commentaire de la classe parente immédiate Hérite d'un commentaire de la superclasse immédiate.
{@link} Insère un lien vers un autre sujet {@link name text}
{@linkplain} Insère un lien vers un autre sujet, mais le lien est affiché en police de texte brut Insère un lien en ligne vers un autre sujet.
@param Décrit un paramètre de méthode @param parameter-name explanation
@return Décrit le type de la valeur de retour @return explanation
@see Spécifie un lien vers un autre sujet @see ancre
@serial Décrit une propriété de sérialisation @serial description
@serialData Décrit les données écrites via les méthodes writeObject( ) et writeExternal( ) @serialData description
@serialField Décrit un composant ObjectStreamField @serialField nom type description
@since Indique quand un changement spécifique est introduit @since release
@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 un attribut statique. Affiche la valeur d'une constante, qui doit être un champ statique.
@version Spécifie la version d'une classe @version info

Commentaires de documentation

Après l'ouverture/**la première ligne ou les premières lignes sont la description principale de la classe, de la variable ou de la méthode.

Ensuite, vous pouvez inclure une ou plusieurs@balises diverses. Chaque@balise doit être au début d'une nouvelle ligne ou suivre immédiatement l'astérisque au début d'une ligne*。

Plusieurs balises du même type doivent être regroupées. Par exemple, si vous avez trois@seebalises, vous pouvez les placer l'une après l'autre.

Voici un exemple de commentaire de classe :

/*** Cette classe dessine un diagramme à barres * @author exemple * @version 1.2 */

Ce que javadoc produit

L'outil javadoc prend en entrée le code source de votre programme Java et produit des fichiers HTML contenant les commentaires de votre programme.

Les informations de chaque classe se trouveront dans un fichier HTML séparé. javadoc peut également produire des structures d'arborescence d'héritage et des index.

Comme les implémentations de javadoc diffèrent, la sortie peut également différer. Vous devez vérifier les détails tels que la version de votre système de développement Java et choisir la version appropriée de Javadoc.

Exemple

Voici un exemple simple utilisant des commentaires de documentation. Notez que chaque commentaire apparaît avant l'élément qu'il décrit.

Après avoir été traité par javadoc, le commentaire de la classe SquareNum se trouvera dans SquareNum.html.

Code du fichier SquareNum.java :

import java.io.*; /** * Cette classe démontre les commentaires de documentation * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * Cette méthode renvoie le carré de num. * Ceci est une description multiligne. Vous pouvez utiliser * autant de lignes que vous le souhaitez. * @param num La valeur à mettre au carré. * @return num au carré. */ public double square(double num) { return num * num; } /** * Cette méthode lit un nombre saisi par l'utilisateur. * @return La valeur saisie sous forme de double. * @exception IOException En cas d'erreur de saisie. * @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(); } /** * Cette méthode démontre square(). * @param args Inutilisé. * @return Rien. * @exception IOException En cas d'erreur d'entrée. * @see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Saisir la valeur à mettre au carré : "); val = ob.getNumber(); val = ob.square(val); System.out.println("La valeur au carré est " + val); } }

Comme indiqué ci-dessous, 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
$
Autres extensions