« Programmation Java/Commentaires » : différence entre les versions

Contenu supprimé Contenu ajouté
Copié de la page "bases du langage"
fusion du triplon dans la page "annotations"
Ligne 1 :
<noinclude>{{Programmation Java}}</noinclude>
 
== Principe ==
Un {{w|Commentaire (informatique)|commentaire}} permet d'insérer du texte qui ne sera pas compilé ni interprété.
Il sert à ajouter du texte au code source.
Ligne 11 ⟶ 12 :
Il peut aussi être utilisé pour que le compilateur ignore une partie du code : code temporaire de débogage, code en cours de développement, etc.
 
Par ailleurs, il existe aussi des commentaires interprétables utilisés pour la documentation des classes, appelés ''{{wt|annotation}}s'', et qui seront détaillées [[../Annotations|dans un chapitre ultérieur]].
 
== Syntaxe ==
Les commentaires en Java utilisent la même syntaxe qu'en {{w|C++}} :
Java permet d'insérer des commentaires en utilisant deux syntaxes différentes :
* La séquence <code>//</code> permet d'insérer un commentaire sur une seule ligne, qui se termine donc à la fin de la ligne.
* La séquence <code>/*</code> permet d'insérer un commentaire sur plusieurs lignes. La séquence <code>*/</code> marque la fin du commentaire. En d'autres termes, tout ce qui est situé entre <code>/*</code> et <code>*/</code> est considéré comme faisant partie du commentaire.
 
=== Exemples ===
*La séquence <code>//</code> permet d'insérer un commentaire sur une seule ligne, qui se termine donc à la fin de la ligne.
 
*La séquence <code>/*</code> permet d'insérer un commentaire sur plusieurs lignes. La séquence <code>*/</code> marque la fin du commentaire. En d'autres termes, tout ce qui est situé entre <code>/*</code> et <code>*/</code> est considéré comme faisant partie du commentaire.
 
Exemple :
<source lang="java">
// Commentaire sur une ligne
public class /* un commentaire au milieu de la ligne */ Exemple {
/*
Commentaire sur
plusieurs lignes
...
*/
public static void main(String[] args) {
}
}
</source>
 
==== Commentaire Javadoc ====
Les commentaires normaux sont totalement ignorés par le compilateur Java.
 
En revanche, certains commentaires sont interprétés par le générateur automatique de documentation Javadoc.
 
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.
 
Exemple :
<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.
 
 
 
 
 
== Syntaxe ==
Les commentaires en Java utilisent la même syntaxe qu'en C++.
 
Un commentaire de fin de ligne commence par un double slash et se termine au retour à la ligne.
 
Exemple :
<source lang="java">
// Un commentaire pour donner l'exemple
Ligne 93 ⟶ 26 :
</source>
 
Un commentaire sur plusieurs lignes est encadré par slash + étoile, et étoile + slash.
 
Exemple :
<source lang="java">
/*
Ligne 108 ⟶ 38 :
while (a-->0) System.out.println("DEBUG: tab["+a+"]="+tab[a]);
*/
</source>
 
== Documentation des classes ==
Java permet de documenter les classes et leurs membres en utilisant une syntaxe particulière des commentaires.
 
=== Syntaxe ===
Un commentaire de documentation est encadré par slash-étoile-étoile et étoile-slash (soit /** ... */).
La documentation est au format HTML.
 
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 ''[[../Annotations|annotations]]''.
 
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>).
|}
 
=== Documentation ===
Le JDK fournit un outil nommé javadoc qui permet de générer la documentation des classes correctement commentées.
 
La commande javadoc sans argument donne la syntaxe complète de la commande.
 
Exemple : pour une [[Programmation Java/Les classes en Java|classe]] nommée <code>Exemple</code> définie dans un ''[[Programmation Java/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>