Написание документации для C# проекта: от А до Я

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Зачем нужна качественная документация C# проекта?

Документация — это мост между разработчиком и пользователем вашего кода. В мире C# (.NET) этот мост строится с помощью XML-комментариев и специализированных инструментов (DocFX, Sandcastle). Хорошая документация:

Ускоряет ввод новых разработчиков в проект
Уменьшает количество вопросов в чатах и тикетах
Повышает качество кода (вы невольно рефакторите плохие методы, когда пишете для них доки)
Автоматически генерирует API-справочник (IntelliSense в Visual Studio)

В этой статье мы разберём полный цикл: от настройки проекта до публикации документации на статический сайт. Все примеры — на C# (.NET 8).

1. XML-комментарии: основа документации в C#

1.1. Как включить генерацию XML-файла

Visual Studio (или Rider) автоматически создаёт XML-файл с комментариями, если включить соответствующую опцию в .csproj:

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

После сборки в папке bin/Debug/net8.0/ появится XML-файл с вашими комментариями. Этот файл — сырьё для DocFX и Sandcastle.

1.2. Основные XML-теги

Для написания документации C# проекта используйте следующие теги:

<summary> — краткое описание класса, метода, свойства.
<param name="..."> — описание параметра метода.
<returns> — описание возвращаемого значения.
<exception cref="..."> — какие исключения может выбросить метод.
<example> — пример использования.
<see cref="..."> — ссылка на другой тип или метод.
<code> — форматированный код внутри описания.

1.3. Пример полного комментария

/// <summary>
/// Выполняет безопасное деление двух чисел с проверкой на ноль.
/// </summary>
/// <param name="dividend">Делимое (числитель).</param>
/// <param name="divisor">Делитель (знаменатель). Не может быть равен 0.</param>
/// <returns>Результат деления в виде десятичной дроби.</returns>
/// <exception cref="DivideByZeroException">Выбрасывается, если divisor равен 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("Деление на ноль запрещено.");
    return dividend / divisor;
}

Совет: Пишите комментарии на русском, если проект внутренний, или на английском — для открытого API. Главное — соблюдать единый стиль.

2. Инструменты генерации документации: DocFX vs Sandcastle

2.1. DocFX (рекомендуемый)

DocFX — современный инструмент от Microsoft, который из XML-комментариев и дополнительных Markdown-файлов генерирует статический сайт. Он поддерживает C#, VB.NET и даже JavaScript.

Установка:

dotnet tool install -g docfx

Быстрый старт:

docfx init -o my-docs
cd my-docs
docfx build
docfx serve _site

DocFX автоматически:

Сканирует ваши .csproj и .sln файлы
Извлекает XML-комментарии
Создаёт страницы для каждого класса, метода, свойства
Добавляет навигацию, поиск и красивые темы (по умолчанию — Bootstrap)

2.2. Sandcastle Help File Builder (SHFB)

Классический инструмент для Windows. Генерирует CHM-справку (Windows Help) или HTML. Работает через GUI-мастер, что удобно для консервативных проектов. Однако он менее гибок, чем DocFX, и не поддерживает современные темы.

Когда выбирать Sandcastle: если нужна CHM-справка для офлайн-использования или проект использует устаревшие версии .NET Framework.

3. Структура документации: от README до API-справочника

3.1. Главный файл: README.md или index.md

Это лицо вашей документации. В DocFX он автоматически становится домашней страницей. Напишите:

Что делает библиотека/проект
Краткий пример кода (как начать)
Ссылки на API-справочник, руководства, changelog

3.2. Дополнительные статьи (Articles)

Создайте папку articles/ и добавьте туда Markdown-файлы с руководствами:

getting-started.md — пошаговая инструкция
configuration.md — настройка и конфиги
troubleshooting.md — частые ошибки
changelog.md — история версий

3.3. API-справочник (автоматическая генерация)

DocFX собирает все публичные типы и методы из вашей сборки. Для каждого элемента создаётся отдельная страница с полным описанием, списком параметров, исключений и примеров. Вам нужно только написать качественные XML-комментарии — остальное сделает инструмент.