Compartilhar via


Processamento XML Arquivo (guia de programação C#)

O compilador gera uma sequência de identificação para cada constructo no seu código que está marcado para gerar a documentação. (Para obter informações sobre como marcar seu código, consulte Recomendado marcas de comentários de documentação.) A sequência de caracteres ID identifica exclusivamente o constructo. Programas que processam o arquivo XML podem usar a seqüência de caracteres de identificação para identificar o correspondente.Item de metadados/reflexão do NET Framework que se aplica a documentação.

O arquivo XML não é uma representação hierárquica de seu código; é uma lista simples que tenha uma identificação gerada para cada elemento.

O compilador observa as regras a seguir quando ele gera as sequências de identificação:

  • Não há espaço em branco é a seqüência de caracteres.

  • A primeira parte da seqüência de caracteres ID identifica o tipo de membro sendo identificado por meio de um único caractere, seguido de dois pontos. Os seguintes tipos de membro são usados:

    Caracterer

    Descrição

    N

    namespace

    Não é possível adicionar comentários de documentação a um namespace, mas você pode fazer referências de cref a elas, com suporte.

    T

    tipo: classe, interface, struct, enum, delegado

    F

    campo

    P

    propriedade (incluindo indexadores ou outras propriedades indexadas)

    M

    método (incluindo tais métodos especiais como construtores, operadores e assim por diante)

    E

    Evento

    !

    sequência de caracteres de erro

    O restante da sequência 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 seqüência de caracteres é o nome totalmente qualificado do item, iniciando na raiz do namespace. O nome do item, seu tipo (s) delimitador e o espaço para nome são separadas por pontos. Se o nome do item propriamente dito tiver períodos, eles são substituídos pelo sinal hash ('#'). Supõe-se que nenhum item tem um sinal de hash diretamente em seu nome. Por exemplo, o nome totalmente qualificado do construtor String seria "System.String.#ctor".

  • Para propriedades e métodos, se houver argumentos para o método, a lista de argumentos colocados entre parênteses segue. Se não houver nenhum argumento, nenhum parêntese estará presente Os argumentos são separados por vírgulas. A codificação de cada argumento segue diretamente como ele é codificado em um.Assinatura do NET Framework:

    • Tipos base. Tipos de regulares (ELEMENT_TYPE_CLASS ou ELEMENT_TYPE_VALUETYPE) são representados como o nome totalmente qualificado do tipo.

    • Tipos intrínsecos (por exemplo, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. e ELEMENT_TYPE_VOID) são representadas como o nome totalmente qualificado do tipo completo correspondente. Por exemplo, Int32 ou System.TypedReference.

    • ELEMENT_TYPE_PTR é representado como um ' *' seguindo o tipo modificado.

    • ELEMENT_TYPE_BYREF é representado como uma '@' seguindo o tipo modificado.

    • ELEMENT_TYPE_PINNED é representado como uma ' ^' seguindo o tipo modificado. O compilador C# nunca gera isso.

    • ELEMENT_TYPE_CMOD_REQ é representado como uma ' |' e o nome totalmente qualificado da classe modificador, seguindo o tipo modificado. O compilador C# nunca gera isso.

    • ELEMENT_TYPE_CMOD_OPT é representado como uma '!' e o nome totalmente qualificado da classe modificador, seguindo o tipo modificado.

    • ELEMENT_TYPE_SZARRAY é representado como "[]" o tipo de elemento da matriz a seguir.

    • ELEMENT_TYPE_GENERICARRAY é representado como "?" o tipo de elemento da matriz a seguir. O compilador C# nunca gera isso.

    • ELEMENT_TYPE_ARRAY é representado como lowerbound:size,lowerbound:size] onde o número de vírgulas é o posto - 1, e os limites inferiores e um tamanho de cada dimensão, se for conhecido, são representados em decimal. Se um limite inferior ou o tamanho não for especificado, ele simplesmente é omitido. Se o limite inferior e o tamanho de uma determinada dimensão forem omitidos, o ':' é omitido bem. Por exemplo, uma matriz bidimensional com 1 como os limites inferiores e tamanhos não especificados é [1:, 1:].

    • ELEMENT_TYPE_FNPTR é representado como "= FUNC:type(assinatura)", onde type é o tipo de retorno, e assinatura é os argumentos do método. Se não houver nenhum argumento, os parênteses são omitidos. O compilador C# nunca gera isso.

    Os seguintes componentes de assinatura não são representados, porque nunca são usadas para diferenciação métodos sobrecarregados:

    • convenção de chamada

    • tipo de retorno

    • ELEMENT_TYPE_SENTINEL

  • Para conversão operadores somente (op_Implicit e op_Explicit), o valor de retorno do método é codificado como um ' ~' seguido o tipo de retorno, como codificado acima.

  • Para tipos genéricos, o nome do tipo será ser seguido por uma escala de back e um número que indica o número de parâmetros de tipo genérico. Por exemplo,

    <member name="T:SampleClass`2">é a marca para um tipo que é definido como public class SampleClass<T, U>.

    Para tirar tipos genéricos como parâmetros de métodos, os parâmetros de tipo genérico são especificados como números antecedidos pelo back tiques (por exemplo, ' 0,'1). Cada número que representa uma notação de matriz baseada em zero para os parâmetros genéricos do tipo.

Exemplos

Os exemplos a seguir mostram como a identificação de seqüências de caracteres para uma classe e seus membros seriam gerados:

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


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


        /// <summary>
        /// Enter description here for field q.
        /// ID string generated is "F:N.X.q".
        /// </summary>
        public string q;


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


        /// <summary>
        /// Enter description for method f.
        /// ID string generated is "M:N.X.f".
        /// </summary>
        /// <returns>Describe return value.</returns>
        public int f() { return 1; }


        /// <summary>
        /// Enter description for method bb.
        /// ID string generated is "M:N.X.bb(System.String,System.Int32@,System.Void*)".
        /// </summary>
        /// <param name="s">Describe parameter.</param>
        /// <param name="y">Describe parameter.</param>
        /// <param name="z">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public int bb(string s, ref int y, void* z) { return 1; }


        /// <summary>
        /// Enter description for method gg.
        /// ID string generated is "M:N.X.gg(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 gg(short[] array1, int[,] array) { return 0; }


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


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


        /// <summary>
        /// Enter description for event.
        /// ID string generated is "E:N.X.d".
        /// </summary>
        public event D d;


        /// <summary>
        /// Enter description for property.
        /// ID string generated is "P:N.X.Item(System.String)".
        /// </summary>
        /// <param name="s">Describe parameter.</param>
        /// <returns></returns>
        public int this[string s] { get { return 1; } }


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


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


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

    }
}

Consulte também

Referência

/doc ( Opçõesdo compilador TRANSLATION FROM VPE FOR CSHARP)

XML Documentation Comments (C# Programming Guide)

Conceitos

C# Programming Guide