Bagikan melalui

Pemrosesan file dokumentasi XML

  • Artikel

Pengkompilasi menghasilkan string ID untuk setiap konstruksi dalam kode Anda yang ditandai untuk menghasilkan dokumentasi. Untuk informasi selengkapnya, lihat Komentar dokumentasi tag yang direkomendasikan. String ID secara unik mengidentifikasi konstruksi. Program yang memproses file XML dapat menggunakan string ID untuk mengidentifikasi metadata .NET Framework atau item pantulan yang sesuai dengan yang diterapkan dokumentasi.

File XML bukan representasi hierarkis kode Anda, ini adalah daftar datar dengan ID yang dihasilkan untuk setiap elemen.

Pengkompilasi mengamati aturan berikut saat menghasilkan string ID:

  • Tidak ada spasi kosong dalam string.

  • Bagian pertama dari string ID mengidentifikasi jenis anggota yang diidentifikasi, dengan satu karakter yang diikuti oleh titik dua. Jenis anggota berikut digunakan:

    karakter Deskripsi
    N Ruang nama

    Anda tidak dapat menambahkan komentar dokumentasi ke namespace layanan, referensi cref ke namespace layanan dimungkinkan.
    T Jenis: kelas, antarmuka, struct, enum, delegasi
    D Typedef
    F Bidang
    P Properti (termasuk pengindeks atau properti terindeks lainnya)
    M Metode (termasuk metode khusus seperti konstruktor, operator, dan sebagainya)
    E Kejadian
    ! Kesalahan string

    String lainnya menyediakan informasi tentang kesalahan. Pengkompilasi MSVC menghasilkan informasi kesalahan untuk tautan yang tidak dapat diselesaikan.

  • Bagian kedua dari string adalah nama item yang sepenuhnya memenuhi syarat, dimulai dari akar namespace layanan. Nama item, jenis atau jenis yang diapit, dan namespace dipisahkan oleh titik. Jika nama item itu sendiri memiliki titik, item digantikan oleh tanda hash ('#'). Diasumsikan bahwa tidak ada item yang memiliki tanda hash langsung dalam namanya. Misalnya, nama konstruktor String yang sepenuhnya memenuhi syarat adalah System.String.#ctor.

  • Untuk properti dan metode, jika ada argumen ke metode, daftar argumen yang diapit dalam tanda kurung mengikuti. Jika tidak ada argumen, tidak ada tanda kurung. Argumen dipisahkan oleh koma. Setiap argumen dikodekan dengan cara yang sama seperti dikodekan dalam tanda tangan .NET Framework:

    • Jenis dasar. Jenis reguler (ELEMENT_TYPE_CLASS atau ELEMENT_TYPE_VALUETYPE) dinyatakan sebagai nama jenis yang sepenuhnya memenuhi syarat.

    • Jenis intrinsik (misalnya, , ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECTELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF, dan ELEMENT_TYPE_VOID) diwakili sebagai nama yang sepenuhnya memenuhi syarat dari jenis lengkap yang sesuai, misalnya, System.Int32 atau System.TypedReference.

    • ELEMENT_TYPE_PTR direpresentasikan sebagai '*' mengikuti jenis yang dimodifikasi.

    • ELEMENT_TYPE_BYREF direpresentasikan sebagai '@' mengikuti jenis yang dimodifikasi.

    • ELEMENT_TYPE_PINNED direpresentasikan sebagai '^' mengikuti jenis yang dimodifikasi. Pengkompilasi MSVC tidak pernah menghasilkan elemen ini.

    • ELEMENT_TYPE_CMOD_REQ direpresentasikan sebagai '|' dan nama kelas pengubah yang sepenuhnya memenuhi syarat, mengikuti jenis yang dimodifikasi. Pengkompilasi MSVC tidak pernah menghasilkan elemen ini.

    • ELEMENT_TYPE_CMOD_OPT direpresentasikan sebagai '!' dan nama kelas pengubah yang sepenuhnya memenuhi syarat, mengikuti jenis yang dimodifikasi.

    • ELEMENT_TYPE_SZARRAY direpresentasikan sebagai "[]" mengikuti jenis elemen array.

    • ELEMENT_TYPE_GENERICARRAY direpresentasikan sebagai "[?]" mengikuti jenis elemen array. Pengkompilasi MSVC tidak pernah menghasilkan elemen ini.

    • ELEMENT_TYPE_ARRAYdirepresentasikan sebagai [ukuran,terikat:yang lebih rendah dengan ukuran] batas:bawah di mana jumlah koma adalah peringkat - 1, dan batas dan ukuran yang lebih rendah dari setiap dimensi, jika diketahui, diwakili dalam desimal. Jika batas bawah atau ukuran tidak ditentukan, maka akan dihilangkan. Jika batas dan ukuran yang lebih rendah dihilangkan untuk dimensi tertentu, ':' juga dihilangkan. Misalnya, array 2 dimensi dengan 1 sebagai ukuran terikat bawah dan tidak ditentukan diwakili sebagai [1:,1:].

    • ELEMENT_TYPE_FNPTR dinyatakan sebagai "=FUNC:type(signature)", di mana type adalah jenis pengembalian, dan tanda tangan adalah argumen metode. Jika tidak ada argumen, tanda kurung akan dihilangkan. Pengkompilasi MSVC tidak pernah menghasilkan elemen ini.

    Komponen tanda tangan berikut tidak diwakili karena tidak pernah digunakan untuk membedakan metode yang kelebihan beban:

    • Konvensi panggilan

    • Tipe hasil

    • ELEMENT_TYPE_SENTINEL

  • Hanya untuk operator konversi, nilai pengembalian metode dikodekan sebagai '~' diikuti dengan jenis pengembalian, seperti yang dikodekan sebelumnya.

  • Untuk jenis generik, nama jenis akan diikuti oleh tanda centang belakang dan kemudian angka yang menunjukkan jumlah parameter jenis generik. Contohnya,

    <member name="T:MyClass`2">

    Contoh menunjukkan jenis yang didefinisikan sebagai public class MyClass<T, U>.

    Untuk metode yang mengambil jenis generik sebagai parameter, parameter jenis generik ditentukan sebagai angka yang diawali dengan tanda centang belakang (misalnya '0, '1). Setiap angka mewakili posisi array berbasis nol untuk parameter generik jenis.

Contoh

Contoh berikut menunjukkan bagaimana string ID untuk kelas dan anggotanya akan dihasilkan.

// 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"
   };
}

Lihat juga

Dokumentasi XML