Processando o arquivo XML (Guia de Programação em 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 que está 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 da documentação a um namespace, mas você pode fazer cref referências a elas, quando houver suporte.
T
tipo: classe, interface, struct, enum, delegado
F
campo
P
propriedade (incluindo os 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 hash-sinal ('#'). Presume-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 "[]" seguindo o tipo de elemento da matriz.
ELEMENT_TYPE_GENERICARRAY é representado como "?" após o tipo de elemento da matriz. 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 o tamanho de cada dimensão, se conhecido, são representados no formato 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 ':' for 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 do tipo de retorno, como codificado acima.
Para tipos genéricos, o nome do tipo será ser seguido por uma escala de back 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 marca para um tipo que é definido como public class SampleClass<T, U>.
Para tirar os tipos genéricos como parâmetros de métodos, os parâmetros de tipo genérico são especificados como números precedidos de tiques traseiro (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 seguintes exemplos 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ções do compilador C#)
Comentários de documentação XML (Guia de Programação em C#)