Marcas XML recomendadas para comentários de documentação

  • Artigo

Os comentários da documentação do C# usam elementos XML para definir a estrutura da documentação de saída. Uma consequência desse recurso é que você pode adicionar qualquer XML válido em seus comentários de documentação. O compilador C# copia esses elementos no arquivo XML de saída. Embora você possa usar qualquer XML válido em seus comentários (incluindo qualquer elemento HTML válido), o código de documentação é recomendado por muitos motivos.

A seguir, temos algumas recomendações, cenários de caso de uso gerais e coisas que você precisa saber ao usar marcas de documentação XML em seu código C#. Embora você possa colocar marcas em seus comentários de documentação, este artigo descreve as marcas recomendadas para os constructos de idioma mais comuns. Em todos os casos, você deve seguir essas recomendações:

  • Para fins de consistência, todos os tipos visíveis publicamente e seus membros públicos devem ser documentados.
  • Membros particulares também podem ser documentados usando comentários XML. No entanto, isso expõe o funcionamento interno (potencialmente confidencial) da sua biblioteca.
  • No mínimo, os tipos e seus membros devem ter uma marca <summary>.
  • O texto da documentação deve ser escrito usando frases terminadas com ponto final.
  • Classes parciais têm suporte total e informações da documentação serão concatenadas em uma única entrada para cada tipo.

A documentação XML começa com ///. Quando você cria um novo projeto, os assistentes colocam algumas linhas iniciais /// para você. O processamento desses comentários tem algumas restrições:

  • A documentação deve ser em XML bem formado. Se o XML não estiver bem formado, o compilador gerará um aviso. O arquivo de documentação conterá um comentário que diz que um erro foi encontrado.
  • Algumas das marcas recomendadas têm significado especial:
    • A marca <param> é usada para descrever parâmetros. Se ela é usada, o compilador verifica se o parâmetro existe e se todos os parâmetros são descritos na documentação. Se a verificação falha, o compilador emite um aviso.
    • O atributo cref pode ser anexado a qualquer marca para fazer referência a um elemento de código. O compilador verifica se esse elemento de código existe. Se a verificação falha, o compilador emite um aviso. O compilador respeita qualquer instrução using quando procura por um tipo descrito no atributo cref.
    • A marca <summary> é usada pelo IntelliSense no Visual Studio para exibir informações adicionais sobre um tipo ou membro.

      Observação

      O arquivo XML não fornece informações completas sobre o tipo e os membros (por exemplo, ele não contém nenhuma informação de tipo). Para obter informações completas sobre um tipo ou membro, use o arquivo de documentação que reflita o membro ou tipo real.

  • Os desenvolvedores são livres para criar seu próprio conjunto de marcas. O compilador as copiará para o arquivo de saída.

Algumas das marcas recomendadas podem ser usadas em qualquer elemento de linguagem. Outras têm uso mais especializado. Por fim, algumas das marcas são usadas para formatar texto em sua documentação. Este artigo descreve as marcas recomendadas organizadas por uso.

O compilador verifica a sintaxe dos elementos seguidos por um único * na lista a seguir. O Visual Studio fornece o IntelliSense para as marcas verificadas pelo compilador e todas as marcas seguidas por ** na lista a seguir. Além das marcas listadas aqui, o compilador e o Visual Studio validam as marcas <b>, <i>, <u>, <br/> e <a>. O compilador também valida <tt>, que foi preterido em HTML.

Observação

Os comentários de documentação não podem ser aplicados a um namespace.

Se você quiser que os colchetes angulares sejam exibidos no texto de um comentário de documentação, use a codificação HTML de < e > que são &lt; e &gt; respectivamente. Essa codificação é mostrada no exemplo a seguir.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Marcas gerais

<summary>

<summary>description</summary>

A marca <summary> deve ser usada para descrever um tipo ou um membro de tipo. Use <remarks> para adicionar mais informações a uma descrição de tipo. Use o atributo cref para habilitar ferramentas de documentação como o DocFX e o Sandcastle para criar hiperlinks internos para páginas de documentação em elementos de código. O texto da marca <summary> é exibido no IntelliSense e na janela Pesquisador de Objetos.

<remarks>

<remarks>
description
</remarks>

A marca <remarks> é usada para adicionar informações sobre o tipo, complementando as informações especificadas com <summary>. Essas informações são exibidas na janela do Pesquisador de Objetos. Essa marca pode incluir explicações mais longas. Você pode achar que usar seções CDATA para markdown torna a gravação mais conveniente. Ferramentas como docfx processam o texto de markdown em seções CDATA.

Membros do documento

<returns>

<returns>description</returns>

A marca <returns> deve ser usada no comentário para uma declaração de método descrever o valor retornado.

<param>

<param name="name">description</param>
  • name: o nome do parâmetro de um método. Coloque o nome entre aspas duplas (" "). Os nomes dos parâmetros devem corresponder à assinatura da API. Se um ou mais parâmetros não forem abordados, o compilador emitirá um aviso. O compilador também emitirá um aviso se o valor name não corresponder a um parâmetro formal na declaração do método.

A marca <param> deve ser usada no comentário para uma declaração de método para descrever um dos parâmetros do método. Para documentar vários parâmetros, use várias marcas <param>. O texto da marca <param> é exibido no IntelliSense, o Navegador de objetos e o Relatório Web de comentários de código.

<paramref>

<paramref name="name"/>
  • name: o nome do parâmetro ao qual você deseja fazer referência. Coloque o nome entre aspas duplas (" ").

A marca <paramref> fornece uma maneira de indicar que uma palavra nos comentários do código, por exemplo, em um bloco <summary> ou <remarks> refere-se a um parâmetro. O arquivo XML pode ser processado para formatar essa palavra de alguma forma distinta, como com uma fonte em negrito ou itálico.

<exception>

<exception cref="member">description</exception>
  • cref = "member": uma referência a uma exceção que está disponível no ambiente de compilação atual. O compilador verifica se a exceção apresentada existe e move o member para o nome de elemento canônico no XML de saída. member deve ser exibido entre aspas duplas (" ").

A marca <exception> permite que você especifique quais exceções podem ser lançadas. Essa marca pode ser aplicada às definições de métodos, propriedades, eventos e indexadores.

<value>

<value>property-description</value>

A marca <value> permite descrever o valor que uma propriedade representa. Observe que quando você adiciona uma propriedade por meio do assistente de código no ambiente de desenvolvimento do Visual Studio .NET, ele adicionará uma marca <summary> à nova propriedade. Adicione manualmente uma marca <value> para descrever o valor que a propriedade representa.

Formatar a saída da documentação

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

A marca <para> é para ser usada dentro de uma marca, como <summary>, <remarks> ou <returns>, e permite adicionar estrutura ao texto. A <para> marca cria um parágrafo espaçado duplo. Use a <br/> marca se quiser um único parágrafo espaçado.

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

O bloco <listheader> é usado para definir a linha de cabeçalho de uma tabela ou lista de definição. Ao definir uma tabela, é necessário fornecer uma entrada para term no título. Cada item na lista é especificado com um bloco <item>. Ao criar uma lista de definições, será necessário especificar term e description. No entanto, para uma tabela, lista com marcadores ou lista numerada, será necessário fornecer apenas uma entrada para description. Uma lista ou tabela pode ter quantos blocos <item> forem necessários.

<c>

<c>text</c>

A marca <c> oferece uma forma de indicar que o texto em uma descrição deve ser marcado como código. Use <code> para indicar várias linhas como código.

<code>

<code>
    var index = 5;
    index++;
</code>

A marca <code> é usada para indicar várias linhas de código. Use <c> para indicar que o texto dentro uma descrição deve ser marcado como código.

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

A marca <example> permite especificar um exemplo de como usar um método ou outro membro da biblioteca. Normalmente, isso envolve o uso da marca <code>.

Reutilizar texto da documentação

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Herdar comentários XML de classes base, interfaces e métodos semelhantes. Usar inheritdoc elimina a cópia e a colagem indesejadas de comentários XML duplicados e mantém automaticamente os comentários XML sincronizados. Observe que quando você adicionar a marca <inheritdoc> a um tipo, todos os membros herdarão os comentários também.

  • cref: especifique o membro do qual herdar a documentação. As marcas já definidas no membro atual não são substituídas pelas herdadas.
  • path: a consulta de expressão XPath que resultará em um nó definido para mostrar. Você pode usar esse atributo para filtrar as marcas para incluir ou excluir da documentação herdada.

Adicione seus comentários XML em classes ou interfaces base e deixe herdado copiar os comentários para implementar classes. Adicione seus comentários XML aos métodos síncronos e deixe herdado copiar os comentários para suas versões assíncronas dos mesmos métodos. Se você quiser copiar os comentários de um membro específico, use o atributo cref para especificar o membro.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: o nome do arquivo XML que contém a documentação. O nome do arquivo pode ser qualificado com um caminho relativo ao arquivo de código-fonte. Coloque filename entre aspas simples (' ').
  • tagpath: O caminho das marcas em filename que leva à marca name. Coloque o caminho entre aspas simples (' ').
  • name: o especificador de nome na marca que precede os comentários; name terá um id.
  • id: a ID da marca que precede os comentários. Coloque a ID entre aspas duplas (" ").

A marca <include> permite consultar comentários em outro arquivo que descrevem os tipos e membros em seu código-fonte. Incluir um arquivo externo é uma alternativa para inserir comentários de documentação diretamente em seu arquivo de código-fonte. Colocando a documentação em um arquivo separado, é possível aplicar o controle do código-fonte à documentação separadamente do código-fonte. Uma pessoa pode fazer o check-out do arquivo de código-fonte e outra pessoa pode fazer o check-out do arquivo de documentação. A marca <include> usa a sintaxe XML XPath. Consulte a documentação do XPath para obter maneiras de personalizar o uso de <include>.

Por exemplo, o código-fonte a seguir usa a marca <include> para incluir observações. O caminho do arquivo é relativo à origem.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

A origem do XML do arquivo de inclusão é mostrada no exemplo a seguir. Sua estrutura é a mesma do arquivo XML gerado pelo compilador C#. O arquivo XML pode conter texto para vários métodos ou tipos, desde que uma expressão XPath possa identificá-los.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

A saída XML para esse método é mostrada no exemplo a seguir:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Dica

A equipe do .NET Runtime usa muito a marca <include> em sua documentação. Você pode ver muitos exemplos pesquisando no dotnet/runtimerepositório.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member":Uma referência a um membro ou campo disponível para ser chamado do ambiente de compilação atual. O compilador verifica se o elemento de código fornecido existe e passa member para o nome de elemento no XML de saída. Coloque member entre aspas duplas (“ ”). Você pode fornecer texto de link diferente para um "cref", usando uma marca de fechamento separada.
  • href="link":um link clicável para uma determinada URL. Por exemplo, <see href="https://github.com">GitHub</see> produz um link clicável com texto GitHub que é vinculado a https://github.com.
  • langword="keyword": uma palavra-chave de idioma, como true ou uma das outras palavras-chave válidas.

A marca <see> permite especificar um link de dentro do texto. Use <seealso> para indicar que o texto deve ser colocado em uma seção Confira também. Use o atributo cref para criar hyperlinks internos para páginas de documentação para elementos de código. Você inclui os parâmetros de tipo para especificar uma referência a um tipo ou método genérico, como cref="IDictionary{T, U}". Além disso, href é um atributo válido que funcionará como um hiperlink.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member":Uma referência a um membro ou campo disponível para ser chamado do ambiente de compilação atual. O compilador verifica se o elemento de código fornecido existe e passa member para o nome de elemento no XML de saída. member deve ser exibido entre aspas duplas (" ").
  • href="link":um link clicável para uma determinada URL. Por exemplo, <seealso href="https://github.com">GitHub</seealso> produz um link clicável com texto GitHub que é vinculado a https://github.com.

A marca <seealso> permite especificar o texto que você quer que seja exibido na seção Confira também Use <see> para especificar um link de dentro do texto. Não é possível aninhar a marca seealso dentro da marca summary.

atributo cref

O atributo cref em uma marca de documentação XML significa "referência de código". Ele especifica que o texto interno da marca é um elemento de código, como um tipo, método ou propriedade. Ferramentas de documentação, como o DocFX e o Sandcastle, usam os atributos cref para gerar automaticamente os hiperlinks para a página em que o tipo ou o membro está documentado.

Atributo href

O atributo href significa uma referência a uma página da Web. Você pode usá-lo para fazer referência direta à documentação online sobre sua API ou biblioteca.

Tipos e métodos genéricos

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: o nome do parâmetro de tipo. Coloque o nome entre aspas duplas (" ").

A marca <typeparam> deve ser usada no comentário para um tipo genérico ou para uma declaração de método descrever um dos parâmetros de tipo. Adicione uma marca para cada parâmetro de tipo do tipo ou do método genérico. O texto da marca <typeparam> será exibido no IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: o nome do parâmetro de tipo. Coloque o nome entre aspas duplas (" ").

Use essa marca para habilitar os consumidores do arquivo de documentação a formatar a palavra de alguma forma distinta, por exemplo, em itálico.

Marcas definidas pelo usuário

Todas as marcas descritas acima representam as marcas que são reconhecidas pelo compilador C#. No entanto, o usuário é livre para definir suas próprias marcas. Ferramentas como o Sandcastle dão suporte para marcas extras, como <event> e <note>, e até mesmo à documentação de namespaces. Ferramentas de geração de documentação internas ou personalizadas também podem ser usadas com as marcas padrão e vários formatos de saída, de HTML a PDF, podem ter suporte.