Remerciez-le!

Remerciez @Admin pour avoir partagé cet document gratuitement, de la manière la plus simple, en partageant sur les réseaux sociaux.

javadoc Université de Nice - Sophia Antipolis p p Richard Grin Version 1 4 1 –

javadoc Université de Nice - Sophia Antipolis p p Richard Grin Version 1 4 1 – 8/2/11 Version 1.4.1 8/2/11 Généralités Généralités javadoc produit de la documentation en partant de javadoc produit de la documentation en partant de commentaires particuliers insérés dans le code source des classes (/** */) source des classes (/ . . . /) On peut ainsi documenter t n paquetages n classes ou interfaces n variables d'instance n méthodes méthodes Sauf pour les paquetages, les commentaires doivent être placés juste avant ce qu'ils commentent javadoc Richard Grin page 2 être placés juste avant ce qu ils commentent Format des commentaires Format des commentaires Les commentaires peuvent contenir p n du texte simple n des tags HTML de mise en forme de texte n des tags HTML de mise en forme de texte (italique, caractère gras, caractères à espacement fixe,…) ; un tag bien utile est p , ) ; g <code> (et </code>) pour inclure du code dans les commentaires n des tags spéciaux à javadoc, qui commencent par le caractère @ : @author, @version, @param,… javadoc Richard Grin page 3 Format des commentaires Format des commentaires Il est possible de passer à la ligne pour couper p p g p p les lignes trop longues ; javadoc ignore les « * » placés en début de ligne javadoc Richard Grin page 4 Caractères spéciaux Caractères spéciaux L tè lié à HTML < Les caractères liés à HTML comme « < » ou « > » sont interprétés spécialement par javadoc « < » doit être écrit « < » dans la javadoc Depuis le JDK 5.0 le tag @literal permet d’insérer plus facilement les caractères spéciaux ; par exemple {@literal A<B>C} sera affiché « A<B>C » par la javadoc {@code A<B>C} fait la même chose en ajoutant {@ } j la police de caractères du tag HTML <code> javadoc Richard Grin page 5 Insérer du code Insérer du code Si l d à i é f it l i li il f t tili Si le code à insérer fait plusieurs ligne il faut utiliser à la fois {@code et la balise HTML <pre> : < >{@ d <pre>{@code ... ... }</pre> javadoc Richard Grin page 6 Insérer une référence Insérer une référence Les tags @ et @li k permettent d’insérer une Les tags @see et @link permettent d’insérer une référence vers une autre partie de la d t ti ê t documentation ou même vers une autre documentation quelconque j é d l i S @see ajoute une entrée dans la section « See also » de la documentation @link insère un lien vers une autre partie de la javadoc j Plusieurs formats peuvent être utilisés pour indiquer ces références javadoc Richard Grin page 7 indiquer ces références Formats pour les références (1) Formats pour les références (1) h î d tè l l h î chaîne de caractères quelconque : la chaîne sera affichée telle quelle dans la javadoc E l Exemple : @see "The Java Programming Language" <a href="URL#ancre">label</a> : lien vers une adresse Web (adresse absolue ou relative) Exemple : @see <a href="spec.html#section">Java / Spec</a> javadoc Richard Grin page 8 Formats pour les références (2) Formats pour les références (2) k Cl # b l b l li package.Classe#membre label : lien vers un autre endroit de la javadoc (ou vers une autre javadoc si l’option li k est utilisée au javadoc si l option -link est utilisée au lancement de la commande javadoc n Le texte du lien sera « label » n Remarquez le # à la place d'un « . » entre le q p nom de la classe et le nom de la méthode javadoc Richard Grin page 9 Formats pour package Classe#membre Formats pour package.Classe#membre L b t êt t t Le membre peut être un constructeur, une méthode ou une variable d’instance On peut aussi désigner une classe par package.Classe, ou une classe interne par package.Classe.ClasseInterne (ne jamais omettre la classe englobante, même si le commentaire est dans la classe englobante) On peut aussi désigner un paquetage : p g p q g @see fr.unice.truc javadoc Richard Grin page 10 Formats pour package Classe#membre Formats pour package.Classe#membre Si l l ti t t d l l Si la classe appartient au paquetage de la classe documentée ou si la classe est importée, on peut tt l d t omettre le nom du paquetage : @see Classe Si l b ti t à l l i t Si le membre appartient à la classe qui est documentée, on peut omettre package.Classe : Utilise la méthode {@link Utilisez la méthode {@link #getComponentAt(int, int) getComponentAt}. Si l éth d ’ t h é l d l Si la méthode n’est pas surchargée, le nom de la méthode suffit ; sinon il faut indiquer sa signature javadoc Richard Grin page 11 Section « see also » Section « see also » @see crée une entrée dans la section « see also » de @see crée une entrée dans la section « see also » de la documentation Exemples : Exemples : n @see java.lang.Integer#parseInt label n @see <a href="…">label</a> (si le 1er caractère est "<", c'est un lien HTML) n @see "texte quelconque" javadoc Richard Grin page 12 Exemple de @see Exemple de @see @ "Th J P i L " @see "The Java Programming Language" @see <a href="spec.html#section">Java Spec</a> Pour désigner des méthodes de la classe ou d’une autre classe : Pour les méthodes n @see equals n @see String#equals(Object) equals Pour les méthodes surchargées n @see String#equals(Object) equals L l b l i Le label qui sera affiché Les classes sont cherchées dans le classpath javadoc Richard Grin page 13 Liens entre commentaires Liens entre commentaires {@link nom-classe#membre label} {@link nom classe#membre label} permet de placer un lien n'importe où dans la documentation (ne pas oublier les accolades) documentation (ne pas oublier les accolades) Exemple : Utilise la méthode {@link #getComponentAt(int int) Utilise la méthode {@link #getComponentAt(int, int) getComponentAt}. @li k l i t id ti à @li k i l @linkplain a une syntaxe identique à @link mais le label est affiché dans la police de caractères du texte di i t d l li d d ordinaire et pas dans la police du code javadoc Richard Grin page 14 Commentaires @since Commentaires @since @ i t d'i di i d i @since permet d'indiquer une version depuis laquelle ce qui est commenté a été introduit Exemple : @since JDK1.1 javadoc Richard Grin page 15 Commentaires de classe et d'interface Commentaires de classe et d interface @param <E> description de ce que représente le èt d t E (d i l JDK 5 0) paramètre de type <E> (depuis le JDK 5.0) @author nom indique l'auteur (plusieurs fois si plusieurs auteurs) @author texte @ indique le ou les auteurs en utilisant le texte @version texte @version texte précise la version Ces 2 tags ne sont utilisés dans la documentation Ces 2 tags ne sont utilisés dans la documentation que si on donne les options -author et -version de la commande javadoc javadoc Richard Grin page 16 commande javadoc Commentaires de méthodes Tous les tags de même type doivent se suivre Les descriptions peuvent s'étaler sur plusieurs lignes Les descriptions peuvent s étaler sur plusieurs lignes @param paramètre description documente un paramètre de la méthode documente un paramètre de la méthode @param <T> description documente un paramètre de type <T> de la documente un paramètre de type <T> de la méthode (ne pas omettre les < et >) @return description @return description documente ce que retourne la méthode @throws classe exception description @throws classe_exception description documente une exception (on peut aussi utiliser @exception) javadoc Richard Grin page 17 @exception) Résumé de commentaire Résumé de commentaire La première phrase du commentaire d’un membre p p d’une classe constitue le résumé du commentaire Ce résumé est affiché dans la section « résumé » Ce résumé est affiché dans la section « résumé » Le reste peut être vu en suivant le lien de la section résumé résumé La « première phrase » se termine n par un point suivant d’un espace ou d’une fin de ligne n ou par un tag javadoc comme @param ou @return javadoc Richard Grin page 18 Exemple de documentation de méthode Exemple de documentation de méthode /** * R t th h t t th ifi d i d A i d * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * * @param index the index of uploads/S4/ javadoc-1.pdf