« Programmation Java/Annotations » : différence entre les versions
Contenu supprimé Contenu ajouté
→Fonctionnement : orthographe |
Copié de "base du langage" + "commentaire" |
||
Ligne 4 :
Ces annotations sont ajoutées dans le code devant les classes et leurs membres (méthodes et champs) pour :
* Ajouter des informations de documentation supplémentaires aux
* Ajouter des contraintes de compilation (voir @Override par exemple),
* Associer des méta-données qui peuvent être retrouvées par réflexion.
Malgré la similarité de syntaxe (arobase + nom) et de nom (@deprecated par exemple), il ne faut pas les confondre avec
De plus, une annotation correspond à un type de données (comme les classes, interfaces et énumérations).
Ceci explique que la documentation d'un package possède une section supplémentaire nommée « ''Annotation Types'' » pour les annotations définies dans le package.
==
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 {{w|Javadoc}}, fourni par le JDK.
La commande <code>javadoc</code> sans argument donne la syntaxe complète de la commande.
Ces commentaires commencent par la séquence <code>/**</code> et se terminent par <code>*/</code>. 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 <code>@</code>.
La documentation générée étant au format HTML, il est possible d'insérer des balises dans la description.
=== Exemples ===
Exemple :
<source lang="java">
/**
Une classe pour donner un <b>exemple</b> de documentation HTML.
*/
public class Exemple {
/** ...Documentation du membre de type entier nommé exemple... */
public int exemple;
</source>
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
==== Exemple 1 ====
<source lang="java">
/**
Une classe pour illustrer les commentaires Javadoc.
@author Moi :-)
*/
public class Exemple {
/**
Une méthode <b>main</b> qui ne fait rien.
@param args Les arguments de la ligne de commande.
*/
public static void main(String[] args) {
}
}
</source>
En fait, il existe un attribut Javadoc qui est pris en compte par le compilateur : l'attribut <code>@deprecated</code>. 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 :
<source lang="java">
/**
Une méthode obsolète. Il faut utiliser get() à la place.
@deprecated
*/
public Object getElement(int index)
{ ... }
/**
Une nouvelle méthode.
*/
public Object get(int index)
{ ... }
</source>
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 2 ====
Exemple pour la méthode suivante :
<source lang="java">
/**
Obtenir la somme de deux entiers.
@param a Le premier nombre entier.
@param b Le deuxième nombre entier.
@return La valeur de la somme des deux entiers spécifiés.
*/
public int somme(int a, int b) {
return a + b;
}
</source>
;<code>Obtenir la somme de deux entiers.</code>:Description de la méthode somme.
;<code>@param a Le premier nombre entier.</code>:Attribut de description du paramètre a de la méthode.
;<code>@param b Le deuxième nombre entier.</code>:Attribut de description du paramètre b de la méthode.
;<code>@return La valeur de la somme des deux entiers spécifiés.</code>:Attribut de description de la valeur retournée par la méthode.
Voici une liste non exhaustive des attributs spéciaux :
{| class="wikitable" border="1"
! Attribut et syntaxe
! Dans un commentaire de ...
! Description
|-----
| @author ''auteur''
| classe
| Nom de l'auteur de la classe.
|-{{ligne grise}}
| @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.
|-{{ligne grise}}
| @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.
|-{{ligne grise}}
| @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 <code>throws</code>).
|}
==== Exemple 3 ====
Exemple pour une [[../Les classes en Java|classe]] nommée <code>Exemple</code> définie dans un ''[[../Extensions|package]]'' nommé <code>org.wikibooks.fr</code> dans le fichier <code>C:\ProgJava\org\wikibooks\fr\Exemple.java</code> :
<source lang="java">
package org.wikibooks.fr;
/**
Une classe d'exemple.
*/
public class Exemple {
/**
Obtenir la somme de deux entiers.
@param a Le premier nombre entier.
@param b Le deuxième nombre entier.
@return La valeur de la somme des deux entiers spécifiés.
*/
public int somme(int a, int b) {
return a + b;
}
}
</source>
La documentation peut être générée dans un répertoire spécifique (C:\ProgDoc par exemple) avec la commande suivante :
javadoc -locale fr_FR -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.wikibooks.fr
Les options de cette commande sont décrites ci-dessous :
;<code>-locale fr_FR</code>:La documentation est en français.
;<code>-use</code>:Créer les pages sur l'utilisation des classes et paquetages (''packages'').
;<code><nowiki>-classpath C:\ProgJava</nowiki></code>:Le chemin des classes compilées (*.class).
;<code><nowiki>-sourcepath C:\ProgJava</nowiki></code>:Le chemin des classes sources (*.java).
;<code><nowiki>-d C:\ProgDoc</nowiki></code>:Le chemin où la documentation doit être générée.
;<code>org.wikibooks.fr</code>: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.
La page de description d'un paquetage copie le texte de description à partir d'un fichier nommé <code>package.html</code> qui doit se situer dans le répertoire correspondant. Dans notre exemple, il faut documenter le paquetage dans le fichier <code>C:\ProgJava\org\wikibooks\fr\package.html</code>.
Dans les versions récentes de Java, le fichier <code>package.html</code> peut être remplacé par un fichier Java spécial nommé <code>package-info.java</code> contenant uniquement la déclaration du paquetage (''package'') précédée d'un commentaire de documentation.
Exemple (<code>C:\ProgJava\org\wikibooks\fr\package-info.java</code>) :
<source lang="java5">
/**
Ce paquetage fictif sert à illustrer le livre sur Java
de <i>fr.wikibooks.org</i>.
*/
package org.wikibooks.fr;
</source>
== Annotations ==
Toute entité (classe, interface, méthode ou champ) peut être précédée d'une ou plusieurs annotations contenant des méta-données renseignant le compilateur ou l'application elle-même.
Ligne 22 ⟶ 185 :
La liste des paramètres entre parenthèses est optionnelle (vide par défaut). Elle contient une série de valeurs associées à un nom de champ définit par l'annotation.
==== Exemples ====
Exemple 1 :
<source lang="java">
| |||