Cette année, pendant un projet de programmation en C, nous avons fait face à un problème de taille, la documentation. En effet, lors de la mise en commun, nous avons dû travailler de concert, longuement, pour être certain d’utiliser correctement toutes les fonctions réalisées.
Nous avions commenter notre code, mais ce n’était pas suffisant, nous avons alors décidé de réaliser documenter rapidement notre projet et pour ce faire nous avons utilisé Doxygen 1.
Comme nous, avec Doxygen, vous rendrez des codes proprement documentés sans même vous en rendre compte et vous pourrez générer un site pour votre documentation tout aussi simplement.
Nous allons donc voir quels paramètres modifier, et comment organiser au mieux son code pour obtenir une documentation similaire à celle de notre projet.
Comment fonctionne Doxygen
Doxygen se définit comme un générateur de documentation, c’était exactement l’outil dont nous avions besoin, mais il est surtout orienté objet et pouvoir l’utiliser au mieux pour créer votre documentation en C, il existe quelques paramètres à modifier.
La documentation est générée directement depuis votre code source, Doxygen utilise les commentaires et l’architecture de votre code pour générer une documentation complète. En l’utilisant correctement vous pourrez documenter l’intégralité de votre code source.
Pour l’utiliser au mieux, il faut alors penser à bien organiser votre code et à commenter vos headers de la bonne manière.
Installation
Première étape, l’installation, je fais l’hypothèse que vous utilisez Linux ou le portage Ubuntu sur le terminal Windows. Il vous suffit d’installer Doxygen sur votre machine.
$ sudo apt-get install doxygenEt ensuite d’initialiser Doxygen dans le dossier de votre projet.
$ doxygen -g doxygen.confParfait ! Doxygen est prêt à être paramétré. Dans quelques minutes vous pourrez générer votre première documentation!
Paramètrage
Doxygen est un outil complet et dispose donc de nombreux paramètres que vous pouvez modifier pour adapter votre documentation à votre besoin.
Personnaliser Doxygen
Pour rendre le site généré clair et unique, quelques paramètres doivent être modifiés. Déjà le nom et la description du projet, sont les premiers paramètres de la page;
PROJECT_NAME = "My Project"
PROJECT_BRIEF = "My description"Ensuite, vous pouvez pousser la personnalisation au logo, et au dossier dans lequel la documentation générée sera sauvegardée.
PROJECT_LOGO = PATH_TO_LOGO
OUTPUT_DIRECTORY = PATH_TO_WRITE_TOOptimiser pour le C
Les paramètres à modifier pour avoir une documentation agréable en C sont :
OPTIMIZE_OUTPUT_FOR_C = YESVous venez d’activer l’optimisation de génération de la documentation pour le C. Cette option est idéale si votre code source est uniquement écrit en C. Certaines listes et noms sont modifiés (enlevant en partie la notion d’Objet dont aurait besoin une documentation en C++ par exemple).
TYPEDEF_HIDES_STRUCT = YESVous avez aussi utilisé les typedef pour cacher les structures dont elles définissent le type, rendant la documentation plus claire.
Vous pouvez maintenant vous dire que tout est paramétré, vous êtes bien prêts créer la documentation de votre code source C.
Ajouter les graphes d’appel
Doxygen est capable de générer différents types de graphes, par défaut sont activés les paramètres permettant de voir les inclut et incluant de votre code.
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YESVous devriez obtenir au début de la documentation de chacune de vos headers (.h) les graphes d’inclusion. Vous pouvez aussi lui faire générer des graphes plus détaillés, des fonctions utilisant et utilisée. Les graphes d’appels.
Les graphes d’appels permettent de visualiser rapidement comment est utilisée une fonction dans votre code. On peut générer des graphes d’appels et d’appelant de la manière suivante :
CALL_GRAPH = YES
CALLER_GRAPH = YESIl ne vous reste plus qu’à générer votre documentation.
Générer la documentation
Formaliser ses commentaires
Nous n’avons pas encore traité de comment formater la documentation des fonctions et structures. Dans vos fichiers header, il vous suffit de commenter en utilisant ce format qui va suivre.
Il faut d’abord ajouter au début du fichier les informations qui conviennent.
/**
* @file filename.h
* @date dd month yyyy
* @brief description rapide
* @author Johnny Gouvaert
*
* description détaillée
* description détaillée
* description détaillée
*
* @todo
*/Vous pouvez ensuite commenter vos structures, typedef, fonctions en ajoutant des blocs du même type. Vous pouvez utiliser, par exemple, le format qui suit.
/**
* @brief Une structure
*/
typedef struct Structure {
int entier;
float flottant;
} Structure;
/**
* @brief Une fonction
*
* Description du fonctionnement, de l'utilisation...
*
* @code
* Structure result = fonction();
* @endcode
*
* @return information sur ce que la fonction renvoi.
*/
Structure fonction ();Il existe une multitude de formulation différente et de tags différents, avec ceux-ci vous devriez pouvoir expliquer clairement le fonctionnement de l’utilisation de votre code. La documentation Doxygen 2détaille clairement comment commenter son code.
Visualiser votre documentation
La génération de la documentation se fait avec une simple commande, demandant à Doxygen d’utiliser votre fichier de configuration pour générer votre documentation.
$ doxygen doxygen.confAprès un rapide chargement, vous avez maintenant une documentation complète, cohérente, interactive et surtout simple à partager !
Conclusion
Aujourd’hui vous avez appris à paramétrer Doxygen pour générer la documentation de votre code source en C.
Vous avez aussi appris à installer globalement Doxygen sur Linux et même à commenter le code pour que Doxygen puisse générer la documentation.
Une bonne documentation, c’est un bon projet et une bonne compréhension
alors ne sous-estimez pas l’importance de documenter proprement les fonctions de votre code.
References
