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

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.

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 officielTéléchargement GhostDoc, Kevin Perriat. 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é.

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

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.

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.

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.

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▲

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 :

 

Sélectionnez

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.