Partilhar via

Gerar comentários da documentação da API XML

Os arquivos de origem C# podem incluir comentários estruturados que produzem documentação de API para os tipos definidos nesses arquivos. O compilador C# produz um arquivo XML que contém dados estruturados que representam os comentários e as assinaturas da API. Outras ferramentas podem processar essa saída XML para criar documentação legível por humanos na forma de páginas da Web ou arquivos PDF, por exemplo.

A referência da linguagem C# documenta a versão mais recentemente lançada da linguagem C#. Contém também documentação inicial para funcionalidades em pré-visualizações públicas para o próximo lançamento linguístico.

A documentação identifica qualquer funcionalidade introduzida pela primeira vez nas últimas três versões da língua ou em pré-visualizações públicas atuais.

Sugestão

Para saber quando uma funcionalidade foi introduzida pela primeira vez em C#, consulte o artigo sobre o histórico de versões da linguagem C#.

Esse processo oferece muitas vantagens para você adicionar documentação de API em seu código:

  • O compilador C# combina a estrutura do código C# com o texto dos comentários em um único documento XML.
  • O compilador C# verifica se os comentários correspondem às assinaturas da API para tags relevantes.
  • As ferramentas que processam os arquivos de documentação XML podem definir elementos XML e atributos específicos para essas ferramentas.

Ferramentas como o Visual Studio fornecem IntelliSense para muitos elementos XML comuns usados em comentários de documentação.

Este artigo aborda estes tópicos:

  • Comentários da documentação e geração de arquivos XML
  • Tags validadas pelo compilador C# e Visual Studio
  • Formato do arquivo XML gerado

Criar saída de documentação XML

Você cria documentação para seu código escrevendo campos de comentário especiais indicados por barras triplas. Os campos de comentário incluem elementos XML que descrevem o bloco de código que segue os comentários. Por exemplo:

/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass { }

Define a opção GenerarDocumentação ou Ficheiro de Documentação . O compilador encontra todos os campos de comentário com etiquetas XML no código-fonte e cria um ficheiro de documentação XML a partir desses comentários. Quando ativa esta opção, o compilador gera o aviso CS1591 para qualquer membro visível publicamente declarado no seu projeto sem comentários na documentação XML.

Formatos de comentário XML

O uso de comentários doc XML requer delimitadores que indiquem onde começa e termina um comentário de documentação. Use os seguintes delimitadores com as etiquetas de documentação XML:

  • /// Delimitador de linha única: Os exemplos de documentação e modelos de projeto C# usam este formulário. Se o espaço em branco seguir o delimitador, ele não será incluído na saída XML.

    Observação

    O Visual Studio insere automaticamente as tags e <summary> posiciona o </summary> cursor dentro dessas tags depois de digitar o /// delimitador no editor de códigos. Você pode ativar ou desativar esse recurso na caixa de diálogo Opções.

  • /** */ Delimitadores multilinha: Os /** */ delimitadores têm as seguintes regras de formatação:

    • Na linha que contém o /** delimitador, se o restante da linha for espaço em branco, a linha não será processada para comentários. Se o primeiro caractere após o /** delimitador for espaço em branco, esse caractere de espaço em branco será ignorado e o restante da linha será processado. Caso contrário, todo o texto da linha após o /** delimitador é processado como parte do comentário.

    • Na linha que contém o */ delimitador, se houver apenas espaço em branco até o */ delimitador, essa linha será ignorada. Caso contrário, o texto na linha até o */ delimitador é processado como parte do comentário.

    • Para as linhas após aquela que começa com o /** delimitador, o compilador procura um padrão comum no início de cada linha. O padrão pode consistir em espaço em branco opcional e/ou um asterisco (*), seguido por mais espaço em branco opcional. Se o compilador encontrar um padrão comum no início de cada linha que não comece com o /** delimitador ou termine com o */ delimitador, ele ignorará esse padrão para cada linha.

    • A única parte do seguinte comentário processado é a linha que começa com <summary>. Os três formatos de tag produzem os mesmos comentários.

      /** <summary>text</summary> */

/**
<summary>text</summary>
*/

/**
* <summary>text</summary>
*/

    • O compilador identifica um padrão comum de " * " no início da segunda e terceira linhas. O padrão não está incluído na saída.

      /**
* <summary>
* text </summary>*/

    • O compilador não encontra nenhum padrão comum no comentário a seguir porque o segundo caractere na terceira linha não é um asterisco. Todo o texto na segunda e terceira linhas é processado como parte do comentário.

      /**
* <summary>
   text </summary>
*/

    • O compilador não encontra nenhum padrão no comentário a seguir por dois motivos. Primeiro, o número de espaços antes do asterisco não é consistente. Em segundo lugar, a quinta linha começa com uma guia, que não corresponde aos espaços. Todo o texto das linhas dois a cinco é processado como parte do comentário.

      /**
  * <summary>
  * text
*  text2
 	*  </summary>
*/

Para se referir a elementos XML (por exemplo, a sua função processa elementos XML específicos que pretende descrever num comentário de documentação XML), use o mecanismo padrão de citação (&lt; e &gt;). Para se referir a identificadores genéricos em elementos de referência de código (cref), use os caracteres de escape (por exemplo, cref="List&lt;T&gt;") ou colchetes (cref="List{T}"). Como um caso especial, o compilador analisa as chaves como colchetes angulares para tornar o comentário da documentação menos complicado para o autor quando se refere a identificadores genéricos.

Observação

Se escrever comentários usando o delimitador de comentários XML de linha única, ///, mas não incluir etiquetas, o compilador adiciona o texto desses comentários ao ficheiro de saída XML. No entanto, a saída não inclui elementos XML como <summary>. A maioria das ferramentas que consomem comentários XML (incluindo o Visual Studio IntelliSense) não lê esses comentários.

Ferramentas que aceitam entrada de documentação XML

As seguintes ferramentas criam saída a partir de comentários XML:

  • DocFX: DocFX é um gerador de documentação de API para .NET, que atualmente suporta C#, Visual Basic e F#. Ele também permite que você personalize a documentação de referência gerada. DocFX constrói um site HTML estático a partir do seu código fonte e arquivos Markdown. Além disso, DocFX fornece a flexibilidade para personalizar o layout e estilo do seu site através de modelos. Você também pode criar modelos personalizados.
  • Sandcastle: As ferramentas do Sandcastle criam arquivos de ajuda para bibliotecas de classes gerenciadas contendo páginas de referência conceituais e de API. As ferramentas do Sandcastle são baseadas em linha de comando e não têm front-end GUI, recursos de gerenciamento de projetos ou processo de compilação automatizado. O Sandcastle Help File Builder fornece GUI independente e ferramentas baseadas em linha de comando para criar um arquivo de ajuda de forma automatizada. Um pacote de integração do Visual Studio também está disponível para que os projetos de ajuda possam ser criados e gerenciados inteiramente de dentro do Visual Studio.
  • Doxygen: O Doxygen gera um navegador de documentação on-line (em HTML) ou um manual de referência offline (em LaTeX) a partir de um conjunto de arquivos de origem documentados. Há também suporte para geração de saída em páginas de manual RTF (MS Word), PostScript, PDF com hiperlink, HTML compactado, DocBook e Unix. Você pode configurar o Doxygen para extrair a estrutura de código de arquivos de origem não documentados.

Observação

Os comentários da documentação XML não são metadados. O compilador não os inclui na assembly compilada, por isso não são acessíveis por reflexão.

Cadeias de caracteres de ID

O compilador escreve cada tipo ou membro num elemento do ficheiro XML de saída. Cada elemento tem uma cadeia de identificação única que identifica o tipo ou membro. A string ID inclui informações sobre operadores, parâmetros, valores de retorno, parâmetros genéricos de tipo, ref, in, e out parâmetros. Para codificar todos esses elementos potenciais, o compilador segue regras claramente definidas para gerar as cadeias de caracteres de ID. Os programas que processam o arquivo XML usam a cadeia de caracteres de ID para identificar os metadados .NET correspondentes ou o item de reflexão ao qual a documentação se aplica.

O compilador segue estas regras ao gerar as strings ID:

  • A corda não contém espaço em branco.

  • A cadeia começa com um único carácter e dois pontos que identifica o tipo de membro. Use os seguintes tipos de membros:

    Personagem Tipo de membro Observações
    N espaço de nomes Você não pode adicionar comentários de documentação a um namespace, mas pode fazer cref referências a eles, quando suportado.
    T tipo Um tipo é uma classe, interface, struct, enum ou delegado.
    F campo
    P propriedade Inclui indexadores ou outras propriedades indexadas.
    M método Inclui métodos especiais, como construtores e operadores.
    E evento
    ! sequência de erro O restante da cadeia de caracteres fornece informações sobre o erro. O compilador C# gera informações de erro para links que não podem ser resolvidos.

  • A segunda parte da cadeia de caracteres é o nome totalmente qualificado do item, começando na raiz do namespace. O nome do item, os seus tipos anexos e o namespace estão separados por períodos. Se o nome do próprio item tiver pontos, o compilador substitui-os pelo sinal de hash ('#'). A gramática pressupõe que nenhum item tenha um sinal de hash diretamente em seu nome. Por exemplo, o nome totalmente qualificado do construtor String é "System.String.#ctor".

  • Para propriedades e métodos, segue-se a lista de parâmetros entre parênteses. Se não houver parâmetros, nenhum parêntesis estará presente. Os parâmetros são separados por vírgulas. A codificação de cada parâmetro segue diretamente como ele é codificado em uma assinatura .NET (Consulte Microsoft.VisualStudio.CorDebugInterop.CorElementType para obter definições dos elementos all caps na lista a seguir):

    • Tipos de base. Os tipos regulares (ELEMENT_TYPE_CLASS ou ELEMENT_TYPE_VALUETYPE) são representados como o nome totalmente qualificado do tipo.
    • Tipos intrínsecos, como ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF, e ELEMENT_TYPE_VOID, são representados como o nome totalmente qualificado do tipo completo correspondente. Por exemplo, System.Int32 ou System.TypedReference.
    • ELEMENT_TYPE_PTR é representado como um '*' após o tipo modificado.
    • ELEMENT_TYPE_BYREF é representado como um '@' após o tipo modificado.
    • ELEMENT_TYPE_CMOD_OPT é representado como um '!' e o nome totalmente qualificado da classe modificadora, seguindo o tipo modificado.
    • ELEMENT_TYPE_SZARRAY é representado como "[]" seguindo o tipo de elemento da matriz.
    • ELEMENT_TYPE_ARRAY é representado como [limite inferior:size,limite inferior:size] onde o número de vírgulas é a ordem - 1, e os limites inferiores e o tamanho de cada dimensão, se conhecidos, são representados em decimais. O limite inferior e o tamanho são omitidos se não forem especificados. Se o limite inferior e o tamanho de uma determinada dimensão forem omitidos, o ':' também será omitido. Por exemplo, uma matriz bidimensional com 1 como limites inferiores e tamanhos não especificados é [1:,1:].

  • Para operadores de conversão apenas (op_Implicit e op_Explicit), o valor de retorno do método é codificado como a ~ seguido pelo tipo de retorno. Por exemplo: <member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32"> é a tag para o operador public static explicit operator int (decimal value); cast declarada System.Decimal na classe.

  • Para tipos genéricos, o nome do tipo é seguido por um backtick e, em seguida, um número que indica o número de parâmetros de tipo genérico. Por exemplo: <member name="T:SampleClass`2"> é a tag para um tipo definido como public class SampleClass<T, U>. Para métodos que tomam tipos genéricos como parâmetros, os parâmetros de tipo genéricos são especificados como números precedidos de backticks (por exemplo, '0,'1). Cada número representa uma notação de matriz baseada em zero para os parâmetros genéricos do tipo.

    • ELEMENT_TYPE_PINNED é representado como um '^' após o tipo modificado. O compilador C# nunca gera essa codificação.
    • ELEMENT_TYPE_CMOD_REQ é representado como um '|' e o nome totalmente qualificado da classe modificadora, seguindo o tipo modificado. O compilador C# nunca gera essa codificação.
    • ELEMENT_TYPE_GENERICARRAY é representado como "[?]" seguindo o tipo de elemento da matriz. O compilador C# nunca gera essa codificação.
    • ELEMENT_TYPE_FNPTR é representado como "=FUNC:type(signature)", onde type é o tipo de retorno, e signature é os argumentos do método. Se não houver argumentos, os parênteses são omitidos. O compilador C# nunca gera essa codificação.
    • Os seguintes componentes de assinatura não são representados porque não são usados para diferenciar métodos sobrecarregados:
      • Convenção de Chamada
      • tipo de retorno
      • ELEMENT_TYPE_SENTINEL

Os exemplos seguintes mostram como o compilador gera as strings de ID para uma classe e os seus membros:

namespace MyNamespace;

/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:MyNamespace.MyClass".
/// </summary>
public unsafe class MyClass
{
    /// <summary>
    /// Enter description here for the first constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor".
    /// </summary>
    public MyClass() { }

    /// <summary>
    /// Enter description here for the second constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public MyClass(int i) { }

    /// <summary>
    /// Enter description here for field Message.
    /// ID string generated is "F:MyNamespace.MyClass.Message".
    /// </summary>
    public string? Message;

    /// <summary>
    /// Enter description for constant PI.
    /// ID string generated is "F:MyNamespace.MyClass.PI".
    /// </summary>
    public const double PI = 3.14;

    /// <summary>
    /// Enter description for method Func.
    /// ID string generated is "M:MyNamespace.MyClass.Func".
    /// </summary>
    /// <returns>Describe return value.</returns>
    public int Func() => 1;

    /// <summary>
    /// Enter description for method SomeMethod.
    /// ID string generated is "M:MyNamespace.MyClass.SomeMethod(System.String,System.Int32@,System.Void*)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <param name="num">Describe parameter.</param>
    /// <param name="ptr">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int SomeMethod(string str, ref int num, void* ptr) { return 1; }

    /// <summary>
    /// Enter description for method AnotherMethod.
    /// ID string generated is "M:MyNamespace.MyClass.AnotherMethod(System.Int16[],System.Int32[0:,0:])".
    /// </summary>
    /// <param name="array1">Describe parameter.</param>
    /// <param name="array">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int AnotherMethod(short[] array1, int[,] array) { return 0; }

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)".
    /// </summary>
    /// <param name="first">Describe parameter.</param>
    /// <param name="second">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static MyClass operator +(MyClass first, MyClass second) { return first; }

    /// <summary>
    /// Enter description for property.
    /// ID string generated is "P:MyNamespace.MyClass.Prop".
    /// </summary>
    public int Prop { get { return 1; } set { } }

    /// <summary>
    /// Enter description for event.
    /// ID string generated is "E:MyNamespace.MyClass.OnHappened".
    /// </summary>
    public event Del? OnHappened;

    /// <summary>
    /// Enter description for index.
    /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <returns></returns>
    public int this[string s] => 1;

    /// <summary>
    /// Enter description for class Nested.
    /// ID string generated is "T:MyNamespace.MyClass.Nested".
    /// </summary>
    public class Nested { }

    /// <summary>
    /// Enter description for delegate.
    /// ID string generated is "T:MyNamespace.MyClass.Del".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public delegate void Del(int i);

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32".
    /// </summary>
    /// <param name="myParameter">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static explicit operator int(MyClass myParameter) => 1;
}

Especificação da linguagem C#

Para obter mais informações, consulte o anexo Especificação da linguagem C# nos comentários da documentação.

  • Last updated on