Writing Documentation for a C# Project: From A to Z

Why do you need high-quality C# project documentation?

Documentation is the bridge between the developer and the user of your code. In the world of C# (.NET), this bridge is built using XML comments and specialized tools (DocFX, Sandcastle). Good documentation:

• Accelerates onboarding of new developers to the project
• Reduces the number of questions in chats and tickets
• Improves code quality (you inevitably refactor bad methods when writing docs for them)
• Automatically generates an API reference (IntelliSense in Visual Studio)

In this article, we will cover the full cycle: from project setup to publishing documentation on a static site. All examples are in C# (.NET 8).

1. XML Comments: The Foundation of Documentation in C#

1.1. How to Enable XML File Generation

Visual Studio (or Rider) automatically creates an XML file with comments if you enable the corresponding option in .csproj:

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

After building, an XML file with your comments will appear in the bin/Debug/net8.0/ folder. This file is the raw material for DocFX and Sandcastle.

1.2. Basic XML Tags

To write documentation for a C# project, use the following tags:

• <summary> — a brief description of a class, method, or property.
• <param name="..."> — description of a method parameter.
• <returns> — description of the return value.
• <exception cref="..."> — which exceptions the method can throw.
• <example> — usage example.
• <see cref="..."> — a link to another type or method.
• <code> — formatted code within the description.

1.3. Example of a Complete Comment

/// <summary>/// Performs safe division of two numbers with a zero check./// </summary>/// <param name="dividend">The dividend (numerator).</param>/// <param name="divisor">The divisor (denominator). Cannot be zero.</param>/// <returns>The result of the division as a decimal fraction.</returns>/// <exception cref="DivideByZeroException">Thrown if divisor is zero.</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("Division by zero is not allowed.");    return dividend / divisor;}

Tip: Write comments in Russian if the project is internal, or in English for a public API. The main thing is to maintain a consistent style.

2. Documentation Generation Tools: DocFX vs Sandcastle

2.1. DocFX (Recommended)

DocFX is a modern tool from Microsoft that generates a static site from XML comments and additional Markdown files. It supports C#, VB.NET, and even JavaScript.

Installation:

dotnet tool install -g docfx

Quick Start:

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

DocFX automatically:

• Scans your .csproj and .sln files
• Extracts XML comments
• Creates pages for each class, method, and property
• Adds navigation, search, and beautiful themes (Bootstrap by default)