Partilhar via

Tags XML recomendadas para comentários da documentação em C#

Os comentários da documentação em 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 da documentação. O compilador C# copia esses elementos para o 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.

O que se segue são algumas recomendações, cenários gerais de casos de uso e coisas que você deve saber ao usar marcas de documentação XML em seu código C#. Embora você possa colocar qualquer tag nos comentários da documentação, este artigo descreve as tags recomendadas para as construções de linguagem mais comuns. Em todos os casos, deve aderir a estas recomendações:

  • Por uma questão de coerência, todos os tipos publicamente visíveis e os seus membros públicos devem ser documentados.
  • Membros privados também podem ser documentados usando comentários XML. No entanto, expõe o funcionamento interno (potencialmente confidencial) da sua biblioteca.
  • No mínimo, os tipos e seus membros devem ter uma <summary> tag.
  • O texto da documentação deve ser escrito usando frases completas que terminam com pontos finais.
  • As classes parciais são totalmente suportadas e as informações de documentação são concatenadas em uma única entrada para cada tipo. Se ambas as declarações de um membro parcial tiverem comentários de documentação, os comentários sobre a declaração de implementação serão gravados no XML de saída.

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

  • A documentação deve ser XML bem formado. Se o XML não estiver bem formado, o compilador gerará um aviso. O arquivo de documentação contém um comentário que diz que um erro foi encontrado.
  • Algumas das tags recomendadas têm significados especiais:
    • A <param> tag é usada para descrever parâmetros. Se usado, o compilador verifica se o parâmetro existe e se todos os parâmetros estão descritos na documentação. Se a verificação falhar, o compilador emitirá um aviso.
    • O cref atributo pode ser anexado a qualquer tag para fazer referência a um elemento de código. O compilador verifica se esse elemento de código existe. Se a verificação falhar, o compilador emitirá um aviso. O compilador respeita todas using as diretivas quando procura um tipo descrito no cref atributo.
    • A <summary> tag é usada pelo IntelliSense dentro do Visual Studio para exibir informações adicionais sobre um tipo ou membro.

      Nota

      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 juntamente com a reflexão sobre o tipo ou membro real.

  • Os desenvolvedores são livres para criar seu próprio conjunto de tags. O compilador copia essas tags para o arquivo de saída.

Algumas das tags recomendadas podem ser usadas em qualquer elemento de idioma. Outros têm uso mais especializado. Finalmente, algumas das tags são usadas para formatar texto em sua documentação. Este artigo descreve as tags recomendadas organizadas por seu uso.

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

Nota

Tags HTML como <br/> são úteis para formatação em comentários de documentação. A <br/> tag cria quebras de linha, enquanto outras tags HTML fornecem formatação de texto. Essas tags funcionam nas dicas de ferramentas do IntelliSense e na documentação gerada.

Nota

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

Se desejar que os colchetes angulares apareçam no texto de um comentário da documentação, use a codificação HTML de < e >, que é &lt; e &gt; respectivamente. Essa codificação é mostrada no exemplo a seguir.

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

Tags gerais

<summary>

<summary>description</summary>

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

<remarks>

<remarks>
description
</remarks>

A <remarks> etiqueta é usada para adicionar informação sobre um tipo ou um membro de tipo, complementando a informação especificada com <summary>. Essas informações são exibidas na janela Pesquisador de objetos. Esta tag pode incluir explicações mais longas. Você pode achar que usar CDATA seções para marcação torna a escrita mais conveniente. Ferramentas como docfx processam o texto de marcação em CDATA seções.

Membros do documento

<returns>

<returns>description</returns>

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

<param>

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

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

<paramref>

<paramref name="name"/>
  • name: O nome do parâmetro ao qual se refere. Coloque o nome entre aspas (").

A <paramref> tag fornece uma maneira de indicar que uma palavra nos comentários de código, por exemplo, em um <summary> bloco ou <remarks> se refere a um parâmetro. O arquivo XML pode ser processado para formatar essa palavra de alguma maneira 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 dada existe e se traduz member para o nome do elemento canônico no XML de saída. member deve aparecer entre aspas (").

A <exception> tag permite especificar quais exceções podem ser lançadas. Essa tag pode ser aplicada a definições de métodos, propriedades, eventos e indexadores.

<value>

<value>property-description</value>

A <value> tag permite descrever o valor que uma propriedade representa. Quando adicionas uma propriedade através do assistente de código no ambiente de desenvolvimento Visual Studio .NET, adiciona uma <summary> etiqueta para a nova propriedade. Você adiciona manualmente uma <value> tag para descrever o valor que a propriedade representa.

Formatar saída de documentação

<para>

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

A <para> etiqueta serve para uso dentro de uma etiqueta, como <summary>, <remarks>, ou <returns>, e permite-lhe adicionar estrutura ao texto. A <para> tag cria um parágrafo com espaçamento duplo. Use a <br/> tag se quiser um único parágrafo espaçado.

Aqui está um exemplo mostrando a diferença entre <para> e <br/>:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<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 <listheader> bloco é usado para definir a linha de título de uma tabela ou lista de definições.

Ao definir uma tabela:

  • Você só precisa fornecer uma entrada para term no título.
  • Cada item da lista é especificado com um <item> bloco. Para cada item, você só precisa fornecer uma entrada para description.

Ao criar uma lista de definições:

  • Você deve fornecer uma entrada para term no título.
  • Cada item da lista é especificado com um <item> bloco. Cada item um deve conter um term e descriptionum .

Uma lista ou tabela pode ter quantos <item> blocos forem necessários.

<c>

<c>text</c>

A <c> tag fornece uma maneira de indicar que o texto dentro de 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 <code> tag é usada para indicar várias linhas de código. Use <c> para indicar que texto de uma linha dentro de 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 <example> tag permite especificar um exemplo de como usar um método ou outro membro da biblioteca. Um exemplo envolve frequentemente o uso da <code> etiqueta.

<b>

<b>text</b>

A <b> tag é usada para colocar o texto em negrito nos comentários da documentação. Essa marca de formatação HTML é validada pelo compilador e pelo Visual Studio, e o texto formatado aparece no IntelliSense e na documentação gerada.

<i>

<i>text</i>

A <i> tag é usada para colocar o texto em itálico nos comentários da documentação. Essa marca de formatação HTML é validada pelo compilador e pelo Visual Studio, e o texto formatado aparece no IntelliSense e na documentação gerada.

<u>

<u>text</u>

A <u> tag é usada para sublinhar o texto nos comentários da documentação. Essa marca de formatação HTML é validada pelo compilador e pelo Visual Studio, e o texto formatado aparece no IntelliSense e na documentação gerada.

<br/>

Line one<br/>Line two

A <br/> tag é usada para inserir uma quebra de linha nos comentários da documentação. Use essa tag quando quiser um único parágrafo espaçado, em oposição à <para> tag que cria parágrafos com espaçamento duplo.

<a>

<a href="https://example.com">Link text</a>

A <a> tag é usada para criar hiperlinks nos comentários da documentação. O href atributo especifica a URL à qual vincular. Essa marca de formatação HTML é validada pelo compilador e pelo Visual Studio.

Nota

O compilador também valida a etiqueta <tt>, que é HTML obsoleto. Em vez disso, use a tag <c> para formatação de código inline.

Reutilizar texto da documentação

<inheritdoc>

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

Herdar comentários XML de classes base, interfaces e métodos semelhantes. O uso inheritdoc elimina a cópia e colagem indesejadas de comentários XML duplicados e mantém automaticamente os comentários XML sincronizados. Quando você adiciona a <inheritdoc> tag a um tipo, todos os membros herdam os comentários também.

  • cref: Especifique o membro do qual herdar a documentação. As tags já definidas no membro atual não são substituídas pelas herdadas.
  • path: A consulta de expressão XPath que resulta em um conjunto de nós para mostrar. Você pode usar esse atributo para filtrar as tags a serem incluídas ou excluídas da documentação herdada.

Nota

O Visual Studio fornece herança automática de documentação XML para membros não documentados que substituem ou implementam membros documentados. Esse recurso exibe a documentação herdada no IntelliSense e no Quick Info sem exigir a <inheritdoc> tag . No entanto, essa herança automática só se aplica dentro do IDE do Visual Studio e não afeta o arquivo de documentação XML gerado pelo compilador.

Para APIs públicas em bibliotecas que você distribui, você deve usar explicitamente a <inheritdoc> tag ou fornecer documentação completa para garantir que o arquivo de documentação XML gerado inclua todas as informações necessárias para os consumidores de sua biblioteca.

Adicione seus comentários XML em classes base ou interfaces e deixe inheritdoc copiar os comentários para classes de implementação. Adicione seus comentários XML aos seus métodos síncronos e deixe inheritdoc copiar os comentários para suas versões assíncronas dos mesmos métodos. Se quiser copiar os comentários de um membro específico, use o cref atributo 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 tags que filename leva à tag name. Coloque o caminho entre aspas simples (' ').
  • name: O especificador de nome na tag que precede os comentários; name tem um idarquivo .
  • id: O ID da tag que precede os comentários. Coloque o ID entre aspas (").

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

Por exemplo, o código-fonte a seguir usa a <include> tag 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 fonte XML para o arquivo de inclusão é mostrada no exemplo a seguir. Ele é estruturado da mesma forma que o 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 este 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>

Gorjeta

A equipe do .NET Runtime usa a <include> tag extensivamente em sua documentação. Você pode ver muitos exemplos pesquisando no dotnet/runtime repositó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 que está disponível para ser chamado a partir do ambiente de compilação atual. O compilador verifica se o elemento de código fornecido existe e passa member para o nome do elemento no XML de saída. Coloque o membro entre aspas ("). Você pode fornecer texto de link diferente para um "cref", usando uma tag de fechamento separada.
  • href="link": Um link clicável para um determinado URL. Por exemplo, <see href="https://github.com">GitHub</see> produz um link clicável com texto GitHub vinculado ao https://github.com. Use href em vez de cref ao vincular a páginas da Web externas, como cref é projetado para referências de código e não criará links clicáveis para URLs externos.
  • langword="keyword": Uma palavra-chave de idioma, como true ou uma das outras palavras-chave válidas.

A <see> tag permite especificar um link a partir do texto. Use <seealso> para indicar que o texto deve ser colocado numa secção Ver Também. Use o atributo cref para criar hiperlinks 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 funciona como um hiperlink.

Veja um exemplo que mostra a diferença entre cref e href ao fazer referência a URLs externas:

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

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

A <seealso> tag permite especificar o texto que você pode querer que apareça em uma seção Consulte também . Use <see> para especificar um link dentro do texto. Não é possível aninhar a seealso tag dentro dela summary .

atributo cref

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

atributo href

O href atributo significa uma referência a uma página da Web. Você pode usá-lo para fazer referência direta à documentação on-line sobre sua API ou biblioteca. Quando precisar vincular a URLs externos nos comentários da documentação, use href em vez de cref para garantir que os links sejam clicáveis nas dicas de ferramentas do IntelliSense e na documentação gerada.

Tipos e métodos genéricos

<typeparam>

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

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

<typeparamref>

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

Use essa tag para permitir que os consumidores do arquivo de documentação formatem a palavra de alguma maneira distinta, por exemplo, em itálico.

Tags definidas pelo usuário

Todas as tags descritas neste artigo representam as tags reconhecidas pelo compilador C#. No entanto, um usuário é livre para definir suas próprias tags. Ferramentas como o Sandcastle oferecem suporte para etiquetas extra como <event> e <note>, e até suportam a documentação de namespaces. Ferramentas de geração de documentação personalizadas ou internas também podem ser usadas com as tags padrão, e vários formatos de saída de HTML para PDF podem ser suportados.

  • Last updated on