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

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

Documentação de qualidade é a chave para um projeto C# bem-sucedido e sustentável. Ela ajuda os desenvolvedores a entender rapidamente o código, facilita a integração de novos membros da equipe e reduz o número de erros. Neste artigo, abordaremos o processo completo de criação de documentação para um projeto C# (.NET): desde os fundamentos dos comentários XML até a geração automática de sites bonitos.

1. Fundamentos dos comentários XML em C#

A maneira padrão de documentar código em C# são os comentários XML. Eles são escritos antes da declaração de uma classe, método, propriedade ou outro elemento e começam com três barras ///. O compilador C# reconhece esses comentários e pode gerar um arquivo XML de documentação.

Aqui estão as tags básicas que você usará com mais frequência:

\n
• <summary> — descrição resumida do elemento.
\n
• <param name="nome"> — descrição do parâmetro do método.
\n
• <returns> — descrição do valor de retorno.
\n
• <exception cref="Tipo"> — descrição da exceção que o método pode lançar.
\n
• <example> — exemplo de uso.
\n
• <remarks> — observações adicionais.
\n

Exemplo de um comentário XML correto para um método:

/// <summary>\n/// Calcula o fatorial de um número inteiro não negativo.\n/// </summary>\n/// <param name="n">Número inteiro não negativo.</param>\n/// <returns>Fatorial do número n.</returns>\n/// <exception cref="System.ArgumentException">Lançada se n for menor que 0.</exception>\n/// <example>\n/// <code>\n/// int result = Factorial(5);\n/// // result é igual a 120\n/// </code>\n/// </example>\npublic static int Factorial(int n)\n{\n    if (n < 0)\n        throw new ArgumentException("n não pode ser negativo", nameof(n));\n\n    int result = 1;\n    for (int i = 1; i <= n; i++)\n    {\n        result *= i;\n    }\n    return result;\n}

2. Documentando classes e propriedades

Não se esqueça de documentar não apenas os métodos, mas também as próprias classes, bem como suas propriedades e campos. Isso é especialmente importante para APIs públicas que serão usadas por outros desenvolvedores.

Para propriedades, use as tags <summary> e <value> (para descrever o valor armazenado):

/// <summary>\n/// Representa um usuário do sistema.\n/// </summary>\npublic class User\n{\n    /// <summary>\n    /// Identificador único do usuário.\n    /// </value>\n    public int Id { get; set; }\n\n    /// <summary>\n    /// Nome completo do usuário.\n    /// </summary>\n    /// <value>String contendo nome e sobrenome.</value>\n    public string FullName { get; set; }\n\n    /// <summary>\n    /// Cria um novo usuário.\n    /// </summary>\n    /// <param name="id">Identificador.</param>\n    /// <param name="fullName">Nome completo.</param>\n    public User(int id, string fullName)\n    {\n        Id = id;\n        FullName = fullName ?? throw new ArgumentNullException(nameof(fullName));\n    }\n}

3. Geração do arquivo XML e compilação da documentação

Para obter um arquivo XML a partir dos seus comentários, você precisa configurar o projeto. No Visual Studio ou através do arquivo .csproj, adicione:

<PropertyGroup>\n  <GenerateDocumentationFile>true</GenerateDocumentationFile>\n  <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile>\n  <NoWarn>$(NoWarn);1591</NoWarn> <!-- Desativa o aviso sobre comentários ausentes, se necessário -->\n</PropertyGroup>

Após compilar o projeto, você obterá um arquivo XML que pode ser usado para criar