Présentation de la Javadoc

Introduction du cours

Ce tuto présente l'outil Javadoc de Sun, qui permet de générer les documentations d'un code Java.

Ca sert à quoi de commenter son code ? Je suis le seul à le lire, non ?
C'est quoi la Javadoc ? Et les tags ? @param, @since, ça sert à quelque chose ?
Et je fais comment pour en générer, moi, de la Javadoc ?

Si vous vous êtes déjà posé une de ces questions, alors ce tuto devrait pouvoir vous intéresser. Nous allons essayer de répondre ensemble à ces interrogations. Et vous vous rendrez compte qu'une fois que vous aurez commencé à utiliser la Javadoc, cela deviendra une étape incontournable dans la création et la maintenance de vos programmes en Java.

Si vous commencez tout juste à apprendre le Java, ce tuto peut quand même vous intéresser. En effet, vous pourrez dès maintenant prendre de bonnes habitudes pour commenter votre code :)

Introduction

Pourquoi commenter son code ?

Il y a deux bonnes raisons pour commenter correctement son code. Tout d'abord, cela permet de mieux comprendre ce que l'on a écrit. Mais surtout, cela facilitera le travail de ceux qui voudraient comprendre, utiliser, voire maintenir votre travail. Les principaux arguments en faveur d'une bonne documentation sont ici présentés selon l'utilisation de votre code.

Pour une utilisation personnelle

• Vous comprendrez mieux ce que vous avez écrit.

• Vous pourrez revenir sur votre code sans avoir à vous replonger dedans.

• Vous pouvez anticiper le codage d'une classe en rédigeant la doc.

Pour une utilisation scolaire

• Les mêmes arguments qu'au dessus plus...

• Beaucoup de profs ne lisent pas en détail les sources.

• C'est toujours des points en plus de gagnés ;)

• C'est plus facile quand on travaille à plusieurs.

Pour une utilisation professionnelle

• Les même arguments qu'au dessus plus...

• Votre code sera sans doute utilisé par d'autres.

• Il sera plus facile de communiquer sur votre travail.

• C'est toujours mieux vu de fournir un code avec une documentation.

J'espère que vous avez bien compris l'intérêt de documenter son code. Mais pour bien comprendre l'objectif de la Javadoc, il faut suivre le conseil suivant à la lettre.

Ne tentez pas de le faire tout seul...

Écrire une documentation complète, facilement utilisable, et surtout qui puisse être maintenue sans effort, c'est impossible à faire "à la main".

Le problème des commentaires internes

Si comme beaucoup de gens vous mettez des commentaires dans votre code, c'est un bon début. Mais si quelqu'un veut avoir une vue globale de votre code, il doit quand même le lire intégralement. Pire encore, si une personne lit dans votre code que vous utilisez une fonction, il est impossible pour lui d'en savoir plus sur cette fonction, sans avoir à chercher sur google par exemple... Imaginez le temps perdu ! :waw:

Le problème de la maintenance

Que ce soit dans le cas de commentaires inclus dans le code, ou (pire) dans le cas d'une documentation fournie à côté (un document OpenOffice, par exemple), comment ferez-vous pour maintenir votre code ? Il suffit que vous vouliez changer le nom d'une classe, d'une fonction, ou même déplacer une classe dans un autre package. Et c'est le drame. Vous devrez éditer chaque page de la documentation concernée par ces changements...

Vous avez bien compris l'intérêt de documenter son code. Mieux encore, vous vous êtes rendu compte que vous ne pourrez pas la faire entièrement à la main, sans quoi la maintenance pourrait ressembler à un vrai cauchemar. Vous êtes donc tout à fait prêts à lire la suite !

Retourner au sommaire de ce tuto.

L'outil JavadocJavadoc, c'est quoi ?

Javadoc, c'est avant tout un outil, développé par Sun Microsystems (la société qui a créé le langage Java). Mais par analogie, c'est aussi la documentation générée par cet outil.

Note : dans la suite de ce tuto, je parlerai de "Javadoc" pour parler de la documentation produite, et de "l'outil Javadoc" pour parler de l'outil en tant que tel.

Cet outil permet, en inspectant le code Java des classes, de produire une documentation très complète de votre code web.

Comment obtenir l'outil JavaDoc ?

L'outil Javadoc est inclus dans tous les JDK (ou SDK) de Java. Pour télécharger la dernière version du JDK, rendez-vous sur la page de téléchargement de Sun .

Si vous avez déjà un JDK installé sur votre machine, vous trouverez l'outil Javadoc dans le répertoire bin du dossier.

Javadoc génère quoi exactement ?

L'outil génère des pages HTML contenant au minimum la liste des classes, la liste des méthodes et la liste des variables. Nous verrons ensuite qu'il est possible d'ajouter tout un tas d'informations, de commentaires, afin de générer une véritable documentation, exhaustive et facilement lisible.

L'avantage du format HTML utilisé dans la documentation produite tient dans la présence de liens hypertextes. Il devient très facile de naviguer dans la documentation, au fil de la lecture.

Et puis comme ça, vous ne serez pas perdus pour mettre en forme vos commentaires ;)

Quelques exemples

Voici deux exemples de documentation générée par l'outil Javadoc. La première image correspond à une doc générée à partir d'un code sans commentaire. La seconde correspond à un code commenté correctement.

Si vous cliquez sur les images, vous arriverez sur les pages Javadoc correspondantes. ^^

On se rend dès lors très bien compte de l'intérêt de l'outil Javadoc. La documentation produite est claire, simple, et complète. Mais on voit aussi qu'un code bien commenté génère une Javadoc plus lisible, contenant plus d'informations.

En effet, l'outil Javadoc utilise des tags mis dans le code pour compléter la documentation générée. Voyons ensemble ces différents tags.

Retourner au sommaire de ce tuto.

Les tags JavaDoc

Il est possible d'ajouter une grande quantité d'informations à un code, en utilisant les commentaires. Mais ils ne sont pas pris en compte par l'outil Javadoc. Mais Sun a bien fait les choses, il existe des commentaires spécialement faits pour la Javadoc, et mieux encore, des tags précis qui permettent de détailler des informations sur chaque classe, chaque méthode, etc.

Les commentaires Javadoc

Pour rappel, il existe trois types de commentaires en Java. Les commentaires en lignes, les commentaires sur plusieurs lignes, et les commentaires Javadoc.

Voici un exemple présentant ces trois types de commentaire.

/** * Ceci est un commentaire Javadoc. * Il commence par un slash suivis de deux étoiles. * Chaque ligne doit ensuite commencer par une étoile. * Enfin, il fini par une étoile suivie d'un slash. */ protected Vector<Zero> getVectorAmis(){ // Ceci est un commentaire sur une ligne Vector<Zero> vector = new Vector<Zero>(); /* Ceci est un commentaire sur plusieurs lignes */ for (Zero z : listeAmis){ vector.add(z); } return vector; }

Donc toutes les informations que nous mettrons se trouverons dans ce commentaire Javadoc. Il doit se situer sur la ligne immédiatement avant le nom de la classe, de la méthode, ou de la variable.

Les tags Javadoc

Les tags Javadoc sont au nombre de neuf :

• @param

• @return

• @throws

• @author

• @version

• @see

• @since

• @serial

• @deprecated

Je ne détaillerai pas l'utilité (contestable) du tag @serial. Pour plus d'informations, référez-vous au guide de style de SUN (voir en bas de ce tuto).
De plus, des conseils de mise en page de ces tags sont expliqués dans la partie suivante de ce tuto. ;)

@param : les paramètres de la méthode

Le tag @param sert à renseigner le ou les paramètres de la méthode. Derrière le tag, il faut renseigner le nom du paramètre (son type sera inclus automatiquement dans la Javadoc).

/** * Met à jour le niveau du membre. * * @param level * Le nouveau level du membre. */ protected void setLevel(SDZLevel level) { this.level = level; } @return : l'objet retourné par la méthode

Le tag @return sert à renseigner l'objet retourné par la méthode.

/** * Retourne le level du zéro. * * @return Une instance de SDZLevel, qui correspond à niveau du membre sur SDZ. */ public SDZLevel getLevel() { return level; } @throws : les exceptions propagées

Le tag @throws indique la présence d'une exception qui sera propagée si elle se lève. Il faut bien indiquer le type de l'exception, et la raison de l'exception.

/** * Retourne l'adresse du profil du Zero. * * @return L'URL du profil du Zero, générée à partir de l'id du Zero. * * @throws MalformedURLException Si jamais l'url est mal formée. */ public URL getURLProfil() throws MalformedURLException{ URL url = new URL("http://www.siteduzero.com/membres-294-"+id+".html"); return url; } @author et @version : l'auteur et le numéro de version de la classe

Le tag @author renseigne le nom de l'auteur de la classe. Le tag @version indique le numéro de version de la classe. Ce dernier tag est utilisé ensuite par le tag @since (voir plus bas).
Important : ces tags ne peuvent être utilisés que pour une classe ou une interface. Jamais pour une méthode.

package fr.dworkin.sdz.javadoc; /** * Zero est la classe représentant un membre du Site du Zéro. * * @author dworkin * @version 3.0 */ public class Zero { [...] } @see : réfère à une autre méthode, classe, etc.

Le tag @see permet de faire une référence à une autre méthode, classe, etc. Concrètement, cela se symbolisera par un lien hypertexte dans la Javadoc. C'est donc un des tags les plus importants.

/** * Le "level" du Zéro. Ce "level" peut être modifié. * * @see SDZLevel */ private SDZLevel level; @since : depuis quelle version

Le tag @since permet de dater la présence d'une méthode, d'un paramètre. Derrière ce tag, il faut noter un numéro de version de la classe.

/** * Met à jour le pseudo du membre. * * @since 3.0 */ public void setPseudo(String pseudo) { this.pseudo = pseudo; } @deprecated : indique qu'une méthode est dépréciée

Le tag @deprecated doit décrire la version depuis laquelle cette méthode / classe est dépréciée. Mais aussi ce qu'il faut utiliser à la place.

/** * Retourne la liste des amis du zéro. * * @deprecated Depuis Java 1.4, remplacé par getListeAmis() */ protected Vector<Zero> getVectorAmis(){ Vector<Zero> vector = new Vector<Zero>(); for (Zero z : listeAmis){ vector.add(z); } return vector; }

Maintenant que vous connaissez tous les tags, voyons comment les mettre en forme et les enrichir. ;)

Retourner au sommaire de ce tuto.

Les conventions d'écriture

Il existe des conventions pour la mise en forme de la Javadoc. Elles concernent les tags d'une part, et les commentaires d'autre part. Mais il y a aussi le HTML. Vous n'avez pas oublié, tout de même ? :p

Les conventions générales

Il existe une grande quantité de conseils pour la mise en page des commentaires Javadoc. Voici les principaux :

• La première phrase Javadoc de la classe doit être une courte description de la classe.

• Ce conseil vaut aussi pour les méthodes, variables, etc.

• Faites des phrases relativement courtes.

• Utilisez la troisième personne pour commenter une méthode.

• Détaillez le fonctionnement (algo) des méthodes si besoin.

• Utiliser "ce" plutôt que "le".

• Les tags @param et @return doivent être systématiquement indiqués (sauf méthodes sans paramètres ou méthodes void).

Le HTML ?!

Eh oui ! Vous ne vous souvenez déjà plus ? Je vous ai dit au début ce tuto que l'on pouvait utiliser le HTML dans les commentaires Javadoc. Mais il faut les utiliser seulement pour des choses simples. N'essayez pas d'en faire trop, ce n'est pas le but. Les balises les plus utilisées sont <b>, <i>, <ul> et <p>. Regardez dans l'exemple complet qui suit comment je les utilise.
Mais je le répète, n'en faites pas trop ;)
D'ailleurs, vous remarquerez que la documentation est mise en forme grâce à une feuille de style CSS. Si vous voulez modifier les couleurs, vous savez comment faire. :p

Retourner au sommaire de ce tuto.

Générer la Javadoc avec Eclipse

Pourquoi je vous parle d'Eclipse ? Pour deux raisons. D'une part, c'est à mon humble avis le meilleur outil de développement Java. Et je vous assure que je ne suis pas le seul à penser ça. De plus vous serez probablement...