Comment faire une jolie documentation (avec Doxygen)

Portrait de trax
Soumis par trax le lun, 12/05/2008 - 17:50

Ce tutoriel n'a rien de transcendant, mais permettra juste à quelque uns de découvrir cet outil, et vous aider à faire le premier pas.

Introduction

Coder pour soit ça peut être sympa, mais cette pratique atteint assez rapidement ses limites. Mais ouvrir son code demande un minimum de documentation. Alors voici une solution, pas magique, mais presque : Doxygen.

Quelques caractéristiques intéressantes

Petits exemples de documentation doxygen :

Ne soyons pas sectaire il n'y a pas que doxygen qui fasse ce genre de choses

Doxygen est un logiciel qui va analyser votre code pour créer un documentation. Bien évidement, il ne va pas deviner ce que veux fait la fonction la fonction void plop (gchar *msg) il faut donc lui donner un petit coup de main : utiliser des balises. Pas d'affolement c'est tout ce qu'il y a de plus facile.

Ce qui m'a donné envie d'écrire ce tutoriel c'est d'avoir dû documenter le code de notre projet bidon, il y aurait donc pas mal d'exemples basés dessus. Pour pouvoir directement accès aux fichiers se référer à la page du projet.

Pour la documentation officiel : http://www.stack.nl/~dimitri/doxygen/manual.html

Comment commenter son code ?

Quatre manières de commander son code : 

/** commentaire
 * blabla
 */
/*!
 *
 */
/*!
...
 */
///
/// ...
///

Quelques balises bien utiles

La liste de la documentation officielle se trouve là : http://www.stack.nl/~dimitri/doxygen/commands.html
Nous ne présenterons ici que les balises vitales pour commencer

Documentation du code

\author trax Givneraud Omar
\version 0.3

Vous l'aurez deviné pour l'auteur et la version. A mettre en entête de de vos fichiers.

\file foobar.c
\class Eugeni
\fn void plop(gchar *msg)

Gné ça sert a quoi ? il peut pas comprendre tout seul que c'est le fichier foobar.c ou la fonction plop ?
Si il pourrait mais ça permet de pouvoir déplacer la documentation un peu on l'on veux et surtout définir la nature d'un bloc : documentation d'une fonction, un fichier ou encore une classe. L'argument est bien évidement optionnel

\brief breve description de la fonction ou du fichier

Pour une documentation longue pas de balise particulière, il suffit juste de sa placer dans un bloc de documentation doxygen.

\param nom_du_parametre sa description
\return ce que retourne la fonction

Créer une page de documentation style howto ou tutoriel

Petit exemple toujours sur le projet bidon :
http://clubnix.esiee.fr/~trax/bidon/doc/html/howto_makeplugin.html

code doxygen de la page :
http://clubnix.esiee.fr/~trax/bidon/doc/howtos/howto_plugin.doc

Pour créer une page, créer un fichier séparé de préférence et créer un bloc de documentation doxygen.
Utiliser la balise 

/*!
\page reference_de_la_page Titre de la page
 */

Sections

Pour les sections (titres et sous titres) doxygen utilise une syntaxe proche de celle de LaTex

\section Titre niveau 1
\subsection Titre niveau 2
\subsubsection Titre niveau 3

Inclure du code :

\code 
le code
\endcode

Si doxygen reconnait des éléments de votre projet dans la balise code il créera directement un lien vers vers la documentation en question. Cela peut être très pratique, mais également un inconvénient : vous avez une fonction plop dans votre code, et vous voulez faire un exemple dans votre tutoriel avec une fonction plop qui n'a rien a voir avec celle du projet (ceci est également vrai pour le texte d'une page). Il existe donc la balise verbatim.

\verbatim
plop non reconnu
\endverbatim

Faire une liste

Rien de plus facile !

\li premier element
\li deuxième element

Lancer la moulinette pour obtenir sa doc

Il y a un magnifique fichier de configuration, mais pas question de l'ouvrir à la main pour l'instant : doxywizard est notre ami. Lancer le binaire et suivre les instruction, rien de plus simple. Pour avoir un fichier exemple, comme d'habitude voir dans bidon http://clubnix.esiee.fr/~trax/bidon/doc/Doxyfile2