# Programmation Java/Tags Javadoc

* Introduction
* La notion de machine virtuelle
* Installation
** NetBeans
** Eclipse
** Visual Studio Code
* Bases du langage
** Premier programme
** Commentaires
** Types de base
** Opérateurs
** Conditions
** Bloc de portée
** Itérations
** Tableaux
* Les classes en Java
** Membres
** Modificateurs d'accès
** Héritage
** Encapsulation
** Polymorphisme
** Classes abstraites
** Interfaces
** Classes internes
** Transtypage
** Types génériques
** Instanciation et cycle de vie
** « this »
** Objets comparables et clés
** Énumérations
** Exceptions
** Packages
* Classes de base
** Collections
** Nombre de taille arbitraire
** Tags Javadoc
** Annotations
** Entrées sorties
** Threads et synchronisation
** Méthodes natives
** Réflexion
** Regex
** JUnit
* Conclusion
* Exemples en Java
** Générer un carré magique
** Générer un triangle de Sierpiński
** XML
** Swing
*** Un premier exemple
*** Formulaire avec boutons sur image
*** Calcul de somme
*** Calcul de distance
* Annexes
** Les outils de base fournis avec le Java Development Kit
** Créer une archive Java
** Paramétrer la JVM
** Liste des mots réservés
** Débogage
** Java et les autres langages
* Introduction
* La notion de machine virtuelle
* Installation
** NetBeans
** Eclipse
** Visual Studio Code
* Bases du langage
** Premier programme
** Commentaires
** Types de base
** Opérateurs
** Conditions
** Bloc de portée
** Itérations
** Tableaux
* Les classes en Java
** Membres
** Modificateurs d'accès
** Héritage
** Encapsulation
** Polymorphisme
** Classes abstraites
** Interfaces
** Classes internes
** Transtypage
** Types génériques
** Instanciation et cycle de vie
** « this »
** Objets comparables et clés
** Énumérations
** Exceptions
** Packages
* Classes de base
** Collections
** Nombre de taille arbitraire
** Tags Javadoc
** Annotations
** Entrées sorties
** Threads et synchronisation
** Méthodes natives
** Réflexion
** Regex
** JUnit
* Conclusion
* Exemples en Java
** Générer un carré magique
** Générer un triangle de Sierpiński
** XML
** Swing
*** Un premier exemple
*** Formulaire avec boutons sur image
*** Calcul de somme
*** Calcul de distance
* Annexes
** Les outils de base fournis avec le Java Development Kit
** Créer une archive Java
** Paramétrer la JVM
** Liste des mots réservés
** Débogage
** Java et les autres langages
[ Modifier le sommaire ]
Java permet de documenter les classes et leurs membres en utilisant une syntaxe particulière des commentaires. Ils sont alors interprétés par le générateur automatique de documentation Javadoc, fourni par le JDK. La commande javadoc sans argument donne la syntaxe complète de la commande.
Ces commentaires commencent par la séquence /** et se terminent par */. Le contenu décrit l'entité qui suit (classe, interface, méthode ou attribut), suivi d'une série d'attributs dont le nom commence par un arobase @.
La documentation générée étant au format HTML, il est possible d'insérer des balises dans la description.

## Exemples
### Exemple 1

Le commentaire de documentation se place juste avant l'entité commentée (classe, constructeur, méthode, champ).
Dans un commentaire de documentation, la première partie est un texte de description au format HTML. La seconde partie est une liste d'attributs spéciaux dont le nom commence par un arobase (@). Ces derniers sont interprétables par le compilateur et appelés tags.

### Exemple 2

En fait, il existe un attribut Javadoc qui est pris en compte par le compilateur : l'attribut @deprecated. Cet attribut marque une classe, une méthode ou une variable comme obsolète. Ce qui signifie que si une autre classe l'utilise un avertissement est affiché à la compilation de cette classe.
Exemple :
Cet attribut permet de modifier une bibliothèque de classe utilisée par plusieurs applications, en la laissant compatible avec les applications utilisant l'ancienne version, mais en indiquant que les anciennes classes / méthodes / variables ne doivent plus être utilisées et pourraient ne plus apparaître dans une version ultérieure.

### Exemple 3

Exemple pour la méthode suivante :

#### Obtenir la somme de deux entiers.

    Description de la méthode somme.

#### @param a Le premier nombre entier.

    Attribut de description du paramètre a de la méthode.

#### @param b Le deuxième nombre entier.

    Attribut de description du paramètre b de la méthode.

#### @return La valeur de la somme des deux entiers spécifiés.

    Attribut de description de la valeur retournée par la méthode.
Voici une liste non exhaustive des attributs spéciaux :
| Attribut et syntaxe | Dans un commentaire de ... | Description |
| @author auteur | classe | Nom de l'auteur de la classe. |
| @version version | classe | Version de la classe. |
| @deprecated description | classe, constructeur, méthode, champ | Marquer l'entité comme obsolète (ancienne version), décrire pourquoi et par quoi la remplacer. Si l'entité marquée comme obsolète par cet attribut est utilisée, le compilateur donne un avertissement. |
| @see référence | classe, constructeur, méthode, champ | Ajouter un lien dans la section "Voir aussi". |
| @param description de l'id | constructeur et méthode | Décrire un paramètre de méthode. |
| @return description | méthode | Décrire la valeur retournée par une méthode. |
| @exception description du type | constructeur et méthode | Décrire les raisons de lancement d'une exception du type spécifié (clause throws). |

### Exemple 4

Exemple pour une classe nommée Exemple définie dans un package nommé org.wikibooks.fr dans le fichier C:\ProgJava\org\wikibooks\fr\Exemple.java :

## Références

Dans la documentation, il est souvent nécessaire de faire référence à une autre entité (méthode, champ, classe) appartenant à la même classe, une autre classe ou un autre package. Certains tags Javadoc sont dédiés aux références :
* @see permet d'ajouter des références dans une section « Voir aussi » ("See also" en anglais) de la documentation de la méthode, du champ, de la classe ou du package.
* @link permet d'ajouter une référence au milieu du texte de la description.
* @value permet d'ajouter la valeur d'une constante au milieu du texte de la description.
Les deux derniers tags s'insérant au milieu du texte de la description doivent être encadrés par des accolades.
Chaque référence est un lien vers la documentation de l'entité référencée, et doit suivre la syntaxe suivante :
Elle est composée de deux parties optionnelles :

### classe

    Le nom de la classe (avec le nom du package sauf si importé) est optionnel quand le membre est défini dans la même classe.

### #membre

    Le nom du membre de la classe (champ ou méthode) est absent dans les références à une classe.
   * Pour les champs, le nom est suffisant.
   * Pour les méthodes, le nom doit être suivi du type des paramètres entre parenthèses.

## Générer la documentation

La documentation peut être générée dans un répertoire spécifique (C:\ProgDoc par exemple) avec la commande suivante :
Les options de cette commande sont décrites ci-dessous :

### -locale fr_FR

    La documentation est en français.

### -use

    Créer les pages sur l'utilisation des classes et paquetages (packages).

### -classpath C:\ProgJava

    Le chemin des classes compilées (*.class).

### -sourcepath C:\ProgJava

    Le chemin des classes sources (*.java).

### -d C:\ProgDoc

    Le chemin où la documentation doit être générée.

### org.wikibooks.fr

    Le nom du paquetage (package) à documenter. Il est possible de spécifier plusieurs paquetages, ou un ou plusieurs noms de classe pour ne documenter que celles-ci.

### Niveau de documentation

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. Dans notre exemple, il faut documenter le paquetage dans le fichier C:\ProgJava\org\wikibooks\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\wikibooks\fr\package-info.java) :