Zpracování souborů dokumentace XML
Kompilátor vygeneruje řetězec ID pro každý konstruktor v kódu, který je označen k vygenerování dokumentace. Další informace najdete v tématu Doporučené komentáře k dokumentaci ke značkám. Řetězec ID jednoznačně identifikuje konstruktor. Programy, které zpracovávají soubor XML, mohou pomocí řetězce ID identifikovat odpovídající metadata rozhraní .NET Framework nebo položku reflexe, na kterou se dokumentace vztahuje.
Soubor XML není hierarchickou reprezentací kódu, jedná se o plochý seznam s vygenerovaným ID pro každý prvek.
Kompilátor při generování řetězců ID dodržuje následující pravidla:
V řetězci není žádné prázdné znaky.
První část řetězce ID identifikuje druh identifikovaného člena s jedním znakem následovaným dvojtečku. Používají se následující typy členů:
Znak Popis N Obor názvů
Do oboru názvů nemůžete přidávat komentáře dokumentace, odkazy cref na obor názvů jsou možné.T Typ: class, interface, struct, enum, delegate D Typedef F Pole P Vlastnost (včetně indexerů nebo jiných indexovaných vlastností) M Metoda (včetně takových speciálních metod, jako jsou konstruktory, operátory atd.) E Událost ! Text chyby
Zbytek řetězce poskytuje informace o chybě. Kompilátor MSVC generuje informace o chybě pro odkazy, které nelze vyřešit.Druhá část řetězce je plně kvalifikovaný název položky počínaje kořenem oboru názvů. Název položky, jeho uzavřený typ nebo typy a obor názvů jsou odděleny tečkami. Pokud název samotné položky obsahuje tečky, nahradí se znakem hash ('#'). Předpokládá se, že žádná položka nemá ve svém názvu přímo znak hash. Například plně kvalifikovaný název konstruktoru
Stringby bylSystem.String.#ctor.Pro vlastnosti a metody, pokud existují argumenty metody, seznam argumentů uzavřený v závorkách následuje. Pokud neexistují žádné argumenty, nejsou k dispozici žádné závorky. Argumenty jsou oddělené čárkami. Každý argument je kódován stejným způsobem jako kódovaný v podpisu rozhraní .NET Framework:
Základní typy. Běžné typy (
ELEMENT_TYPE_CLASSneboELEMENT_TYPE_VALUETYPE) jsou reprezentovány jako plně kvalifikovaný název typu.Vnitřní typy (například
ELEMENT_TYPE_I4, ,ELEMENT_TYPE_OBJECT,ELEMENT_TYPE_TYPEDBYREFELEMENT_TYPE_STRING, aELEMENT_TYPE_VOID) jsou reprezentovány jako plně kvalifikovaný název odpovídajícího úplného typu, napříkladSystem.Int32neboSystem.TypedReference.ELEMENT_TYPE_PTRje reprezentována jako "*" za upraveným typem.ELEMENT_TYPE_BYREFje reprezentována jako "@" za upraveným typem.ELEMENT_TYPE_PINNEDje reprezentována jako "^" za upraveným typem. Kompilátor MSVC nikdy negeneruje tento prvek.ELEMENT_TYPE_CMOD_REQje reprezentován jako "|" a plně kvalifikovaný název modifikační třídy, za upraveným typem. Kompilátor MSVC nikdy negeneruje tento prvek.ELEMENT_TYPE_CMOD_OPTje reprezentován jako "!" a plně kvalifikovaný název modifikační třídy, za upraveným typem.ELEMENT_TYPE_SZARRAYje reprezentován jako "[]" za typem prvku pole.ELEMENT_TYPE_GENERICARRAYje reprezentován jako "[?]" za typem prvku pole. Kompilátor MSVC nikdy negeneruje tento prvek.ELEMENT_TYPE_ARRAYje reprezentována jako[velikost dolní:,hranice dolní mez:], kde počet čárek je pořadí - 1 a dolní mez a velikost každé dimenze, pokud je znám, jsou reprezentovány v desítkové soustavě. Pokud není zadána dolní mez nebo velikost, je vynechána. Pokud je pro určitou dimenzi vynechána dolní mez a velikost, vynechá se také ":". Například 2rozměrné pole s 1 jako dolní mez a nezadané velikosti jsou reprezentovány jako[1:,1:].ELEMENT_TYPE_FNPTRje reprezentována jako "=FUNC:type(signature)", kdetypeje návratový typ a podpis je argumenty metody. Pokud neexistují žádné argumenty, vynechá se závorky. Kompilátor MSVC nikdy negeneruje tento prvek.
Následující komponenty podpisu nejsou reprezentovány, protože se nikdy nepoužívají k odliování přetížených metod:
Konvenci
Návratový typ
ELEMENT_TYPE_SENTINEL
Pouze pro převodní operátory je návratová hodnota metody zakódována jako "
~" následovaná návratovým typem, jak bylo dříve kódováno.U obecných typů bude název typu následovaný zpětným zaškrtnutím a číslem, které označuje počet parametrů obecného typu. Příklad:
<member name="T:MyClass`2">Příklad ukazuje typ, který je definován jako
public class MyClass<T, U>.U metod, které jako parametry přebírají obecné typy, jsou parametry obecného typu zadány jako čísla před zpětnými zaškrtnutími (například 0, 1). Každé číslo představuje pozici pole založené na nule pro obecné parametry typu.
Příklad
Následující příklady ukazují, jak se generují řetězce ID pro třídu a její členy.
// xml_id_strings.cpp
// compile with: /clr /doc /LD
///
namespace N {
// "N:N"
/// <see cref="System" />
// <see cref="N:System"/>
ref class X {
// "T:N.X"
protected:
///
!X(){}
// "M:N.X.Finalize", destructor's representation in metadata
public:
///
X() {}
// "M:N.X.#ctor"
///
static X() {}
// "M:N.X.#cctor"
///
X(int i) {}
// "M:N.X.#ctor(System.Int32)"
///
~X() {}
// "M:N.X.Dispose", Dispose function representation in metadata
///
System::String^ q;
// "F:N.X.q"
///
double PI;
// "F:N.X.PI"
///
int f() { return 1; }
// "M:N.X.f"
///
int bb(System::String ^ s, int % y, void * z) { return 1; }
// "M:N.X.bb(System.String,System.Int32@,System.Void*)"
///
int gg(array<short> ^ array1, array< int, 2 >^ IntArray) { return 0; }
// "M:N.X.gg(System.Int16[], System.Int32[0:,0:])"
///
static X^ operator+(X^ x, X^ xx) { return x; }
// "M:N.X.op_Addition(N.X,N.X)"
///
property int prop;
// "M:N.X.prop"
///
property int prop2 {
// "P:N.X.prop2"
///
int get() { return 0; }
// M:N.X.get_prop2
///
void set(int i) {}
// M:N.X.set_prop2(System.Int32)
}
///
delegate void D(int i);
// "T:N.X.D"
///
event D ^ d;
// "E:N.X.d"
///
ref class Nested {};
// "T:N.X.Nested"
///
static explicit operator System::Int32 (X x) { return 1; }
// "M:N.X.op_Explicit(N.X!System.Runtime.CompilerServices.IsByValue)~System.Int32"
};
}