Documenter son code PHP avec doxygen

Je cherchais hier un moyen de générer une belle doc PHP, à partir de mes fichiers sources. Je connaissais quelques outils de la sorte (OcamlDoc, Sphinx pour Python, JavaDoc etc.) mais je n’avais jamais regardé ça en détails.

Du coup, je suis tombé sur Doxygen, qui supporte une très grande variété de langages, est utilisé par beaucoup de scripts (dont des très gros comme Drupal) et était largement suffisant pour mes besoins. Il mange vos sources et génère de belles documentations des pages de doc lisibles, en HTML, LaTeX, CHM et autres.

J’ai pas trouvé de guides ultra rapides pour démarrer (ok, j’ai pas vraiment cherché non plus) donc je liste ici les 3 commandes de base, pour avoir une doc en 5 minutes chrono.

Pour commencer, il faut faire doxygen -g .doxygen dans le répertoire du projet pour générer un fichier de configuration (option -g) nommé .doxygen. Voici quelques paramètres utiles à modifier:

• PROJECT_NAME, mettre le nom de votre projet.
• Je voulais générer uniquement une doc HTML, et tout mettre dans un dossier doc. J’ai donc mis OUTPUT_DIRECTORY à "doc/", puis HTML_OUTPUT à . (pour que la doc HTML aille dans doc/) et enfin GENERATE_LATEX à NO pour ne pas générer de doc en LaTeX.
• Enfin, je voulais traiter tous les fichiers de mon projet, donc j’ai mis l’option RECURSIVE à YES.

Une fois tout ceci fait, il faut que vos commentaires soient au bon format pour que doxygen les lise. Un exemple est disponible ici.

En gros, il faut à chaque fois redoubler les commentaires /** … */ pour que doxygen les parse. Les premières lignes de texte dans chaque cas sont un petit paragraphe descriptif. Il est possible d’ajouter un plus long paragraphe après avoir sauté une ligne. Doxygen utilise ensuite des tags @quelquechose pour noter les paramètres, les valeurs de retours, les copyrights etc.

Important, ne pas oublier de dire à doxygen d’utiliser le fichier courant avec un @file dans le commentaire global du fichier.

Une fois tous vos fichiers taggés correctement, lancer doxygen .doxygen depuis la racine de votre projet pour générer la doc. Vous obtiendrez une belle documentation comme ça (ok, il y a encore du boulot sur celle-ci…).