03déc. 2012

Sandcastle : Génération de documentation CSharp

La documentation du code source d'une application est un enjeu majeur car la pérénnité d'un projet en dépends. Cette documentation doit compléter la documentation fonctionnelle.

Cependant, la documentation technique est bien souvent éparpillée dans le code source. De ce fait, avoir une vue globale devient rapidement compliqué.

Il existe, pour remédier à cela, des générateurs qui s'appuient sur la documentation du code source pour générer la documentation technique. J'utilise Sandcastle, un générateur de documentation gratuit pour CSharp.

Qu'est ce que SandCastle ?

SandCastle permet de générer la documentation technique d'une application à partir des fichiers xml de documentation générés par Microsoft Visual Studio. Sandcastle est un outil gratuit. Il se trouve sur codeplex à l'adresse http://shfb.codeplex.com/.

SandCastle se présente sous la forme d'un installeur qui va vous permettre d'ajouter et d'éditer les projets documentation SandcastleHelpFileBuilder.

Lorsque vous "compilez" un projet SHFB, vous générez votre documentation. Il est possible de générer l'aide au format chm et web (HTML/ASP.Net) pour ne citer qu'eux.

Commenter le code pour SandCastle

SandCastle s'appuie sur la documentation générée par Microsoft Visual Studio lors de la compilation. Il vous faut commenter les méthodes, propriétés et classes qui composent votre projet.

Taper /// sur la ligne précédent la déclaration de votre propriété/méthode/classe générera automatiquement un template. Il vous suffit de renseigner correctement les balises pour obtenir votre documentation.

Une fois vos commentaires renseignés, il faut activer la génération de la documentation dans les propriétés du projet documenté. Pour cela, faire Clic droit > Propriétés sur le projet concerné. Se rendre dans l'onglet Build, puis cocher XML Documentation File

Des balises dans les commentaires

Il est possible d'utiliser des balises HTML, mais surtout des balises spécifiques qui permettent de faire des liens entre divers éléments du code source de votre projet.

Par exemple pour faire un lien vers une classe :

<see cref="MonAssembly.DemoNameSpace.MaClasse"/>

SandCastle se chargera de générer le lien adequat qui vous permettra de naviguer rapidement entre les classes qui composent votre projet.

Je vous invite à consulter la liste des balises sur la MSDN.

Une remarque concernant la compilation de la documentation. Cela prends beaucoup de temps. C'est pourquoi, en phase de développement, il peut être nécessaire de désactiver la compilation du ou des projets shfb contenus dans votre solution.

Pour cela, il faut se rendre dans Build > Configuration Manager et décocher les projets shfb.

Resources concernant SandCastle

Vous y trouverez une explication détaillée de l'utilisation de Sandcastle ainsi que des détails concernant les tags à ajouter à votre documentation.

La MSDN contient la liste des tags ainsi que des exemples d'utilisation.