Java/Annexe/Documenter un programme
Il existe trois types de commentaires en Java :
- commentaires sur une ligne. Ils débutent par « // » et s'arrêtent à la fin de la ligne ;
- commentaires sur une ou plusieurs lignes. Ils débutent par « /* » et se terminent par « */» ;
- commentaires Javadoc, sur une ou plusieurs lignes. Ils commencent par « /** » et se terminent par « */ ».
Les commentaires javadoc permettent de créer grâce à une petite commande une documentation en HTML. Cette documentation est donc consultable à l'aide d'un navigateur Web comme par exemple Firefox. Les IDEs permettent également de voir la documentation au survol du nom de l'entité (méthode, classe, attribut...) ou lors de l'autocomplétion.
Installation
[modifier | modifier le wikicode]Lorsque vous installez le JDK de Sun, vous installez aussi, peut-être sans le savoir, « Javadoc ».
Commentez
[modifier | modifier le wikicode]Vous pouvez commenter une classe, un champ ou une méthode. Les commentaires se trouvent juste au dessus de ce que vous voulez commenter et utilisent la syntaxe
/** * bla bla .... * bla bla ... */
Certains IDE (Eclipse par exemple) facilitent la création des commentaires de documentation à la frappe de la touche entrée à la fin de la ligne marquant le début de la documentation /**
Exemple :
/**
public int somme(int[] nombres)
Après frappe de la touche entrées, l'IDE ajoute un modèle à compléter adapté à l'entité documentée située juste en dessous. Pour la méthode précédente :
/**
*
* @param nombres
* @return
*/
public int somme(int[] nombres)
Il ne reste plus qu'à compléter les vides : description générale de la méthode, de chaque paramètre et de la valeur retournée. Par exemple :
/**
* Calcul de la somme des nombres d'un tableau.
* @param nombres Le tableau des nombres dont on calcule la somme.
* @return La somme des nombres du tableau.
*/
public int somme(int[] nombres)
Exceptions
[modifier | modifier le wikicode]Chaque type d'exception lançable par la méthode doit également être documenté : décrire dans quelles circonstances ce type d'exception est lancé, et si possible comment résoudre le problème.
Syntaxe :
@throws type description
Ou
@exception type description
Exemple :
/**
* Calcul de la somme des nombres d'un tableau.
* @param nombres Le tableau des nombres dont on calcule la somme.
* @return La somme des nombres du tableau.
* @throws ListeVideException La liste des nombres est vide.
*/
public int somme(int[] nombres) throws ListeVideException
Références à d'autres méthodes
[modifier | modifier le wikicode]Il est recommandé d'ajouter des références aux méthodes relatives au même groupe d'opérations, aux classes fortement liées...
Syntaxe (recommandé) :
@see ref
Syntaxe :
@see ref texte
- texte
- Le texte définit ce qui est affiché.
- Il est optionnel et en son absence, la référence est affiché.
- Il est recommandé de ne pas afficher de texte alternatif et de laisser la référence visible.
- ref
- La référence est le nom de la classe suivi du nom du membre de la classe, séparés par le caractère
#. - La classe n'est pas nécessaire quand le membre est dans la même classe.
- Il peut s'agir aussi du nom de la classe pour faire référence à la classe au lieu d'un membre particulier.
- Quand il s'agit d'une méthode, le nom du membre doit être suivi de la liste des types des paramètres entre parenthèses.
La plupart des IDE permettent une auto-complétion pour les références.
Exemple :
/**
* Calcul de la somme des nombres d'un tableau.
* @param nombres Le tableau des nombres dont on calcule la somme.
* @return La somme des nombres du tableau.
* @see #produit(int[])
*/
public int somme(int[] nombres)
Les mots-clés
[modifier | modifier le wikicode]Certains mots-clés ont une signification particulière, ils sont précédés par "@"
- author
- deprecated
- exception
- override
- param
- return
- since
- see
- serial
- serialData
- serialField
- throws
- version
Générer la documentation
[modifier | modifier le wikicode]Pour générer la documentation, tapez « javadoc MonProgramme.java ». Remplacez bien sûr « MonProgramme » par le nom de votre programme.
Par défaut, javadoc ne génére pas la documentation pour les commentaires au-dessus d'une méthode ou d'un champ possédant le modificateur « private ». Ce qui est logique pour une documentation destinée à ceux qui vont utiliser les classes de manière externe, sans accès aux membres privés depuis leur propres classes.
Cependant, la documentation des membres privés peut être utile aux développeur des classes concernées.
De même, les développeurs qui utilisent les classes d'un package depuis leurs propres packages n'ont pas besoin de la documentation des membres protégés.
La commande javadoc possède donc des options pour le niveau de documentation voulu :
-public: ne documenter que les membres publics.-protected: ne documenter que les membres publics et protégés.-package: ne documenter que les membres publics, protégés et package (sans mot-clé).-private: documenter tous les membres (publics, protégés, package, privés).
Description du package
[modifier | modifier le wikicode]La page de description d'un paquetage copie le texte de description à partir d'un fichier nommé package.html qui doit se situer dans le répertoire correspondant.
Par exemple pour un package nommé "org.wikiversity.fr" situé dans un répertoire nommé "C:\ProgJava", il faut documenter le paquetage dans le fichier C:\ProgJava\org\wikiversity\fr\package.html.
Dans les versions récentes de Java, le fichier package.html peut être remplacé par un fichier Java spécial nommé package-info.java contenant uniquement la déclaration du paquetage (package) précédée d'un commentaire de documentation.
Exemple (C:\ProgJava\org\wikiversity\fr\package-info.java) :
/**
Ce paquetage fictif sert à illustrer le cours sur Java
de <i>fr.wikiversity.org</i>.
*/
package org.wikiversity.fr;
