Doxygen : Comment documenter un projet de développement informatique ?

Générer une documentation automatiquement pour plusieurs langages de programmation.

14 juin 2012

Doxygen est un générateur de documentation libre. Il parcourt les codes sources et génère automatiquement de la documentation dans différents formats (HTML, RTF, Latex ...). Doxygen a l'avantage, par rapport à ses concurrents, d'être multi-langages de programmation. La première fois que j'ai utilisé Doxygen c'était pour documenter un projet en C++, dans ce tutoriel nous utiliserons PHP. Bien sûr Doxygen n'est pas devin, il faudra l'aider pour qu'il comprenne nos commentaires en utilisant une syntaxe particulière.

Installer Doxygen et préparer une documentation basique

Evidemment, avant d'utiliser Doxygen, il faut l'installer. Les manipulations ont été effectuées sous Debian Squeeze.

Installer Doxygen sous Debian Squeeze

aptitude install doxygen
	

C'est tout !

Doxygen offre la possibilité de personnaliser la documentation pour chaque projet. Pour cela il faut créer un fichier nommé Doxyfile à la racine de votre projet. Supposons que mon projet se nomme Informatix et qu'il se trouve dans /racine_web/informatix.

Générer un Doxyfile

cd /racine_web/informatix
doxygen -g
	

Nous pouvons maintenant personnaliser notre documentation en éditant le Doxyfile.

Voici certaines des options intéressantes :

  • PROJECT_NAME = Informatix : Le nom du projet.
  • RECURSIVE = YES : Cette option permet de parcourir toute l'arborescence de votre projet.
  • LATEX = NO: C'est comme vous voulez, personnellement je n'utilise que le HTML.
  • PRIVATE = YES, STATIC = YES : Fait apparaître tous les attributs et toutes les méthodes dans la documentation.
  • INPUT = /racine_web/informatix : Indique l'emplacement à partir duquel sera lancé le scan.
  • OUTPUT_DIRECTORY = /dossier/documentation : Indique l'emplacement des fichiers de sortie. Attention à ne pas rendre votre documentation visible de tout le monde !
  • OUTPUT_LANGUAGE = French : Eh oui ! Doxygen n'est pas utilisable qu'en Anglais.

Générer la documentation

Et voici la partie que vous attendez tous. Une simple commande à lancer, quelques secondes d'attente, un paquet de warnings qui s'affichent et c'est fini.

Générer de la documentation avec Doxygen

cd /racine_web/informatix
doxygen Doxyfile
	

Vous pourrez trouver à la destination OUTPUT_DIRECTORY/html toute votre documentation générée .

Comme vous pouvez le voir, Doxygen a listé toutes vos classes, vos méthodes, vos attributs etc... Mais aucun n'est commenté pour le moment.

Comme dit précédemment, Doxygen se base sur des commentaires avec une syntaxe spéciale pour générer la doc. Il existe plusieurs syntaxes, je vous en propose une qui n'est, je pense, ni mieux ni moins bien que les autres.

DoxygenExemple.php - La classe de test

/**
* \author NlC0 du site www.informatix.fr
* \date 14/06/2012
* \brief Un exemple de classe qui ne sert à rien.
*/
class DoxygenExemple
{
	/**
	* \brief Méthode qui ne sert à rien !
	* \param exemple Un argument qui ne sert à rien.
	* \return Retourne la string : "Ca marche !".
	*/
	public function test($exemple)
	{
		return ("Ca marche !");
	}
}
	

Re-générez la documentation et bingo ! Vous devriez voir apparaître vos commentaires .

Pour comprendre les annotations que j'ai utilisées et pour en trouver d'autres, je vous laisse regarder la documentation officielle de Doxygen : http://www.stack.nl/~dimitri/doxygen/

Bonne chance.


"La qualité d'un logiciel se mesure au poids de sa documentation." Anonyme

Par
Créateur et administrateur.

Dans la même catégorie

Rechercher un type de fichier sur Google

Commentaire(s)