Sdílet prostřednictvím

Zpracování souborů dokumentace XML

  • Článek

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 String by byl System.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_CLASS nebo ELEMENT_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, a ELEMENT_TYPE_VOID) jsou reprezentovány jako plně kvalifikovaný název odpovídajícího úplného typu, například System.Int32 nebo System.TypedReference.

    • ELEMENT_TYPE_PTR je reprezentována jako "*" za upraveným typem.

    • ELEMENT_TYPE_BYREF je reprezentována jako "@" za upraveným typem.

    • ELEMENT_TYPE_PINNED je reprezentována jako "^" za upraveným typem. Kompilátor MSVC nikdy negeneruje tento prvek.

    • ELEMENT_TYPE_CMOD_REQ je 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_OPT je reprezentován jako "!" a plně kvalifikovaný název modifikační třídy, za upraveným typem.

    • ELEMENT_TYPE_SZARRAY je reprezentován jako "[]" za typem prvku pole.

    • ELEMENT_TYPE_GENERICARRAY je 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_FNPTR je reprezentována jako "=FUNC:type(signature)", kde type je 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"
   };
}

Viz také

Dokumentace XML