Accueil Nos publications Blog Documenter du code C# avec Doxygen
.NET
01/03/2010 2 min

Documenter du code C# avec Doxygen

Doxygen est un générateur de documentation couramment utilisé en C++ (comme Javadoc en java). Il supporte plusieurs langages : C, C++, Java, Python… Mais aussi C#. Doxygen supporte plusieurs formats de sortie (html, chm, rtf, PDF via latex) et le contenu est très personnalisable. On trouve notamment des options pour ignorer les méthodes non documentées, exposer ou non les méthodes privées, les méthodes statiques…

De son côté, Visual Studio nous permet de faire facilement du XML Doc avec les tags <summary>, <param>, <returns>… Le XML Doc est intéressant à utiliser car la documentation ainsi formatée est accessible via l’intellisense.
Par contre, dès qu’on veut exporter la XML Doc en documentation “papier” (pages html par exemple), là ça devient plus ardu : NDoc s’est arrêté au framework .NET 1.1 faute de développeurs et successeurs, NDoc3 est en beta, SandCastle n’est pas forcément simple d’utilisation (apparemment le Sandcastle help file builder facilite bien la tâche) et semble peu performant sur des projets volumineux. De plus le format msdn-like ne fait pas forcément l’unanimité.

Correspondances entre tags XML et balises Doxygen

C’est là que Doxygen fait d’une pierre deux coups. En effet, Doxygen sait parser les tags de la XML Doc. Ainsi on peut faire du XML Doc pour avoir l’intellisense et utiliser Doxygen pour générer une belle documentation à jour. Voilà la correspondance des tags les plus usuels :

  • <summary> correspond à la description brève (\brief) d’une classe, champ, méthode, namespace…
  • <remarks> correspond à la description détaillée d’une classe, champ, méthode, namespace…
  • <param name=”monParam”> sert à documenter le paramètre d’entrée d’une méthode
  • <returns> permet de documenter la valeur de retour

Voir toutes les correspondances

Pour ce qui est de la pratique, Doxygen parse convenablement les fichiers sources C#. Il a quelques comportements anormaux sur du code dont la syntaxe s’éloigne du C++ (implémentation explicite d’interface par exemple) mais dans l’ensemble la documentation est très correcte.

Pour installer Doxygen

Pour l’utiliser

  • Commentez vos sources
  • Lancez Doxywizard
  • Configurez vos options
  • Run
  • ????
  • PROFIT

Notes

  • Doxygen offre énormément d’options, si vous voulez en savoir plus je vous conseille de faire un tour ici
  • La balise <example> est ignorée par doxygen, il faut donc lui préférer <code>

Sources/Liens

Rédigé par :

benjamin.baumann