Vous êtes ici :
Accueil Cours Programmations La Programmation Orientée Objet en Java Les commentaires de documentation (docblock)

La Programmation Orientée Objet en Java : Les commentaires de documentation (docblock)

Le langage Java prend en charge trois types de commentaires:

Commentaire

La description

/* texte */

Le compilateur ignore tout de / * à */.

//texte

Le compilateur ignore tout de // vers la fin de la ligne.

/** documentation */

Il s'agit d'un commentaire de documentation et en général est appelé  commentaire de doc. L'outil JDK javadoc utilise les commentaires du doc lors de la préparation de la documentation générée automatiquement.

Ce chapitre vise à expliquer javadoc. Nous verrons comment nous pouvons utiliser javadoc pour générer de la documentation utile pour notre code Java.

Qu'est-ce que Javadoc ?

javadoc est un outil livré avec JDK et il est utilisé pour générer de la documentation de code Java au format HTML à partir du code source Java qui a nécessité une documentation dans un format prédéfini.

Voici un exemple simple où la partie entre /** et */ du code représente les commentaires Java:

/**
* 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 ci-dessous utilise <h1> .... </ h1> pour l'en-tête et <p> a été utilisé pour créer une rupture de paragraphe:

/**
* <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 tags javadoc

Les tags javadoc sont des mots clés reconnus par javadoc qui définit le type d'information qui suit.

L'outil javadoc reconnaît les balises suivantes:

Marque

La description

Syntaxe

@author

Ajoute l'auteur d'une classe.

@author name-text

{@code}

Affiche du texte dans une police de code sans interpréter le texte sous forme de marquage HTML ou de tags javadoc imbriqués.

{@code text}

{@docRoot}

Représente le chemin relatif au répertoire racine du document généré à partir de toute page générée

{@docRoot}

@deprecated

Ajoute un commentaire indiquant que cette API ne devrait plus être utilisée.

@deprecated deprecated-text

@exception

Ajoute une sous-catégorie Throws  à la documentation générée, avec le nom de la classe et le texte de description.

@exception class-name description

{@inheritDoc}

hérite un commentaire de la classe parent ou de l'interface implémentable

Hériter un commentaire de la surperclasse.

{@link}

Insère un lien en ligne avec l'étiquette de texte visible qui indique la documentation pour le paquetage spécifié, le nom de classe ou le membre 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 que la police de 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 dans la section "Paramètres".

@param nom-paramètre description

@return

Ajoute une section "return" avec le texte de description.

@return description

@see

Ajoute un titre "Voir aussi" avec un lien ou une entrée de texte qui indique la référence.

@see reference

@serial

Utilisé dans le commentaire de la documentation pour un champ sérialisable par défaut.

@serial field-description | Inclure | exclure

@serialData

Documente les données écrites par les méthodes writeObject () ou writeExternal ()

@serialData data-description

@serialField

Associe un composant ObjectStreamField.

@serialField field-name field-type field-description

@since

Ajoute un titre "depuis" avec le texte spécifié depuis la documentation générée.

@since release

@throws

Les tags @throws et @exception sont des synonymes.

@throws class-name description

{@value}

Lorsque {@value} est utilisé dans le commentaire de doc d'un champ statique, il affiche la valeur de cette constant:

{@value package.class #field}

@version

Ajoute une 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-text

Exemple

Le programme suivant utilise quelques-unes des étiquettes importantes disponibles pour les commentaires de la 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 principal 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, procédez  à la génération du commentaire de documentation du fichier AddNum.java à 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 vérifier toute la documentation générée. Si vous utilisez JDK 1.7, javadoc ne génère pas de stylesheet.css, alors je suggère de télécharger et d'utiliser une feuille de style standard à partir de http://docs.oracle.com/javase/7/docs/api/stylesheet.css




Vous êtes ici :
Accueil Cours Programmations La Programmation Orientée Objet en Java Les commentaires de documentation (docblock)