INFORMATIQUE

Génération automatique de la documentation

Dans le cycle de vie normal d'un développement d'application, il n'y a pas que des phases de programmation. En effet, professionnellement parlant, il doit y avoir une phase de documentation du code produit. Cette phase fut très souvent bâclée, ce qui peut poser des problèmes dans une équipe de développement. Aujourd'hui il est conseillé de documenter le code durant la phase de conception, et non plus après.

En Java, ce conseil est d'autant plus intéressant de par le fait que le JDK propose un petit outil : javadoc. Cet outil sait analyser votre code source Java et en extraire des informations pour générer une documentation, assez riche et conviviale, au format HTML. Outre les informations purement liées au code Java, cet outil sait aussi récupérer des commentaires que vous vous devez d'adjoindre à votre code.

Cette pratique, d'ajouter des commentaires de documentation au code source, à un double avantage : vous pouvez compléter la documentation générée par javadoc et de plus vous donnez une double formulation de la fonctionnalité ou de l'utilité qu'a l'entité (attribut, classe, méthode) commentée. En effet vous, avez ainsi une formulation informelle (votre commentaire) ainsi qu'une formulation formelle (votre code). Après avoir terminé de coder chaque méthode, relisez bien tout pour voir si votre formulation formelle (votre code) ne serait pas en contradiction avec votre formulation informelle. Ca à peut être l'air inutile, mais si l'on s'impose cette façon de travailler, on peut parfois déceler des erreurs (des bugs) avant même de commencer à tester votre travail.

Afin de mieux comprendre les choses, nous allons commencer par tester, dans un cas simple, les fonctionnalités basiques de javadoc. Puis ensuite nous étudierons point par point, certains aspects complémentaires de javadoc. Enfin nous conclurons sur ce petit utilitaire.

L'outil javadoc.

Cet outil est donc fournit par défaut avec le JDK. Il permet de générer des fichiers de documentations à partir de votre code Java. Son utilisation est très simple. Il vous demande de lui spécifier un ensemble de fichiers Java à documenter. A partir de là le reste se fait tout seul, pourvu que vous ayez semez un peu d'information dans les fichiers de code. Un certain nombre de fichiers sont générés et permettent la navigation parmi toutes les classes documentées. Le fichier de départ se nomme alors index.html.

Réalisation d'une documentation simple

Pour mettre en oeuvre un exemple simple, nous allons réutiliser le code des classes Shape, Circle et Square, étudiées dans les chapitres précédents. Ces classes, je vous le rappelle, permettent de gérer des figures géométriques. Cliquez sur les liens pour obtenir le code Java ainsi que les commentaires de chacune des classes. L'exemple qui suit montre comment générer la documentation en utilisant javadoc.

Le point d'entrée de cette documentation est le fichier index.html (en suivant ce lien, vous pouvez consulter la documentation générée). Comme vous l'avez peut-être déjà remarqué, cette documentation est structurée de la même manière que la documentation du JDK : c'est logique, car elle a, elle aussi, été générée via l'outil javadoc. Mais que contient cette documentation ?

En fait, elle contient tout ce qui est nécessaire aux utilisateurs de vos classes. Normalement, vos classes font partie d'un package. N'oubliez pas qu'en dehors d'un package, seuls les champs public sont accessibles. En conséquence, javadoc ne présentera que les champs (méthodes ou attributs) publics de vos classes. N'oubliez donc pas de correctement positionner vos attributs de visibilités (public, private, ...).

De plus, parmi les champs publics d'une classe, on peut discerner plusieurs catégories : les attributs publics, les méthodes et les constructeurs. javadoc vous présente ces champs catégorie par catégorie. Pour encore plus faciliter l'utilisation de cette documentation, chaque documentation de classe propose d'abord un résumé de son contenu puis des informations plus détaillées.

Utilisation des commentaires javadoc

Comme nous l'avons déjà dit, javadoc ne tire pas toutes ses informations qu'uniquement du code Java. Vous pouvez aussi semer des commentaires qui pourront être pris en charge par l'outil. Or, les commentaires peuvent aussi servir au programmeur sans que ce dernier souhaite forcément qu'ils apparaissent au niveau de l'aide. Pour régler le problème, les commentaires javadoc se différencient des commentaires traditionnels. Le tableau suivant montre les types de commentaires supportés : vous conviendrez que pour ce qui est du compilateur Java, il ne voit que deux types de commentaires (les commentaires javadoc étant dérivés des commentaires à la C).

Les commentaires javadoc peuvent contenir des sections spéciales permettant d'adjoindre des informations supplémentaires sur les paramètres des méthodes, les valeurs de retour, les exceptions, ... Mais nous reviendrons sur ces points, un à un, ultérieurement dans ce chapitre.

Profiter du format HTML

Une autre caractéristique de javadoc est qu'il génère du code HTML. Ce point est très intéressant. En effet, dans le texte des commentaires javadoc, vous pouvez y insérer des tags HTML. Ainsi, une fois l'aide présentée dans le navigateur, les tags HTML sont traités. Vous pouvez donc inclure des images, les liens, des tableaux, ... Le petit exemple suivant permet de mettre l'accent sur certains points en les mettant en gras (tag <B> en HTML).

Quelques instructions javadoc

Nous avons déjà dit qu'il était possible de stocker des sections spéciales dans les commentaires javadoc. Cela se fait en utilisant certaines instructions commençant toute par le caractère @. Nous allons donc présenter quelques-unes des instructions javadoc les plus utiles. Celles-ci vous permettrons de documenter vos classes, vos méthodes, leurs paramètres, leur type de retour, ...

Documentation de la classe

Javadoc vous permet de définir plusieurs informations relatives à une classe. L'instruction @see vous permet de faire des références à d'autres classes. L'instruction @since permet de dire à partir de quelle version de votre librairie la classe à été définie. On peut aussi donner le numéro de version courante et l'auteur de la classe via les instructions @version et @author. Dans ce dernier cas, il vous rajouter des options lors de l'appel de la commande javadoc (javadoc -author -version files). Voici en petit exemple pour la classe Shape.

Documentation des méthodes

Pour la définition de vos méthodes, vous pouvez aussi être généreux en informations. Vous pouvez toujours indiquer quelle est la version de votre librairie à partir de laquelle la méthode est supportée, via l'instruction @since. Autres petites choses intéressantes : vous pouvez documenter chacun des paramètres d'appels de la méthode via l'instruction @param, ainsi que la valeur de retour de cette dernière via l'instruction @return.

Vous pouvez de plus réaliser des liens hypertextes via l'instruction @see. Cette dernière permet de lier soit une classe, soit une méthode d'une classe donnée. La syntaxe de cette instruction est simple : elle prend un paramètre qui correspond à l'élément lié. Cet élément est constitué du nom de la classe puis éventuellement de caractère # suivit du nom d'une méthode. Comme le langage Java supporte la surcharge de méthode, vous pouvez de plus donner la signature de la méthode à lier, histoire de lever toute ambiguïté.

Deux autres petites choses sont à connaître. Tout comme dans le JDK, vous pouvez documenter des méthodes dépréciées et les exceptions déclenchées. Pour documenter une méthode dépréciée, il vous faut utiliser l'instruction @deprecated. Vous pouvez bien entendu dire pourquoi vous la dépréciez. Pour documenter une exception, il vous faut utiliser l'instruction @throws. Elle doit, en premier lieu indiquer quelle est l'exception qui est documentée, puis ensuite doit suivre votre commentaire.

Conclusion

Pour conclure ce chapitre, on peut dire que vous avez là un outil formidable. En effet, pour peu que vous commentiez vos programmes au fur et à mesure de leur élaboration, vous pouvez générer une documentation, d'une qualité non négligeable, à moindre frais. Il est vrai que certains autres outils en font de même, et ceux directement durant la phase de conception du logiciel (Rational Rose en est certainement l'exemple le plus connu). Dans ce cas, vous pouvez vous demander lequel de ces produits est le plus adapté ? C'est à vous de trancher. Mais ne perdez pas de vu que l'aspect hypertexte de la documentation générée par javadoc n'est pas négligeable.