Melhores Práticas de Documentação em C#

• Membros públicos devem ser documentados com comentários XML.
• É recomendado documentar membros internos também, especialmente se forem complexos ou não autoexplicativos.

Orientações para todas as APIs

• Use <summary> para fornecer uma descrição breve, em uma única frase, do que o tipo ou membro faz. Comece o resumo com um verbo no presente e na terceira pessoa.
• Use <remarks> para informações adicionais, que podem incluir detalhes de implementação, notas de uso ou qualquer outro contexto relevante.
• Use <see langword> para palavras-chave específicas da linguagem como null, true, false, int, bool, etc.
• Use <c> para trechos de código em linha.
• Use <example> para exemplos de uso de como utilizar o membro.
  • Use <code> para blocos de código. As tags <code> devem ser colocadas dentro de uma tag <example>. Adicione a linguagem do exemplo de código usando o atributo language, por exemplo, <code language="csharp">.
• Use <see cref> para referenciar outros tipos ou membros em linha (em uma frase).
• Use <seealso> para referências isoladas (não em uma frase) a outros tipos ou membros na seção "Veja também" da documentação online.
• Use <inheritdoc/> para herdar documentação de classes base ou interfaces.
  • A menos que haja uma grande mudança de comportamento, caso em que você deve documentar as diferenças.

Métodos

• Use <param> para descrever parâmetros de métodos.
  • A descrição deve ser uma frase nominal que não especifica o tipo de dado.
  • Comece com um artigo introdutório.
  • Se o parâmetro for um enum de flags, comece a descrição com "Uma combinação bit a bit dos valores da enumeração que especifica...".
  • Se o parâmetro for um enum sem flags, comece a descrição com "Um dos valores da enumeração que especifica...".
  • Se o parâmetro for um Booleano, a redação deve ser do tipo "<see langword="true" /> para ...; caso contrário, <see langword="false" />.".
  • Se o parâmetro for um parâmetro "out", a redação deve ser do tipo "Quando este método retornar, conterá .... Este parâmetro é tratado como não inicializado.".
• Use <paramref> para referenciar nomes de parâmetros na documentação.
• Use <typeparam> para descrever parâmetros de tipo em tipos ou métodos genéricos.
• Use <typeparamref> para referenciar parâmetros de tipo na documentação.
• Use <returns> para descrever o que o método retorna.
  • A descrição deve ser uma frase nominal que não especifica o tipo de dado.
  • Comece com um artigo introdutório.
  • Se o tipo de retorno for Booleano, a redação deve ser do tipo "<see langword="true" /> se ...; caso contrário, <see langword="false" />.".

Construtores

• A redação do resumo deve ser "Inicializa uma nova instância da classe <Class> [ou struct].".

Propriedades

• O <summary> deve começar com:
  • "Obtém ou define..." para uma propriedade de leitura e escrita.
  • "Obtém..." para uma propriedade somente leitura.
  • "Obtém [ou define] um valor que indica se..." para propriedades que retornam um valor Booleano.
• Use <value> para descrever o valor da propriedade.
  • A descrição deve ser uma frase nominal que não especifica o tipo de dado.
  • Se a propriedade tiver um valor padrão, adicione-o em uma frase separada, por exemplo, "O padrão é <see langword="false" />".
  • Se o tipo de valor for Booleano, a redação deve ser do tipo "<see langword="true" /> se ...; caso contrário, <see langword="false" />. O padrão é ...".

Exceções

• Use <exception cref> para documentar exceções lançadas por construtores, propriedades, indexadores, métodos, operadores e eventos.
• Documente todas as exceções lançadas diretamente pelo membro.
• Para exceções lançadas por membros aninhados, documente apenas as exceções que os usuários têm maior probabilidade de encontrar.
• A descrição da exceção descreve a condição sob a qual ela é lançada.
  • Omita "Lançada se ..." ou "Se ..." no início da frase. Apenas declare a condição diretamente, por exemplo, "Ocorreu um erro ao acessar uma API de Filas de Mensagens.".