Partilhar via

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

  • Artigo

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 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 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 conterá 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 instruções 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 irá copiá-los 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

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

<Resumo>

<summary>description</summary>

A <summary> tag deve ser usada para descrever um tipo ou um membro do tipo. Use <comentários> para adicionar informações suplementares a uma descrição de 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.

<Comentários>

<remarks>
description
</remarks>

A <remarks> tag é usada para adicionar informações sobre um tipo ou um membro do tipo, complementando as informações especificadas com <resumo>. 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

<devoluções>

<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 duplas (" "). 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 duplas (" ").

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.

<exceção>

<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 duplas (" ").

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.

<valor>

<value>property-description</value>

A <value> tag permite descrever o valor que uma propriedade representa. Quando você adiciona uma propriedade via assistente de código no ambiente de desenvolvimento do Visual Studio .NET, ele adiciona uma marca de <resumo> 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> tag é para uso dentro de uma tag, como <resumo>, <observações> ou <retornos>, e permite 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.

<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 cabeçalho. Cada item da lista é especificado com um <item> bloco. Ao criar uma lista de definições, você precisará especificar ambos e termdescription. No entanto, para uma tabela, lista com marcadores ou lista numerada, você só precisa fornecer uma entrada para description. 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 <o código> 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 o texto de linha única dentro de uma descrição deve ser marcado como código.

<Exemplo>

<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 geralmente envolve o uso da tag de código>.<

Reutilizar texto da documentação

<herançadoc>

<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. Observe que 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 resultará 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.

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.

<incluem>

<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 terá um idarquivo .
  • id: O ID da tag que precede os comentários. Coloque o ID entre aspas duplas (" ").

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.

<veja>

<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 duplas (" "). 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.
  • 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 em uma seção Consulte 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 funcionará como um hiperlink.

<Ver também>

<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 duplas (" ").
  • 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 de 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.

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 duplas (" ").

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 será exibido no IntelliSense.

<tipoparamref>

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

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 acima representam as tags que são reconhecidas pelo compilador C#. No entanto, um usuário é livre para definir suas próprias tags. Ferramentas como Sandcastle trazem suporte para tags extras, como <evento> e< nota>, e até mesmo suporte para documentar 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.