# 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

Lorsque vous installez le JDK de Sun, vous installez aussi, peut-être sans le savoir, « Javadoc ».

## Commentez

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
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 :
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 :
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 :

### Exceptions

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 :
Ou
Exemple :

### Références à d'autres méthodes

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é) :
Syntaxe :

#### 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 :

## Les mots-clés

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

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

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) :
| Sommaire | Nombres |