Procesar el archivo XML (Guía de programación de C#)
Actualización: noviembre 2007
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 (namespace)
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
evento
!
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 correspondiente tipo completo. 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 un '!' 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 // "N:N"
{
///
///
public unsafe class X // "T:N.X"
{
public X(){}
//----------------------------
// The result of the above is:
// "M:N.X.#ctor"
/// <param name="i"></param>
public X(int i){}
//----------------------------
// The result of the above is:
// "M:N.X.#ctor(System.Int32)"
~X(){}
//----------------------------
// The result of the above is:
// "M:N.X.Finalize", destructor's representation in metadata
public string q;
//----------------------------
// The result of the above is:
// "F:N.X.q"
/// <returns></returns>
public const double PI = 3.14;
//----------------------------
// The result of the above is:
// "F:N.X.PI"
/// <param name="s"></param>
/// <param name="y"></param>
/// <param name="z"></param>
/// <returns></returns>
public int f(){return 1;}
//----------------------------
// The result of the above is:
// "M:N.X.f"
/// <param name="array1"></param>
/// <param name="array"></param>
/// <returns></returns>
public int bb(string s, ref int y, void * z){return 1;}
//----------------------------
// The result of the above is:
// "M:N.X.bb(System.String,System.Int32@,=System.Void*)"
/// <param name="x"></param>
/// <param name="xx"></param>
/// <returns></returns>
public int gg(short[] array1, int[,] array){return 0;}
//----------------------------
// The result of the above is:
// "M:N.X.gg(System.Int16[], System.Int32[0:,0:])"
public static X operator+(X x, X xx){return x;}
//----------------------------
// The result of the above is:
// "M:N.X.op_Addition(N.X,N.X)"
public int prop {get{return 1;} set{}}
//----------------------------
// The result of the above is:
// "P:N.X.prop"
public event D d;
//----------------------------
// The result of the above is:
// "E:N.X.d"
public int this[string s]{get{return 1;}}
//----------------------------
// The result of the above is:
// "P:N.X.Item(System.String)"
public class Nested{}
//----------------------------
// The result of the above is:
// "T:N.X.Nested"
public delegate void D(int i);
//----------------------------
// The result of the above is:
// "T:N.X.D"
/// <param name="x"></param>
/// <returns></returns>
public static explicit operator int(X x){return 1;}
//----------------------------
// The result of the above is:
// "M:N.X.op_Explicit(N.X)~System.Int32"
}
}
Vea también
Tareas
Conceptos
Referencia
/doc (Procesar comentarios de documentación) (Opciones del compilador de C#)
Comentarios de documentación XML (Guía de programación de C#)