Doxygen

1. Doxygen

2. Doxygen : qu’est-ce que c’est ? • Système de documentation pour programmes • C++, Java, Objective-C, IDL • PHP, C# • Génère automatiquement : • Html, Xml, Latex, Pdf, PS • man pages • graphe des dépendances, des héritages • Couplage fort entre la documentation et le code

3. Doxygen : comment ? … sans rien faire ;-) • Exemple : • lien DrawQt du menu principal • Génère automatiquement la documentation • en s’appuyant sur un fichier de configuration, • qu’il est capable de générer sous forme de template $> doxygen -g configFile • en analysant le code • en analysant les commentaires placés dans le code, selon un format spécifique

4. Doxygen : 1ère bouffée (1) • Au début de chaque fichier, juste après les instructions d’inclusion : #include <iostream> #include <string> /** @file nomDuFichier.ext * @brief Une brève description du fichier. * * Une description plus complète du fichier. * Probablement sur plusieurs lignes. */

5. Doxygen : 1ère bouffée (2) • Juste avant chaque classe : /** @brief Une brève description de maClasse. * * Une description plus complète de maClasse. * Probablement sur plusieurs lignes. */ class maClass {

6. Doxygen : 1ère bouffée (3) • Juste avant chaque méthode : /** @brief Une brève description de maMethode. * * Une description plus complète de maMethode. * Probablement sur plusieurs lignes. * @param unArgument Une brève description de unArgument. * @return Une brève description de ce que retourne * maMethode. */ std::string maMethode( std::string unArgument );

7. Doxygen : 1ère bouffée (4) • Juste avant chaque variable : /** @brief Une brève description de maVariable. * * Une description plus complète de maVariable. * Probablement sur plusieurs lignes. */ std::string maVariable;

8. Doxygen : en apnée (1) • Au début de chaque fichier, juste après les instructions d’inclusion : #include <iostream> #include <string> /** @file nomDuFichier.ext * @brief Une brève description du fichier. * * Une description plus complète du fichier. * Probablement sur plusieurs lignes. * * <strong>Exemple</strong> * <code>Status maFonction();</code> * * @author Leroi Arthur */

9. Doxygen : en apnée (2) • Juste avant chaque classe : /** @brief Une brève description de maClasse. * * Une description plus complète de maClasse. * Probablement sur plusieurs lignes. * Une liste de caractéristiques : * - un item * -# numéroté 1 * -# numéroté 2 * - un autre item */ class maClass {

10. Doxygen : en apnée (3) • Juste avant chaque méthode : /** @brief Une brève description de maMethode. * * Une description plus complète de maMethode. * Probablement sur plusieurs lignes. * * @param unArgument Une brève description de unArgument. * @return Une brève description de ce que retourne * maMethode. * *@throws monException La raison et la description. * * @see #uneAutreMethode * @see uneAutreClasse#uneAutreMethode */ std::string maMethode( std::string unArgument );

11. Doxygen : syntaxe des liens • @seepackageLien vers unpackage • @seeclassnameLien versclassnamedans le package courant • @seepackage.classnameLien versclassnamedans un autre package • @see#methodLien versmethoddans la classe courante • @seeclassname#methodLien versmethoddans une autre classe • @see#method(type)Lien versmethodavec l’argument type

12. Doxygen : en apnée (4) • Enrichir la page d’introduction : @mainpage • dans un bloc de commentaire • par exemple, dans un fichier mainpage.h • /** @mainpage Le package Test** @sectionintro Introduction* …*@sectioninstall Procédure d’installation …* @subsection step_1 Première étape …* @subsection step_2Deuxième étape …* …* Le fichier <a href=”../../ChangeLog”> ChangeLog</a>*/

13. Utilisation avec CMT • Dans <package>/<version>/cmt : $> cmt make doxygen • puis : $>open ../doc/html/index.html … c’est tout … ;-)