Escrevendo documentação para projetos C#: do A ao Z

Por que uma documentação de qualidade para projetos C# é necessária?

Documentação é a ponte entre o desenvolvedor e o usuário do seu código. No mundo C# (.NET), essa ponte é construída com comentários XML e ferramentas especializadas (DocFX, Sandcastle). Uma boa documentação:

• Acelera a integração de novos desenvolvedores no projeto
• Reduz o número de perguntas em chats e tickets
• Melhora a qualidade do código (você acaba refatorando métodos ruins ao escrever a documentação para eles)
• Gera automaticamente um guia de referência da API (IntelliSense no Visual Studio)

Neste artigo, abordaremos o ciclo completo: desde a configuração do projeto até a publicação da documentação em um site estático. Todos os exemplos são em C# (.NET 8).

1. Comentários XML: a base da documentação em C#

1.1. Como habilitar a geração do arquivo XML

O Visual Studio (ou Rider) cria automaticamente um arquivo XML com comentários se você ativar a opção correspondente no .csproj:

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

Após a compilação, um arquivo XML com seus comentários aparecerá na pasta bin/Debug/net8.0/. Este arquivo é a matéria-prima para DocFX e Sandcastle.

1.2. Principais tags XML

Para escrever a documentação de um projeto C#, use as seguintes tags:

• <summary> — descrição resumida de uma classe, método ou propriedade.
• <param name="..."> — descrição de um parâmetro de método.
• <returns> — descrição do valor de retorno.
• <exception cref="..."> — quais exceções o método pode lançar.
• <example> — exemplo de uso.
• <see cref="..."> — link para outro tipo ou método.
• <code> — código formatado dentro da descrição.

1.3. Exemplo de comentário completo

/// <summary>/// Realiza a divisão segura de dois números com verificação de zero./// </summary>/// <param name="dividend">Dividendo (numerador).</param>/// <param name="divisor">Divisor (denominador). Não pode ser igual a 0.</param>/// <returns>Resultado da divisão como uma fração decimal.</returns>/// <exception cref="DivideByZeroException">Lançada se divisor for igual a 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("Divisão por zero não é permitida.");    return dividend / divisor;}

Dica: Escreva comentários em português se o projeto for interno, ou em inglês para uma API pública. O importante é manter um estilo consistente.

2. Ferramentas de geração de documentação: DocFX vs Sandcastle

2.1. DocFX (recomendado)

DocFX é uma ferramenta moderna da Microsoft que, a partir de comentários XML e arquivos Markdown adicionais, gera um site estático. Ela suporta C#, VB.NET e até JavaScript.

Instalação:

dotnet tool install -g docfx

Início rápido:

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

O DocFX automaticamente:

• Escaneia seus arquivos .csproj e .sln
• Extrai comentários XML
• Cria páginas para cada classe, método e propriedade
• Adiciona navegação, busca e temas bonitos (por padrão, Bootstrap)