Comentários de documentaçãoDocumentation comments

O C# fornece um mecanismo para os programadores documentarem seu código usando uma sintaxe de comentário especial que contém texto XML.C# provides a mechanism for programmers to document their code using a special comment syntax that contains XML text. Em arquivos de código-fonte, os comentários com um determinado formulário podem ser usados para direcionar uma ferramenta para produzir XML a partir desses comentários e dos elementos de código-fonte, que eles precedem.In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Os comentários que usam essa sintaxe são chamados *comentários da documentação _.Comments using such syntax are called *documentation comments _. Eles devem preceder imediatamente um tipo definido pelo usuário (como uma classe, um delegado ou uma interface) ou um membro (como um campo, evento, propriedade ou método).They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method). A ferramenta de geração de XML é chamada de gerador de documentação.The XML generation tool is called the documentation generator. (Esse gerador poderia ser, mas não precisa ser, o próprio compilador do C#.) A saída produzida pelo gerador de documentação é chamada de arquivo de documentação.(This generator could be, but need not be, the C# compiler itself.) The output produced by the documentation generator is called the documentation file. Um arquivo de documentação é usado como entrada para o _ Visualizador de documentação *; uma ferramenta destinada a produzir algum tipo de exibição visual de informações de tipo e sua documentação associada.A documentation file is used as input to a _*documentation viewer**; a tool intended to produce some sort of visual display of type information and its associated documentation.

Essa especificação sugere um conjunto de marcas a serem usadas em comentários de documentação, mas o uso dessas marcas não é necessário e outras marcas podem ser usadas, se desejado, desde que as regras de XML bem formadas sejam seguidas.This specification suggests a set of tags to be used in documentation comments, but use of these tags is not required, and other tags may be used if desired, as long the rules of well-formed XML are followed.

IntroduçãoIntroduction

Os comentários com um formulário especial podem ser usados para direcionar uma ferramenta para produzir XML a partir desses comentários e dos elementos de código-fonte, que eles precedem.Comments having a special form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Esses comentários são comentários de linha única que começam com três barras ( /// ) ou comentários delimitados que começam com uma barra e duas estrelas ( /** ).Such comments are single-line comments that start with three slashes (///), or delimited comments that start with a slash and two stars (/**). Eles devem preceder imediatamente um tipo definido pelo usuário (como uma classe, um delegado ou uma interface) ou um membro (como um campo, evento, propriedade ou método) que eles anotam.They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method) that they annotate. As seções de atributo (especificação de atributo) são consideradas parte das declarações; portanto, os comentários de documentação devem preceder os atributos aplicados a um tipo ou membro.Attribute sections (Attribute specification) are considered part of declarations, so documentation comments must precede attributes applied to a type or member.

Sintaxe:Syntax:

single_line_doc_comment
    : '///' input_character*
    ;

delimited_doc_comment
    : '/**' delimited_comment_section* asterisk+ '/'
    ;

Em uma single_line_doc_comment, se houver um caractere de espaço em branco após os /// caracteres em cada um dos single_line_doc_comment adjacentes ao single_line_doc_comment atual, esse caractere de espaço em branco não será incluído na saída XML.In a single_line_doc_comment, if there is a whitespace character following the /// characters on each of the single_line_doc_comment s adjacent to the current single_line_doc_comment, then that whitespace character is not included in the XML output.

Em um documento delimitado-doc-Comment, se o primeiro caractere que não seja espaço em branco na segunda linha for um asterisco e o mesmo padrão de caracteres de espaço em branco opcionais e um caractere asterisco for repetido no início de cada linha dentro do comentário delimitado-doc-Comment, os caracteres do padrão repetido não serão incluídos na saída XML.In a delimited-doc-comment, if the first non-whitespace character on the second line is an asterisk and the same pattern of optional whitespace characters and an asterisk character is repeated at the beginning of each of the line within the delimited-doc-comment, then the characters of the repeated pattern are not included in the XML output. O padrão pode incluir caracteres de espaço em branco após, bem como antes, o caractere de asterisco.The pattern may include whitespace characters after, as well as before, the asterisk character.

Exemplo:Example:

/// <summary>Class <c>Point</c> models a point in a two-dimensional
/// plane.</summary>
///
public class Point 
{
    /// <summary>method <c>draw</c> renders the point.</summary>
    void draw() {...}
}

O texto nos comentários da documentação deve estar bem formado de acordo com as regras de XML ( https://www.w3.org/TR/REC-xml) .The text within documentation comments must be well formed according to the rules of XML (https://www.w3.org/TR/REC-xml). Se o XML estiver mal formado, um aviso será gerado e o arquivo de documentação conterá um comentário dizendo que um erro foi encontrado.If the XML is ill formed, a warning is generated and the documentation file will contain a comment saying that an error was encountered.

Embora os desenvolvedores estejam livres para criar seu próprio conjunto de marcas, um conjunto recomendado é definido em marcas recomendadas.Although developers are free to create their own set of tags, a recommended set is defined in Recommended tags. Algumas das marcas recomendadas têm significado especial:Some of the recommended tags have special meanings:

  • A <param> marca é usada para descrever os parâmetros.The <param> tag is used to describe parameters. Se tal marca for usada, o gerador de documentação deverá verificar se o parâmetro especificado existe e se todos os parâmetros estão descritos nos comentários da documentação.If such a tag is used, the documentation generator must verify that the specified parameter exists and that all parameters are described in documentation comments. Se essa verificação falhar, o gerador de documentação emitirá um aviso.If such verification fails, the documentation generator issues a warning.
  • O atributo cref pode ser anexado a qualquer marca para fornecer uma referência a um elemento de código.The cref attribute can be attached to any tag to provide a reference to a code element. O gerador de documentação deve verificar se esse elemento de código existe.The documentation generator must verify that this code element exists. Se a verificação falhar, o gerador de documentação emitirá um aviso.If the verification fails, the documentation generator issues a warning. Ao procurar um nome descrito em um cref atributo, o gerador de documentação deve respeitar a visibilidade do namespace de acordo com using as instruções que aparecem no código-fonte.When looking for a name described in a cref attribute, the documentation generator must respect namespace visibility according to using statements appearing within the source code. Para elementos de código genéricos, a sintaxe genérica normal (ou seja, " List<T> ") não pode ser usada porque produz XML inválido.For code elements that are generic, the normal generic syntax (that is, "List<T>") cannot be used because it produces invalid XML. Chaves podem ser usadas em vez de colchetes (ou seja, " List{T} ") ou a sintaxe de escape XML pode ser usada (ou seja, " List&lt;T&gt; ").Braces can be used instead of brackets (that is, "List{T}"), or the XML escape syntax can be used (that is, "List&lt;T&gt;").
  • A <summary> marca destina-se a ser usada por um visualizador de documentação para exibir informações adicionais sobre um tipo ou membro.The <summary> tag is intended to be used by a documentation viewer to display additional information about a type or member.
  • A <include> marca inclui informações de um arquivo XML externo.The <include> tag includes information from an external XML file.

Observe atentamente que o arquivo de documentação não fornece informações completas sobre o tipo e os membros (por exemplo, ele não contém nenhuma informação de tipo).Note carefully that the documentation file does not provide full information about the type and members (for example, it does not contain any type information). Para obter informações sobre um tipo ou membro, o arquivo de documentação deve ser usado em conjunto com reflexão no tipo ou membro real.To get such information about a type or member, the documentation file must be used in conjunction with reflection on the actual type or member.

O gerador de documentação deve aceitar e processar qualquer marca que seja válida de acordo com as regras de XML.The documentation generator must accept and process any tag that is valid according to the rules of XML. As marcas a seguir fornecem funcionalidade comumente usada na documentação do usuário.The following tags provide commonly used functionality in user documentation. (É claro que outras marcas são possíveis.)(Of course, other tags are possible.)

TagTag SeçãoSection FinalidadePurpose
<c> <c> Definir texto em uma fonte do tipo códigoSet text in a code-like font
<code> <code> Definir uma ou mais linhas do código-fonte ou saída do programaSet one or more lines of source code or program output
<example> <example> Indicar um exemploIndicate an example
<exception> <exception> Identifica as exceções que um método pode gerarIdentifies the exceptions a method can throw
<include> <include> Inclui XML de um arquivo externoIncludes XML from an external file
<list> <list> Criar uma lista ou tabelaCreate a list or table
<para> <para> Permitir que a estrutura seja adicionada ao textoPermit structure to be added to text
<param> <param> Descrever um parâmetro para um método ou ConstrutorDescribe a parameter for a method or constructor
<paramref> <paramref> Identificar que uma palavra é um nome de parâmetroIdentify that a word is a parameter name
<permission> <permission> Documentar a acessibilidade de segurança de um membroDocument the security accessibility of a member
<remarks> <remarks> Descrever informações adicionais sobre um tipoDescribe additional information about a type
<returns> <returns> Descrever o valor de retorno de um métodoDescribe the return value of a method
<see> <see> Especificar um linkSpecify a link
<seealso> <seealso> Gerar uma entrada Consulte tambémGenerate a See Also entry
<summary> <summary> Descrever um tipo ou um membro de um tipoDescribe a type or a member of a type
<value> <value> Descrever uma propriedadeDescribe a property
<typeparam> Descrever um parâmetro de tipo genéricoDescribe a generic type parameter
<typeparamref> Identificar que uma palavra é um nome de parâmetro de tipoIdentify that a word is a type parameter name

<c>

Essa marca fornece um mecanismo para indicar que um fragmento de texto dentro de uma descrição deve ser definido em uma fonte especial, como a usada para um bloco de código.This tag provides a mechanism to indicate that a fragment of text within a description should be set in a special font such as that used for a block of code. Para linhas de código real, use <code> ( <code> ).For lines of actual code, use <code> (<code>).

Sintaxe:Syntax:

<c>text</c>

Exemplo:Example:

/// <summary>Class <c>Point</c> models a point in a two-dimensional
/// plane.</summary>

public class Point 
{
    // ...
}

<code>

Essa marca é usada para definir uma ou mais linhas de código-fonte ou saída do programa em alguma fonte especial.This tag is used to set one or more lines of source code or program output in some special font. Para fragmentos de código pequenos em narrativas, use <c> ( <c> ).For small code fragments in narrative, use <c> (<c>).

Sintaxe:Syntax:

<code>source code or program output</code>

Exemplo:Example:

/// <summary>This method changes the point's location by
///    the given x- and y-offsets.
/// <example>For example:
/// <code>
///    Point p = new Point(3,5);
///    p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>

public void Translate(int xor, int yor) {
    X += xor;
    Y += yor;
}   

<example>

Essa marca permite código de exemplo dentro de um comentário, para especificar como um método ou outro membro da biblioteca pode ser usado.This tag allows example code within a comment, to specify how a method or other library member may be used. Normalmente, isso também envolveria o uso da marca <code> ( <code> ).Ordinarily, this would also involve use of the tag <code> (<code>) as well.

Sintaxe:Syntax:

<example>description</example>

Exemplo:Example:

Consulte <code> ( <code> ) para obter um exemplo.See <code> (<code>) for an example.

<exception>

Essa marca fornece uma maneira de documentar as exceções que um método pode gerar.This tag provides a way to document the exceptions a method can throw.

Sintaxe:Syntax:

<exception cref="member">description</exception>

wherewhere

  • member é o nome de um membro.member is the name of a member. O gerador de documentação verifica se o membro fornecido existe e se traduz no member nome do elemento canônico no arquivo de documentação.The documentation generator checks that the given member exists and translates member to the canonical element name in the documentation file.
  • description é uma descrição das circunstâncias em que a exceção é lançada.description is a description of the circumstances in which the exception is thrown.

Exemplo:Example:

public class DataBaseOperations
{
    /// <exception cref="MasterFileFormatCorruptException"></exception>
    /// <exception cref="MasterFileLockedOpenException"></exception>
    public static void ReadRecord(int flag) {
        if (flag == 1)
            throw new MasterFileFormatCorruptException();
        else if (flag == 2)
            throw new MasterFileLockedOpenException();
        // ...
    } 
}

<include>

Essa marca permite incluir informações de um documento XML externo ao arquivo de código-fonte.This tag allows including information from an XML document that is external to the source code file. O arquivo externo deve ser um documento XML bem formado e uma expressão XPath é aplicada a esse documento para especificar o XML desse documento a ser incluído.The external file must be a well-formed XML document, and an XPath expression is applied to that document to specify what XML from that document to include. <include>Em seguida, a marca é substituída pelo XML selecionado do documento externo.The <include> tag is then replaced with the selected XML from the external document.

Sintaxe:Syntax:

<include file="filename" path="xpath" />

wherewhere

  • filename é o nome de arquivo de um arquivo XML externo.filename is the file name of an external XML file. O nome do arquivo é interpretado em relação ao arquivo que contém a marca include.The file name is interpreted relative to the file that contains the include tag.
  • xpath é uma expressão XPath que seleciona parte do XML no arquivo XML externo.xpath is an XPath expression that selects some of the XML in the external XML file.

Exemplo:Example:

Se o código-fonte contiver uma declaração como:If the source code contained a declaration like:

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { ... }

e o arquivo externo "docs.xml" tinha o seguinte conteúdo:and the external file "docs.xml" had the following contents:

<?xml version="1.0"?>
<extradoc>
  <class name="IntList">
     <summary>
        Contains a list of integers.
     </summary>
  </class>
  <class name="StringList">
     <summary>
        Contains a list of integers.
     </summary>
  </class>
</extradoc>

em seguida, a mesma documentação é saída como se o código-fonte contivesse:then the same documentation is output as if the source code contained:

/// <summary>
///    Contains a list of integers.
/// </summary>
public class IntList { ... }

<list>

Essa marca é usada para criar uma lista ou tabela de itens.This tag is used to create a list or table of items. Ele pode conter um <listheader> bloco para definir a linha de cabeçalho de uma tabela ou lista de definições.It may contain a <listheader> block to define the heading row of either a table or definition list. (Ao definir uma tabela, apenas uma entrada para term no cabeçalho precisa ser fornecida.)(When defining a table, only an entry for term in the heading need be supplied.)

Cada item na lista é especificado com um <item> bloco.Each item in the list is specified with an <item> block. Ao criar uma lista de definições, term e description deve ser especificado.When creating a definition list, both term and description must be specified. No entanto, para uma tabela, lista com marcadores ou lista numerada, só description é necessário especificar.However, for a table, bulleted list, or numbered list, only description need be specified.

Sintaxe:Syntax:

<list type="bullet" | "number" | "table">
   <listheader>
      <term>term</term>
      <description>*description*</description>
   </listheader>
   <item>
      <term>term</term>
      <description>*description*</description>
   </item>
    ...
   <item>
      <term>term</term>
      <description>description</description>
   </item>
</list>

wherewhere

  • term é o termo a ser definido, cuja definição está description .term is the term to define, whose definition is in description.
  • description é um item em uma lista com marcadores ou numerada ou a definição de um term .description is either an item in a bullet or numbered list, or the definition of a term.

Exemplo:Example:

public class MyClass
{
    /// <summary>Here is an example of a bulleted list:
    /// <list type="bullet">
    /// <item>
    /// <description>Item 1.</description>
    /// </item>
    /// <item>
    /// <description>Item 2.</description>
    /// </item>
    /// </list>
    /// </summary>
    public static void Main () {
        // ...
    }
}

<para>

Essa marca é para uso dentro de outras marcas, como <summary> ( <remarks> ) ou <returns> ( <returns> ), e permite que a estrutura seja adicionada ao texto.This tag is for use inside other tags, such as <summary> (<remarks>) or <returns> (<returns>), and permits structure to be added to text.

Sintaxe:Syntax:

<para>content</para>

em que content é o texto do parágrafo.where content is the text of the paragraph.

Exemplo:Example:

/// <summary>This is the entry point of the Point class testing program.
/// <para>This program tests each method and operator, and
/// is intended to be run after any non-trivial maintenance has
/// been performed on the Point class.</para></summary>
public static void Main() {
    // ...
}

<param>

Essa marca é usada para descrever um parâmetro para um método, Construtor ou indexador.This tag is used to describe a parameter for a method, constructor, or indexer.

Sintaxe:Syntax:

<param name="name">description</param>

wherewhere

  • name é o nome do parâmetro.name is the name of the parameter.
  • description é uma descrição do parâmetro.description is a description of the parameter.

Exemplo:Example:

/// <summary>This method changes the point's location to
///    the given coordinates.</summary>
/// <param name="xor">the new x-coordinate.</param>
/// <param name="yor">the new y-coordinate.</param>
public void Move(int xor, int yor) {
    X = xor;
    Y = yor;
}

<paramref>

Essa marca é usada para indicar que uma palavra é um parâmetro.This tag is used to indicate that a word is a parameter. O arquivo de documentação pode ser processado para formatar esse parâmetro de uma maneira distinta.The documentation file can be processed to format this parameter in some distinct way.

Sintaxe:Syntax:

<paramref name="name"/>

em que name é o nome do parâmetro.where name is the name of the parameter.

Exemplo:Example:

/// <summary>This constructor initializes the new Point to
///    (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
/// <param name="xor">the new Point's x-coordinate.</param>
/// <param name="yor">the new Point's y-coordinate.</param>

public Point(int xor, int yor) {
    X = xor;
    Y = yor;
}

<permission>

Essa marca permite que a acessibilidade de segurança de um membro seja documentada.This tag allows the security accessibility of a member to be documented.

Sintaxe:Syntax:

<permission cref="member">description</permission>

wherewhere

  • member é o nome de um membro.member is the name of a member. O gerador de documentação verifica se o elemento de código fornecido existe e traduz o membro para o nome do elemento canônico no arquivo de documentação.The documentation generator checks that the given code element exists and translates member to the canonical element name in the documentation file.
  • description é uma descrição do acesso ao membro.description is a description of the access to the member.

Exemplo:Example:

/// <permission cref="System.Security.PermissionSet">Everyone can
/// access this method.</permission>

public static void Test() {
    // ...
}

<remarks>

Essa marca é usada para especificar informações adicionais sobre um tipo.This tag is used to specify extra information about a type. (Use <summary> ( <summary> ) para descrever o próprio tipo e os membros de um tipo.)(Use <summary> (<summary>) to describe the type itself and the members of a type.)

Sintaxe:Syntax:

<remarks>description</remarks>

em que description é o texto do comentário.where description is the text of the remark.

Exemplo:Example:

/// <summary>Class <c>Point</c> models a point in a 
/// two-dimensional plane.</summary>
/// <remarks>Uses polar coordinates</remarks>
public class Point 
{
    // ...
}

<returns>

Essa marca é usada para descrever o valor de retorno de um método.This tag is used to describe the return value of a method.

Sintaxe:Syntax:

<returns>description</returns>

em que description é uma descrição do valor de retorno.where description is a description of the return value.

Exemplo:Example:

/// <summary>Report a point's location as a string.</summary>
/// <returns>A string representing a point's location, in the form (x,y),
///    without any leading, trailing, or embedded whitespace.</returns>
public override string ToString() {
    return "(" + X + "," + Y + ")";
}

<see>

Essa marca permite que um link seja especificado dentro do texto.This tag allows a link to be specified within text. Use <seealso> ( <seealso> ) para indicar o texto que deve aparecer em uma seção ver também.Use <seealso> (<seealso>) to indicate text that is to appear in a See Also section.

Sintaxe:Syntax:

<see cref="member"/>

em que member é o nome de um membro.where member is the name of a member. O gerador de documentação verifica se o elemento de código fornecido existe e altera o membro para o nome do elemento no arquivo de documentação gerado.The documentation generator checks that the given code element exists and changes member to the element name in the generated documentation file.

Exemplo:Example:

/// <summary>This method changes the point's location to
///    the given coordinates.</summary>
/// <see cref="Translate"/>
public void Move(int xor, int yor) {
    X = xor;
    Y = yor;
}

/// <summary>This method changes the point's location by
///    the given x- and y-offsets.
/// </summary>
/// <see cref="Move"/>
public void Translate(int xor, int yor) {
    X += xor;
    Y += yor;
}

<seealso>

Essa marca permite que uma entrada seja gerada para a seção Consulte também.This tag allows an entry to be generated for the See Also section. Use <see> ( <see> ) para especificar um link de dentro do texto.Use <see> (<see>) to specify a link from within text.

Sintaxe:Syntax:

<seealso cref="member"/>

em que member é o nome de um membro.where member is the name of a member. O gerador de documentação verifica se o elemento de código fornecido existe e altera o membro para o nome do elemento no arquivo de documentação gerado.The documentation generator checks that the given code element exists and changes member to the element name in the generated documentation file.

Exemplo:Example:

/// <summary>This method determines whether two Points have the same
///    location.</summary>
/// <seealso cref="operator=="/>
/// <seealso cref="operator!="/>
public override bool Equals(object o) {
    // ...
}

<summary>

Essa marca pode ser usada para descrever um tipo ou um membro de um tipo. Use <remarks> ( <remarks> ) para descrever o próprio tipo.Use <remarks> (<remarks>) to describe the type itself.

Sintaxe:Syntax:

<summary>description</summary>

em que description é um resumo do tipo ou membro.where description is a summary of the type or member.

Exemplo:Example:

/// <summary>This constructor initializes the new Point to (0,0).</summary>
public Point() : this(0,0) {
}

<value>

Essa marca permite que uma propriedade seja descrita.This tag allows a property to be described.

Sintaxe:Syntax:

<value>property description</value>

em que property description é uma descrição para a propriedade.where property description is a description for the property.

Exemplo:Example:

/// <value>Property <c>X</c> represents the point's x-coordinate.</value>
public int X
{
    get { return x; }
    set { x = value; }
}

<typeparam>

Essa marca é usada para descrever um parâmetro de tipo genérico para uma classe, struct, interface, delegado ou método.This tag is used to describe a generic type parameter for a class, struct, interface, delegate, or method.

Sintaxe:Syntax:

<typeparam name="name">description</typeparam>

em que name é o nome do parâmetro de tipo e description é sua descrição.where name is the name of the type parameter, and description is its description.

Exemplo:Example:

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T> {
    ...
}

<typeparamref>

Essa marca é usada para indicar que uma palavra é um parâmetro de tipo.This tag is used to indicate that a word is a type parameter. O arquivo de documentação pode ser processado para formatar esse parâmetro de tipo de alguma maneira distinta.The documentation file can be processed to format this type parameter in some distinct way.

Sintaxe:Syntax:

<typeparamref name="name"/>

em que name é o nome do parâmetro de tipo.where name is the name of the type parameter.

Exemplo:Example:

/// <summary>This method fetches data and returns a list of <typeparamref name="T"/>.</summary>
/// <param name="query">query to execute</param>
public List<T> FetchData<T>(string query) {
    ...
}

Processando o arquivo de documentaçãoProcessing the documentation file

O gerador de documentação gera uma cadeia de caracteres de ID para cada elemento no código-fonte que é marcado com um comentário de documentação.The documentation generator generates an ID string for each element in the source code that is tagged with a documentation comment. Essa cadeia de caracteres de ID identifica exclusivamente um elemento de origem.This ID string uniquely identifies a source element. Um visualizador de documentação pode usar uma cadeia de caracteres de ID para identificar o item de metadados/reflexão correspondente ao qual a documentação se aplica.A documentation viewer can use an ID string to identify the corresponding metadata/reflection item to which the documentation applies.

O arquivo de documentação não é uma representação hierárquica do código-fonte; em vez disso, é uma lista simples com uma cadeia de caracteres de ID gerada para cada elemento.The documentation file is not a hierarchical representation of the source code; rather, it is a flat list with a generated ID string for each element.

Formato da cadeia de caracteres de IDID string format

O gerador de documentação observa as seguintes regras ao gerar as cadeias de caracteres de ID:The documentation generator observes the following rules when it generates the ID strings:

  • Nenhum espaço em branco é colocado na cadeia de caracteres.No white space is placed in the string.

  • A primeira parte da cadeia de caracteres identifica o tipo de membro que está sendo documentado, por meio de um único caractere seguido por dois-pontos.The first part of the string identifies the kind of member being documented, via a single character followed by a colon. Os seguintes tipos de membros são definidos:The following kinds of members are defined:

    CaractereCharacter DescriçãoDescription
    EE EventoEvent
    FF CampoField
    MM Método (incluindo construtores, destruidores e operadores)Method (including constructors, destructors, and operators)
    NN NamespaceNamespace
    PP Propriedade (incluindo indexadores)Property (including indexers)
    TT Tipo (como classe, delegado, enumeração, interface e struct)Type (such as class, delegate, enum, interface, and struct)
    !! Cadeia de caracteres de erro; o restante da cadeia de caracteres fornece informações sobre o erro.Error string; the rest of the string provides information about the error. Por exemplo, o gerador de documentação gera informações de erro para links que não podem ser resolvidos.For example, the documentation generator generates error information for links that cannot be resolved.
  • A segunda parte da cadeia de caracteres é o nome totalmente qualificado do elemento, começando na raiz do namespace.The second part of the string is the fully qualified name of the element, starting at the root of the namespace. O nome do elemento, seus tipos de delimitador e o namespace são separados por pontos.The name of the element, its enclosing type(s), and namespace are separated by periods. Se o nome do próprio item tiver pontos, eles serão substituídos por #(U+0023) caracteres.If the name of the item itself has periods, they are replaced by #(U+0023) characters. (Supõe-se que nenhum elemento tenha esse caractere em seu nome.)(It is assumed that no element has this character in its name.)

  • Para métodos e propriedades com argumentos, a lista de argumentos segue, entre parênteses.For methods and properties with arguments, the argument list follows, enclosed in parentheses. Para aqueles sem argumentos, os parênteses são omitidos.For those without arguments, the parentheses are omitted. Os argumentos são separados por vírgulas.The arguments are separated by commas. A codificação de cada argumento é a mesma que uma assinatura da CLI, da seguinte maneira:The encoding of each argument is the same as a CLI signature, as follows:

    • Os argumentos são representados pelo nome da documentação, que se baseia em seu nome totalmente qualificado, modificado da seguinte maneira:Arguments are represented by their documentation name, which is based on their fully qualified name, modified as follows:
      • Os argumentos que representam tipos genéricos têm um ` caractere anexado (de marca de seleção) seguido pelo número de parâmetros de tipoArguments that represent generic types have an appended ` (backtick) character followed by the number of type parameters
      • Os argumentos que out ref têm o modificador ou têm um @ nome de tipo a seguir.Arguments having the out or ref modifier have an @ following their type name. Os argumentos passados por valor ou via params não têm notação especial.Arguments passed by value or via params have no special notation.
      • Os argumentos que são matrizes são representados como [lowerbound:size, ... , lowerbound:size] onde o número de vírgulas é a classificação menos uma, e os limites inferiores e o tamanho de cada dimensão, se conhecido, são representados em decimal.Arguments that are arrays are represented as [lowerbound:size, ... , lowerbound:size] where the number of commas is the rank less one, and the lower bounds and size of each dimension, if known, are represented in decimal. Se um limite inferior ou tamanho não for especificado, ele será omitido.If a lower bound or size is not specified, it is omitted. Se o limite inferior e o tamanho de uma determinada dimensão forem omitidos, o : também será omitido.If the lower bound and size for a particular dimension are omitted, the : is omitted as well. As matrizes denteadas são representadas por um [] por nível.Jagged arrays are represented by one [] per level.
      • Os argumentos que têm tipos de ponteiro diferentes de void são representados usando * o nome do tipo a seguir.Arguments that have pointer types other than void are represented using a * following the type name. Um ponteiro void é representado usando um nome de tipo de System.Void .A void pointer is represented using a type name of System.Void.
      • Os argumentos que se referem a parâmetros de tipo genérico definidos em tipos são codificados usando o ` caractere (backtick) seguido pelo índice de base zero do parâmetro de tipo.Arguments that refer to generic type parameters defined on types are encoded using the ` (backtick) character followed by the zero-based index of the type parameter.
      • Os argumentos que usam parâmetros de tipo genérico definidos em métodos usam uma marca de seleção dupla `` em vez de ` usados para tipos.Arguments that use generic type parameters defined in methods use a double-backtick `` instead of the ` used for types.
      • Os argumentos que se referem a tipos genéricos construídos são codificados usando o tipo genérico, seguido por { , seguido por uma lista separada por vírgulas de argumentos de tipo, seguida por } .Arguments that refer to constructed generic types are encoded using the generic type, followed by {, followed by a comma-separated list of type arguments, followed by }.

Exemplos de cadeia de caracteres de IDID string examples

Os exemplos a seguir mostram um fragmento do código C#, juntamente com a cadeia de caracteres de ID produzida de cada elemento de origem capaz de ter um comentário de documentação:The following examples each show a fragment of C# code, along with the ID string produced from each source element capable of having a documentation comment:

  • Os tipos são representados usando seu nome totalmente qualificado, aumentados com informações genéricas:Types are represented using their fully qualified name, augmented with generic information:

    enum Color { Red, Blue, Green }
    
    namespace Acme
    {
        interface IProcess {...}
    
        struct ValueType {...}
    
        class Widget: IProcess
        {
            public class NestedClass {...}
            public interface IMenuItem {...}
            public delegate void Del(int i);
            public enum Direction { North, South, East, West }
        }
    
        class MyList<T>
        {
            class Helper<U,V> {...}
        }
    }
    
    "T:Color"
    "T:Acme.IProcess"
    "T:Acme.ValueType"
    "T:Acme.Widget"
    "T:Acme.Widget.NestedClass"
    "T:Acme.Widget.IMenuItem"
    "T:Acme.Widget.Del"
    "T:Acme.Widget.Direction"
    "T:Acme.MyList`1"
    "T:Acme.MyList`1.Helper`2"
    
  • Os campos são representados pelo nome totalmente qualificado:Fields are represented by their fully qualified name:

    namespace Acme
    {
        struct ValueType
        {
            private int total;
        }
    
        class Widget: IProcess
        {
            public class NestedClass
            {
                private int value;
            }
    
            private string message;
            private static Color defaultColor;
            private const double PI = 3.14159;
            protected readonly double monthlyAverage;
            private long[] array1;
            private Widget[,] array2;
            private unsafe int *pCount;
            private unsafe float **ppValues;
        }
    }
    
    "F:Acme.ValueType.total"
    "F:Acme.Widget.NestedClass.value"
    "F:Acme.Widget.message"
    "F:Acme.Widget.defaultColor"
    "F:Acme.Widget.PI"
    "F:Acme.Widget.monthlyAverage"
    "F:Acme.Widget.array1"
    "F:Acme.Widget.array2"
    "F:Acme.Widget.pCount"
    "F:Acme.Widget.ppValues"
    
  • Construtores.Constructors.

    namespace Acme
    {
        class Widget: IProcess
        {
            static Widget() {...}
            public Widget() {...}
            public Widget(string s) {...}
        }
    }
    
    "M:Acme.Widget.#cctor"
    "M:Acme.Widget.#ctor"
    "M:Acme.Widget.#ctor(System.String)"
    
  • Destruidores.Destructors.

    namespace Acme
    {
        class Widget: IProcess
        {
            ~Widget() {...}
        }
    }
    
    "M:Acme.Widget.Finalize"
    
  • Maneiras.Methods.

    namespace Acme
    {
        struct ValueType
        {
            public void M(int i) {...}
        }
    
        class Widget: IProcess
        {
            public class NestedClass
            {
                public void M(int i) {...}
            }
    
            public static void M0() {...}
            public void M1(char c, out float f, ref ValueType v) {...}
            public void M2(short[] x1, int[,] x2, long[][] x3) {...}
            public void M3(long[][] x3, Widget[][,,] x4) {...}
            public unsafe void M4(char *pc, Color **pf) {...}
            public unsafe void M5(void *pv, double *[][,] pd) {...}
            public void M6(int i, params object[] args) {...}
        }
    
        class MyList<T>
        {
            public void Test(T t) { }
        }
    
        class UseList
        {
            public void Process(MyList<int> list) { }
            public MyList<T> GetValues<T>(T inputValue) { return null; }
        }
    }
    
    "M:Acme.ValueType.M(System.Int32)"
    "M:Acme.Widget.NestedClass.M(System.Int32)"
    "M:Acme.Widget.M0"
    "M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@)"
    "M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
    "M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
    "M:Acme.Widget.M4(System.Char*,Color**)"
    "M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
    "M:Acme.Widget.M6(System.Int32,System.Object[])"
    "M:Acme.MyList`1.Test(`0)"
    "M:Acme.UseList.Process(Acme.MyList{System.Int32})"
    "M:Acme.UseList.GetValues``(``0)"
    
  • Propriedades e indexadores.Properties and indexers.

    namespace Acme
    {
        class Widget: IProcess
        {
            public int Width { get {...} set {...} }
            public int this[int i] { get {...} set {...} }
            public int this[string s, int i] { get {...} set {...} }
        }
    }
    
    "P:Acme.Widget.Width"
    "P:Acme.Widget.Item(System.Int32)"
    "P:Acme.Widget.Item(System.String,System.Int32)"
    
  • Eventos.Events.

    namespace Acme
    {
        class Widget: IProcess
        {
            public event Del AnEvent;
        }
    }
    
    "E:Acme.Widget.AnEvent"
    
  • Operadores unários.Unary operators.

    namespace Acme
    {
        class Widget: IProcess
        {
            public static Widget operator+(Widget x) {...}
        }
    }
    
    "M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
    

    O conjunto completo de nomes de funções de operador unários usado é o seguinte:,,,,, op_UnaryPlus op_UnaryNegation op_LogicalNot op_OnesComplement op_Increment op_Decrement , op_True e op_False .The complete set of unary operator function names used is as follows: op_UnaryPlus, op_UnaryNegation, op_LogicalNot, op_OnesComplement, op_Increment, op_Decrement, op_True, and op_False.

  • Operadores binários.Binary operators.

    namespace Acme
    {
        class Widget: IProcess
        {
            public static Widget operator+(Widget x1, Widget x2) {...}
        }
    }
    
    "M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"
    

    O conjunto completo de nomes de funções de operador binários usado é o seguinte:,,, op_Addition op_Subtraction ,, op_Multiply op_Division op_Modulus op_BitwiseAnd , op_BitwiseOr , op_ExclusiveOr , op_LeftShift , op_RightShift , op_Equality , op_Inequality , op_LessThan , op_LessThanOrEqual , op_GreaterThan e op_GreaterThanOrEqual .The complete set of binary operator function names used is as follows: op_Addition, op_Subtraction, op_Multiply, op_Division, op_Modulus, op_BitwiseAnd, op_BitwiseOr, op_ExclusiveOr, op_LeftShift, op_RightShift, op_Equality, op_Inequality, op_LessThan, op_LessThanOrEqual, op_GreaterThan, and op_GreaterThanOrEqual.

  • Os operadores de conversão têm um " ~ " à direita seguido pelo tipo de retorno.Conversion operators have a trailing "~" followed by the return type.

    namespace Acme
    {
        class Widget: IProcess
        {
            public static explicit operator int(Widget x) {...}
            public static implicit operator long(Widget x) {...}
        }
    }
    
    "M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
    "M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"
    

Um exemploAn example

Código-fonte C#C# source code

O exemplo a seguir mostra o código-fonte de uma Point classe:The following example shows the source code of a Point class:

namespace Graphics
{

/// <summary>Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point 
{

    /// <summary>Instance variable <c>x</c> represents the point's
    ///    x-coordinate.</summary>
    private int x;

    /// <summary>Instance variable <c>y</c> represents the point's
    ///    y-coordinate.</summary>
    private int y;

    /// <value>Property <c>X</c> represents the point's x-coordinate.</value>
    public int X
    {
        get { return x; }
        set { x = value; }
    }

    /// <value>Property <c>Y</c> represents the point's y-coordinate.</value>
    public int Y
    {
        get { return y; }
        set { y = value; }
    }

    /// <summary>This constructor initializes the new Point to
    ///    (0,0).</summary>
    public Point() : this(0,0) {}

    /// <summary>This constructor initializes the new Point to
    ///    (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
    /// <param><c>xor</c> is the new Point's x-coordinate.</param>
    /// <param><c>yor</c> is the new Point's y-coordinate.</param>
    public Point(int xor, int yor) {
        X = xor;
        Y = yor;
    }

    /// <summary>This method changes the point's location to
    ///    the given coordinates.</summary>
    /// <param><c>xor</c> is the new x-coordinate.</param>
    /// <param><c>yor</c> is the new y-coordinate.</param>
    /// <see cref="Translate"/>
    public void Move(int xor, int yor) {
        X = xor;
        Y = yor;
    }

    /// <summary>This method changes the point's location by
    ///    the given x- and y-offsets.
    /// <example>For example:
    /// <code>
    ///    Point p = new Point(3,5);
    ///    p.Translate(-1,3);
    /// </code>
    /// results in <c>p</c>'s having the value (2,8).
    /// </example>
    /// </summary>
    /// <param><c>xor</c> is the relative x-offset.</param>
    /// <param><c>yor</c> is the relative y-offset.</param>
    /// <see cref="Move"/>
    public void Translate(int xor, int yor) {
        X += xor;
        Y += yor;
    }

    /// <summary>This method determines whether two Points have the same
    ///    location.</summary>
    /// <param><c>o</c> is the object to be compared to the current object.
    /// </param>
    /// <returns>True if the Points have the same location and they have
    ///    the exact same type; otherwise, false.</returns>
    /// <seealso cref="operator=="/>
    /// <seealso cref="operator!="/>
    public override bool Equals(object o) {
        if (o == null) {
            return false;
        }

        if (this == o) {
            return true;
        }

        if (GetType() == o.GetType()) {
            Point p = (Point)o;
            return (X == p.X) && (Y == p.Y);
        }
        return false;
    }

    /// <summary>Report a point's location as a string.</summary>
    /// <returns>A string representing a point's location, in the form (x,y),
    ///    without any leading, training, or embedded whitespace.</returns>
    public override string ToString() {
        return "(" + X + "," + Y + ")";
    }

    /// <summary>This operator determines whether two Points have the same
    ///    location.</summary>
    /// <param><c>p1</c> is the first Point to be compared.</param>
    /// <param><c>p2</c> is the second Point to be compared.</param>
    /// <returns>True if the Points have the same location and they have
    ///    the exact same type; otherwise, false.</returns>
    /// <seealso cref="Equals"/>
    /// <seealso cref="operator!="/>
    public static bool operator==(Point p1, Point p2) {
        if ((object)p1 == null || (object)p2 == null) {
            return false;
        }

        if (p1.GetType() == p2.GetType()) {
            return (p1.X == p2.X) && (p1.Y == p2.Y);
        }

        return false;
    }

    /// <summary>This operator determines whether two Points have the same
    ///    location.</summary>
    /// <param><c>p1</c> is the first Point to be compared.</param>
    /// <param><c>p2</c> is the second Point to be compared.</param>
    /// <returns>True if the Points do not have the same location and the
    ///    exact same type; otherwise, false.</returns>
    /// <seealso cref="Equals"/>
    /// <seealso cref="operator=="/>
    public static bool operator!=(Point p1, Point p2) {
        return !(p1 == p2);
    }

    /// <summary>This is the entry point of the Point class testing
    /// program.
    /// <para>This program tests each method and operator, and
    /// is intended to be run after any non-trivial maintenance has
    /// been performed on the Point class.</para></summary>
    public static void Main() {
        // class test code goes here
    }
}
}

XML resultanteResulting XML

Aqui está a saída produzida por um gerador de documentação quando é fornecido o código-fonte para a classe Point , mostrado acima:Here is the output produced by one documentation generator when given the source code for class Point, shown above:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Point</name>
    </assembly>
    <members>
        <member name="T:Graphics.Point">
            <summary>Class <c>Point</c> models a point in a two-dimensional
            plane.
            </summary>
        </member>

        <member name="F:Graphics.Point.x">
            <summary>Instance variable <c>x</c> represents the point's
            x-coordinate.</summary>
        </member>

        <member name="F:Graphics.Point.y">
            <summary>Instance variable <c>y</c> represents the point's
            y-coordinate.</summary>
        </member>

        <member name="M:Graphics.Point.#ctor">
            <summary>This constructor initializes the new Point to
        (0,0).</summary>
        </member>

        <member name="M:Graphics.Point.#ctor(System.Int32,System.Int32)">
            <summary>This constructor initializes the new Point to
            (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
            <param><c>xor</c> is the new Point's x-coordinate.</param>
            <param><c>yor</c> is the new Point's y-coordinate.</param>
        </member>

        <member name="M:Graphics.Point.Move(System.Int32,System.Int32)">
            <summary>This method changes the point's location to
            the given coordinates.</summary>
            <param><c>xor</c> is the new x-coordinate.</param>
            <param><c>yor</c> is the new y-coordinate.</param>
            <see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
        </member>

        <member
            name="M:Graphics.Point.Translate(System.Int32,System.Int32)">
            <summary>This method changes the point's location by
            the given x- and y-offsets.
            <example>For example:
            <code>
            Point p = new Point(3,5);
            p.Translate(-1,3);
            </code>
            results in <c>p</c>'s having the value (2,8).
            </example>
            </summary>
            <param><c>xor</c> is the relative x-offset.</param>
            <param><c>yor</c> is the relative y-offset.</param>
            <see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
        </member>

        <member name="M:Graphics.Point.Equals(System.Object)">
            <summary>This method determines whether two Points have the same
            location.</summary>
            <param><c>o</c> is the object to be compared to the current
            object.
            </param>
            <returns>True if the Points have the same location and they have
            the exact same type; otherwise, false.</returns>
            <seealso
      cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
            <seealso
      cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
        </member>

        <member name="M:Graphics.Point.ToString">
            <summary>Report a point's location as a string.</summary>
            <returns>A string representing a point's location, in the form
            (x,y),
            without any leading, training, or embedded whitespace.</returns>
        </member>

        <member
       name="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)">
            <summary>This operator determines whether two Points have the
            same
            location.</summary>
            <param><c>p1</c> is the first Point to be compared.</param>
            <param><c>p2</c> is the second Point to be compared.</param>
            <returns>True if the Points have the same location and they have
            the exact same type; otherwise, false.</returns>
            <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
            <seealso
     cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
        </member>

        <member
      name="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)">
            <summary>This operator determines whether two Points have the
            same
            location.</summary>
            <param><c>p1</c> is the first Point to be compared.</param>
            <param><c>p2</c> is the second Point to be compared.</param>
            <returns>True if the Points do not have the same location and
            the
            exact same type; otherwise, false.</returns>
            <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
            <seealso
      cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
        </member>

        <member name="M:Graphics.Point.Main">
            <summary>This is the entry point of the Point class testing
            program.
            <para>This program tests each method and operator, and
            is intended to be run after any non-trivial maintenance has
            been performed on the Point class.</para></summary>
        </member>

        <member name="P:Graphics.Point.X">
            <value>Property <c>X</c> represents the point's
            x-coordinate.</value>
        </member>

        <member name="P:Graphics.Point.Y">
            <value>Property <c>Y</c> represents the point's
            y-coordinate.</value>
        </member>
    </members>
</doc>