Documentez vos projets et codes .NET à l'aide de GhostDoc et SandCastle

Kevin Perriat

Dans cet article, nous allons découvrir des outils qui vont nous permettre d'automatiser une partie de la création d'une documentation pour nos projets. Cette étape est importante pour une éventuelle reprise de votre projet, mais aussi afin d'éviter un maximum la redondance de code. Jugée des fois longue à mettre en place, nous allons découvrir deux outils qui vont nous simplifier la tâche.

Commentez cet article : Commentez

- Titre : Documentez vos projets et codes .NET à l'aide de GhostDoc et SandCastle

- Auteur : Kevin Perriat

- Parution : 11 février 2014

- Licence : Copyright ® 2012 Kevin Perriat. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. GhostDoc

- I-A. Présentation

- I-B. Installation

- I-C. Configuation

- I-D. Conclusion

- II. Sandcastle

- II-A. Installation

- II-B. Préparation de la solution

- II-C. Sandcastle Help File Builder

- II-C-1. Ajout des sources de documentation

- II-C-2. Paramétrage du fichier de sortie

- II-C-3. Choix des éléments à afficher

- II-C-4. Génération de la documentation

- III. Conclusion

- IV. Remerciements

I - GhostDoc

I-A - Présentation

GhostDoc est un outil s'intégrant à Visual Studio qui va permettre de générer automatiquement les commentaires sur les méthodes, les classes... Son fonctionnement est simple : une fois installé, nous disposerons d'un raccourci (Ctrl + Shift + D) qui commentera la méthode, la propriété... sur laquelle nous nous trouvons. Nous pourrons aussi commenter automatiquement toute une classe.

La particularité de GhostDoc est que nous allons pouvoir entièrement le paramétrer à l'aide de règles. Il est par exemple capable par défaut de décrire de manière précise une méthode, en fonction des mots clés contenus dans le nom de celle-ci. Par exemple, la méthode listUsers pourra être documentée automatiquement ainsi : listing of all users.

Je présume que vous commencez à voir l'intérêt d'un tel outil. Envie d'en savoir plus ? Alors, passons à l'installation de ce logiciel.

I-B - Installation

Dans cette partie, nous allons donc nous intéresser à l'installation de GhostDoc. Tout d'abord, nous devons télécharger l'installeur sur le site officiel. Une fois téléchargé, lancez l'installeur :

Poursuivez l'installation et choisissez les versions de Visual Studio auxquelles vous voulez installer GhostDoc :

Une fois installé, vous pouvez lancer Visual Studio. À l'ouverture, une fenêtre vous demandera de définir le raccourci pour faire appel à GhostDoc. Il vous proposera aussi de mettre à jour les différentes règles. La configuration terminée, vous pourrez voir dans le menu Outils une section GhostDoc, qui vous prouvera que cet outil s'est bien installé.

I-C - Configuation

Nous allons maintenant voir comment configurer GhostDoc. Pour cela, nous allons prendre un cas pratique : nous voulons que la description des méthodes correspondant au schéma sumXXX soit de ce type : "calculate sum of XXX". Voici un résultat qu'il sera possible d'obtenir avec cette configuration :

/// <summary>
/// Calculate sum of Prices
/// </summary>
/// <returns></returns>
private int sumPrices()
{
return 3000;
}

Pour commencer, ouvrons la fenêtre de configuration de GhostDoc : Outils / GhostDoc / Options. Vous devez voir apparaître une liste de règles assez fournie. Nous allons rajouter la nôtre dans la rubrique Methods. Pour cela, sélectionnez la bonne rubrique et cliquez sur Add :

Maintenant, nous allons bien configurer notre règle. Commencez par sélectionner le type de votre règle (un seul doit être disponible : Custom match of method signature). Je vous conseille de donner un nom facilement identifiable afin de retrouver votre règle par la suite. Nous allons ensuite modifier la correspondance avec le nom de la méthode, en indiquant que celui-ci doit contenir sum :

Nous allons à présent changer le contenu du summary des commentaires pour cette règle. Pour cela, cliquez sur les ... en face de summary. Dans la nouvelle fenêtre, saisissez comme template text : "Calculate sum of ". Afin de finir notre summary, sélectionnez dans la liste des macros la macro suivante : MethodeName / Words / ExceptFirst :

Cette macro a pour résultat de prendre tous les mots du nom de notre méthode sauf le premier. Pour distinguer les différents mots, GhostDoc se base sur les majuscules. Si nous prenons l'exemple sumPrices, cette macro retournera Prices.

Pour tester notre règle, nous allons créer une méthode sumStudents et générer le commentaire grâce à GhostDoc. Si vous avez bien suivi la création de la règle, voici ce que vous devriez obtenir :

/// <summary>
/// Calculate sum of students
/// </summary>
/// <returns></returns>
private int sumStudents()
{
return 10;
}

I-D - Conclusion

Comme vous avez pu le voir, GhostDoc permet donc une documentation rapide de nos codes. De plus, par sa grande personnalisation, nous allons vraiment pouvoir le configurer à nos besoins. Malheureusement, vous devrez par moment retoucher vous-même les descriptions faites par GhostDoc.

II - Sandcastle

Dans cette seconde partie de l'article, nous allons découvrir un logiciel qui va nous permettre de générer des fichiers de documentation pour nos codes. Ce fichier va se baser sur les commentaires mis dans nos codes. Vous comprenez donc que couplé à GhostDoc, SandCastle peut réellement produire un résultat très intéressant.

II-A - Installation

L'installation de SandCastle n'est pas la plus facile au monde. Nous allons commencer par télécharger un installeur comprenant tous les composants nécessaires à la génération d'une documentation. Pour cela, rendons-nous sur la page CodePlex de SandCastle Help File Builder.

Quand vous aurez téléchargé l'installeur, exécutez-le et validez toutes les étapes. Attention, lors de certaines d'entre elles, vous devrez accomplir une action avant de pouvoir passer à l'étape suivante.

II-B - Préparation de la solution

Avant de pouvoir générer notre documentation, nous allons devoir indiquer à Visual Studio de générer un fichier xml contenant l'intégralité de nos documentations de code. Pour cela, clic droit sur votre projet / Propriétés / Générer et cochez la case "Fichier de documentation XML" :

Maintenant, à chaque génération de votre projet, un fichier de documentation au format XML sera créé. C'est celui-ci que nous allons utiliser pour générer notre documentation.

II-C - Sandcastle Help File Builder

Pour générer notre documentation, nous allons utiliser Sandcastle Help File Builder Gui, qui est une interface graphique de SandCastle. Nous allons détailler les différentes étapes pour obtenir une belle documentation.

II-C-1 - Ajout des sources de documentation

La première étape consiste en l'ajout des sources qui serviront à SandCastle pour construire la documentation. Pour cela, dans l'explorateur de projet, clic droit sur Documentation Sources puis Add Documentation Source. Il ne vous reste plus qu'à aller chercher votre exécutable/dll et votre fichier XML comprenant vos commentaires.

II-C-2 - Paramétrage du fichier de sortie

Nous allons maintenant personnaliser un peu notre documentation. Pour cela, nous allons nous intéresser aux propriétés disponibles dans la rubrique Help File :

- HelpTitle : nom de la documentation. Celui-ci apparaîtra lors du visionnage de la documentation ;

- HtmlHelpName : nom du fichier de sortie ;

- Language : langue de la documentation ;

- SyntaxFilters : langages (C#, Visual Basic, ...) insérés dans la documentation.

Dans la rubrique Paths, la propriété OutputPath permet de définir le chemin de sortie du fichier.

Avec ces réglages, vous pourrez personnaliser votre documentation. D'autres réglages existent, mais je vous laisse le soin de les découvrir.

II-C-3 - Choix des éléments à afficher

Un autre aspect intéressant de SandCastle est que nous allons pouvoir sélectionner les éléments que nous souhaitons inclure dans la documentation. Typiquement, nous ne souhaitons pas faire apparaître tous les espaces de noms de notre application. Pour cela, rendons-nous dans la rubrique Visibility puis sur ApiFilter. Dans la nouvelle fenêtre, vous devriez voir apparaître vos différents espaces de nom :

II-C-4 - Génération de la documentation

Maintenant que nous avons bien paramétré notre documentation, il ne nous reste plus qu'à la générer. Pour cela, il suffit d'aller dans le menu Documentation et de faire Build Project. Un nouvel onglet va s'afficher dans la fenêtre principale vous affichant les informations de build. La construction de la documentation sera terminée lorsque vous obtiendrez ce message :

Build completed successfully at 07/13/2012 11:11 .  Total time: 00:00:49,9370

Une fois cette étape de sortie, il ne vous reste plus qu'à ouvrir le fichier .chm généré pour visualiser votre nouvelle documentation :

Comme vous pouvez le voir dans la capture ci-dessus, les informations manquantes à votre documentation peuvent apparaître en rouge. Tout ceci est bien entendu totalement configurable au sein de SandCastle.

III - Conclusion

Au sein de cet article, nous avons vu comment utiliser des outils nous permettant de faciliter la mise en place d'une documentation technique de nos projets. Sachez qu'un projet bien documenté est un projet qui sera plus facilement viable dans le temps. En effet, il facilitera l'intégration de nouveaux membres et toute reprise éventuelle.

IV - Remerciements

Je tiens à remercier Jean-Michel Ormes et tomlev pour leur aide dans la rédaction de cet article. Je tiens aussi à remercier ced pour sa relecture.