Rédaction de documentation pour un projet C# : de A à Z

Pourquoi une documentation de qualité pour un projet C# ?

La documentation est le pont entre le développeur et l'utilisateur de votre code. Dans le monde C# (.NET), ce pont se construit avec des commentaires XML et des outils spécialisés (DocFX, Sandcastle). Une bonne documentation :

• Accélère l'intégration des nouveaux développeurs dans le projet
• Réduit le nombre de questions dans les chats et les tickets
• Améliore la qualité du code (vous refactorez involontairement les mauvaises méthodes lorsque vous écrivez leur documentation)
• Génère automatiquement une référence API (IntelliSense dans Visual Studio)

Dans cet article, nous allons parcourir le cycle complet : de la configuration du projet à la publication de la documentation sur un site statique. Tous les exemples sont en C# (.NET 8).

1. Commentaires XML : le fondement de la documentation en C#

1.1. Comment activer la génération du fichier XML

Visual Studio (ou Rider) crée automatiquement un fichier XML avec les commentaires si vous activez l'option correspondante dans le fichier .csproj :

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile></PropertyGroup>

Après la compilation, un fichier XML avec vos commentaires apparaîtra dans le dossier bin/Debug/net8.0/. Ce fichier est la matière première pour DocFX et Sandcastle.

1.2. Principales balises XML

Pour rédiger la documentation d'un projet C#, utilisez les balises suivantes :

• <summary> — description brève de la classe, méthode, propriété.
• <param name="..."> — description du paramètre de la méthode.
• <returns> — description de la valeur de retour.
• <exception cref="..."> — quelles exceptions la méthode peut lever.
• <example> — exemple d'utilisation.
• <see cref="..."> — lien vers un autre type ou une autre méthode.
• <code> — code formaté à l'intérieur de la description.

1.3. Exemple de commentaire complet

/// <summary>/// Effectue une division sécurisée de deux nombres avec vérification de zéro./// </summary>/// <param name="dividend">Dividende (numérateur).</param>/// <param name="divisor">Diviseur (dénominateur). Ne peut pas être égal à 0.</param>/// <returns>Résultat de la division sous forme de fraction décimale.</returns>/// <exception cref="DivideByZeroException">Levée si divisor est égal à 0.</exception>/// <example>/// <code>/// double result = SafeDivider.Divide(10, 3);/// Console.WriteLine(result); // 3.333.../// </code>/// </example>public static double Divide(double dividend, double divisor){    if (divisor == 0)        throw new DivideByZeroException("La division par zéro est interdite.");    return dividend / divisor;}

Conseil : Rédigez les commentaires en français si le projet est interne, ou en anglais pour une API publique. L'essentiel est de respecter un style cohérent.

2. Outils de génération de documentation : DocFX vs Sandcastle

2.1. DocFX (recommandé)

DocFX est un outil moderne de Microsoft qui, à partir des commentaires XML et de fichiers Markdown supplémentaires, génère un site statique. Il prend en charge C#, VB.NET et même JavaScript.

Installation :

dotnet tool install -g docfx

Démarrage rapide :

docfx init -o my-docscd my-docsdocfx builddocfx serve _site

DocFX automatiquement :

• Analyse vos fichiers .csproj et .sln
• Extrait les commentaires XML
• Crée des pages pour chaque classe, méthode, propriété
• Ajoute une navigation, une recherche et de beaux thèmes (par défaut — Bootstrap)