Documentation d’un projet avec Javadoc

Qu’est-ce que JavaDoc ?

JavaDoc est un projet développé par Sun, devenu un standard Java, créé dans le but de fournir de la documentation en HTML depuis les commentaires dans le code La documentation s’écrit avec de commentaires simples et permet d’utiliser des tags spécifiques et des balises html classique. Les tags JavaDoc sont reconnaissable par l’arobase au début du tag, par exemple “@author”

Quoi documenter ?

La documentation peut être de plusieurs types :

  • L’expression de besoin (à renseigner ou traduire la version anglaise).
  • Architecture / Conception – Vue d’ensemble sur le logiciel
  • Technique – Documentation du code
  • Utilisateur – Manuels pour le end-user ou l’administrateur
  • Marketing – Instructions sur le produit

Nous sommes donc avec JavaDoc dans la partie Documentation Technique.

Les bénéfices ?

  • Transparence
  • Compréhensibilité du code pour les développeurs
  • Création de teste faciliter
  • Troubleshooting facilité
  • Facilite le jaugement de l’état d’avancement du projet

Documentation d’une fonction simple

/** Voici la description de la fonction <b>FaireQuelqueChose</b>
* <i>Cette Fonction permet de multiplier par 10 un nombre</i>
* @author Manu404
* @param x  Nombre a multiplier par <i>10</10>
*/

Les 2 premières lignes seront affiché dans le summary de la fonction

La ligne 3 permet de définir l’auteur de la fonction via le tag author
La ligne suivante documente l’argument de la méthode via le tag param suivi du nom de l’argument et d’une description

Pour générer la documentation sous Netbeans il suffit de faire un clic droit sur le nom du projet et cliquer sur “Generate Javadoc”

Les tags JavaDoc

@author
Le nom du développeur
syntaxe : @author <nom_du_developpeur>

@deprecated
Marque la méthode comme dépréciée. Cela signifie que la méthode sera bientôt supprimé et ne doit donc plus être utilisé
Ce tag est compilé, ce qui signifie que un warning  a la compilation sera généré sur un méthode documenté comme depracated est utilisé.
La syntaxe est la même que @author

@exception
Documente une exception lancée par une méthode
Il possède un synonyme, @throws
Syntaxe : @exception <nom_exception> <description_exception>

@param
Définit un paramètre de méthode. Requis pour chaque paramètre.
Syntaxe : @param <nom_du_paramètre> <description>

@return
Documente la valeur de retour.
Syntaxe : @return <description>

@see
Documente une association à une autre méthode ou classe, en bref, un lien vers une autre doc.
Syntaxe : @see <quoi ?>
Par exemple :
@see “Du texte”
@see package.class
Dans ce cas, il y aura deux liens dans le See Also de la documentation

@since
Précise à quelle version de la SDK/JDK une méthode a été ajoutée à la classe.
Syntaxe : @since <texte>

@throws
Documente une exception lancée par une méthode. Un synonyme pour @exception disponible depuis Javadoc 1.2.

@version
Donne la version d’une classe ou d’une méthode.
Syntaxe : @version <texte>

@ code
Permet d’afficher du code sans l’interpréter par la browser
Syntaxe : <code></code>

@ literal
Permet d’afficher du code sans l’interpréter par la browser
Syntaxe : @literal <texte>

Voici donc la même fonction mais plus documenté.
Le code :

Et voici le résultat dans la JavaDoc

Conclusion

Documentez au maximum vos projets, il y a des outils très facile d’utilisation qui existent et les quelques minutes passé a documenté une classe vous ferons gagner un temp précieux dans le cas ou par exemple un autre developpeur se joint a vous et travail sur le projet, il aura une vision assez détaillé de ou en est le projet et que fait çi ou ça.

2 thoughts on “Documentation d’un projet avec Javadoc

    1. manu404 Post author

      Il y a deux principales méthodes pour la compilation si elle n’est pas prise en charge dans l’IDE :
      La méthode “Solaris” : http://download.oracle.com/javase/1.4.2/docs/tooldocs/solaris/javadoc.html#examples
      La méthode “Windows” : http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#examples

      Si ces deux méthodes ne fonctionnent pas dans votre environnement vous pouvez aussi vous référer a la FAQ de JavaDoc qui est assez complète : http://java.sun.com/j2se/javadoc/faq/index.html

      Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s