Procesar el archivo XML (Guía de programación de C#)
El compilador genera una cadena id. por cada construcción del código marcada para generar documentación. (Para obtener información sobre cómo etiquetar el código, vea Etiquetas recomendadas para comentarios de documentación). La cadena id. identifica de forma exclusiva cada construcción. Los programas que procesan el archivo XML pueden utilizar la cadena id. para identificar el correspondiente elemento de metadatos/reflexión de .NET Framework al que se aplica la documentación.
El archivo XML no es una representación jerárquica del código, es una lista plana que tiene un identificador generado para cada elemento.
El compilador cumple las siguientes reglas cuando genera las cadenas id.:
No hay ningún espacio en blanco en la cadena.
La primera parte de la cadena id. identifica el tipo de miembro por medio de un único carácter seguido de dos puntos. Se utilizan los siguientes tipos de miembros:
Carácter
Descripción
N
Espacio de nombres
No se pueden agregar comentarios de documentación a un espacio de nombres, pero se pueden hacer referencias cref a ellos donde se admitan.
T
tipo: class, interface, struct, enum, delegate
F
campo
P
propiedad (incluidos indizadores u otras propiedades indizadas)
M
método (incluidos métodos especiales como constructores, operadores, etc.)
E
event
!
cadena de error
El resto de la cadena proporciona información acerca del error. El compilador de C# genera información de error para vínculos que no se pueden resolver.
La segunda parte de la cadena es el nombre completo del elemento, empezando en la raíz del espacio de nombres. El nombre del elemento, los tipos contenedores y el espacio de nombres se separan mediante puntos. Si el propio nombre del elemento contiene puntos, éstos se reemplazan por el signo #. Se supone que ningún elemento contiene un signo # directamente en su nombre. Por ejemplo, el nombre completo del constructor de String sería "System.String.#ctor".
Para propiedades y métodos, si existen argumentos para el método, la lista de argumentos que se encuentra entre paréntesis aparece a continuación. Si no existen argumentos, no se escribe ningún paréntesis. Los argumentos se separan por comas. La codificación de cada argumento indica directamente cómo se codifica en una firma de .NET Framework:
Tipos base. Los tipos normales (ELEMENT_TYPE_CLASS o ELEMENT_TYPE_VALUETYPE) se representan como el nombre completo del tipo.
Tipos intrínsecos (por ejemplo, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. y ELEMENT_TYPE_VOID) se representan como el nombre completo del tipo completo correspondiente. Por ejemplo, System.Int32 o System.TypedReference.
ELEMENT_TYPE_PTR se representa con un '*' a continuación del tipo modificado.
ELEMENT_TYPE_BYREF se representa con un signo '@' a continuación del tipo modificado.
ELEMENT_TYPE_PINNED se representa con un signo '^' a continuación del tipo modificado. El compilador de C# nunca genera este resultado.
ELEMENT_TYPE_CMOD_REQ se representa como una '|' y el nombre completo de la clase modificadora, a continuación del tipo modificado. El compilador de C# nunca genera este resultado.
ELEMENT_TYPE_CMOD_OPT se representa como '!' y el nombre completo de la clase modificadora, a continuación del tipo modificado.
ELEMENT_TYPE_SZARRAY se representa como "[]" a continuación del tipo de elemento de la matriz.
ELEMENT_TYPE_GENERICARRAY se representa como "[?]" a continuación del tipo de elemento de la matriz. El compilador de C# nunca genera este resultado.
ELEMENT_TYPE_ARRAY se representa como [límite inferior:size,límite inferior:size] donde el número de comas es el rango, 1, y los límites inferiores y el tamaño de cada dimensión, si se conocen, se representan en decimal. Si no se especifica un límite inferior ni un tamaño, simplemente se omite. Si el límite inferior y el tamaño de una dimensión particular se omiten, el signo ':' también se omite. Por ejemplo, una matriz de dos dimensiones con 1 como límites inferiores y sin tamaños especificados se representa como [1:,1:].
ELEMENT_TYPE_FNPTR se representa como "=FUNC:type (firma)", donde type es el tipo de valor devuelto y firma corresponde a los argumentos del método. Si no existen argumentos, los paréntesis se omiten. El compilador de C# nunca genera este resultado.
Los siguientes componentes de una firma no se representan porque nunca se utilizan para diferenciar métodos sobrecargados:
convención de llamadas
tipo de valor devuelto
ELEMENT_TYPE_SENTINEL
Sólo para operadores de conversión (op_Implicit y op_Explicit), el valor devuelto del método se codifica como un signo '~' seguido del tipo de valor devuelto.
En los tipos genéricos, el nombre del tipo va seguido de un acento invertido y de un número que indica el número de parámetros de tipo genérico. Por ejemplo,
<member name="T:SampleClass`2"> es la etiqueta para un tipo definido como public class SampleClass<T, U>.
Para métodos que toman tipos genéricos como parámetros, los parámetros de tipo genérico se especifican como números con un acento invertido antepuesto (por ejemplo `0, `1). Cada número representa una notación de matrices basada en cero en los parámetros genéricos del tipo.
Ejemplos
Los siguientes ejemplos muestran cómo se generarían las cadenas de id. para una clase y sus miembros:
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; }
}
}
Vea también
Referencia
/doc (Opciones del compilador de C#)
Comentarios de documentación XML (Guía de programación de C#)