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

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

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.
  */

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 {
  ...
 }

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 );

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;

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
  */

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 {
   ...
  }

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 );

Doxygen : syntaxe des liens

@see package	Lien vers un package
@see classname	Lien vers classname dans le package courant
@see package.classname	Lien vers classname dans un autre package
@see #method	Lien vers method dans la classe courante
@see classname#method	Lien vers method dans une autre classe
@see #method(type)	Lien vers method avec l'argument type

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
  *
  * @section intro Introduction
  *             ...
  * @section install Procédure d'installation ...
  *   @subsection step_1 Première étape ...
  *   @subsection step_2 Deuxième étape ...
  *             ...
  * Le fichier <a href="../../ChangeLog"> ChangeLog</a>
  */

Utilisation avec CMT

Dans <package>/<version>/cmt :
```
 $> cmt make doc
      
```
puis :
```
 $> open ../doc/html/index.html
      
```

... c'est tout ! ;-)

Questions ?