Comment faire une jolie documentation (avec Doxygen)

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
- Génération de graphes d'appel de fonction, d'inclusion, ou encore d'héritage (en Orienté Objet) grâce a graphviz (dot)
- Syntaxe très simple
- Formats de sortie multiple
- html http://clubnix.esiee.fr/~trax/bidon/doc/html
- pdf (en passant par LaTex) : http://clubnix.esiee.fr/~trax/bidon/doc/latex/refman.pdf
- man
- xml
- rtf
- langages pris en compte : C++, C, Java, Objective-C, Python, IDL (Corba et Microsoft flavors), Fortran, VHDL, PHP, C#, et D
- Moteur de recherche pour les page web
Petits exemples de documentation doxygen :
- http://clubnix.esiee.fr/~trax/bidon/doc/html : un de nos projets
- http://kdevelop.org/HEAD/doc/api/html/ : documentaiton de Kdevelop
- http://xerces.apache.org/xerces-c/apiDocs/index.html
- http://www.stack.nl/~dimitri/doxygen/projects.html petite liste de projets utilisant doxygen
Ne soyons pas sectaire il n'y a pas que doxygen qui fasse ce genre de choses
- javadoc
- gtk-doc
- http://www.stack.nl/~dimitri/doxygen/links.html petite liste donnée pas doxygen
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