Bagikan melalui

Hasilkan komentar dokumentasi XML API

File sumber C# dapat menyertakan komentar terstruktur yang menghasilkan dokumentasi API untuk jenis yang ditentukan dalam file-file tersebut. Pengkompilasi C# menghasilkan file XML yang berisi data terstruktur yang mewakili komentar dan tanda tangan API. Alat lain dapat memproses output XML tersebut untuk membuat dokumentasi yang dapat dibaca manusia dalam bentuk halaman web atau file PDF, misalnya.

Proses ini memberikan banyak keuntungan bagi Anda untuk menambahkan dokumentasi API dalam kode Anda:

  • Pengompilasi C# menggabungkan struktur kode C# dengan teks komentar ke dalam satu dokumen XML.
  • Pengkompilasi C# memverifikasi bahwa komentar cocok dengan tanda tangan API untuk tag yang relevan.
  • Alat yang memproses file dokumentasi XML dapat menentukan elemen dan atribut XML khusus untuk alat tersebut.

Alat seperti Visual Studio menyediakan IntelliSense untuk banyak elemen XML umum yang digunakan dalam komentar dokumentasi.

Artikel ini membahas topik-topik ini:

  • Komentar dokumentasi dan pembuatan file XML
  • Tag yang divalidasi oleh pengkompilasi C# dan Visual Studio
  • Format file XML yang dihasilkan

Membuat output dokumentasi XML

Anda membuat dokumentasi untuk kode Anda dengan menulis bidang komentar khusus yang ditandai oleh tiga garis miring. Bidang komentar menyertakan elemen XML yang menjelaskan blok kode yang mengikuti komentar. Contohnya:

/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass { }

Anda mengatur opsi GenerateDocumentationFile atau DocumentationFile , dan pengkompilasi menemukan semua bidang komentar dengan tag XML dalam kode sumber dan membuat file dokumentasi XML dari komentar tersebut. Ketika opsi ini diaktifkan, pengkompilasi menghasilkan peringatan CS1591 untuk setiap anggota yang terlihat publik yang dideklarasikan dalam proyek Anda tanpa komentar dokumentasi XML.

Format komentar XML

Penggunaan komentar dokumen XML memerlukan pemisah yang menunjukkan di mana komentar dokumentasi dimulai dan berakhir. Anda menggunakan pemisah berikut dengan tag dokumentasi XML:

  • /// Pemisah baris tunggal: Contoh dokumentasi dan templat proyek C# menggunakan formulir ini. Jika spasi kosong mengikuti pemisah, spasi tidak disertakan dalam output XML.

    Nota

    Visual Studio secara otomatis menyisipkan <summary> tag dan </summary> dan memposisikan kursor Anda dalam tag ini setelah Anda mengetik pemisah /// di editor kode. Anda dapat mengaktifkan atau menonaktifkan fitur ini dalam kotak dialog Opsi.

  • /** */ Pemisah multibaris: Pemisah /** */ memiliki aturan pemformatan berikut:

    • Pada baris yang berisi pemisah /** , jika sisa baris adalah spasi kosong, baris tidak diproses untuk komentar. Jika karakter pertama setelah pemisah /** adalah spasi kosong, karakter spasi putih tersebut diabaikan dan sisa garis diproses. Jika tidak, seluruh teks baris setelah pemisah /** diproses sebagai bagian dari komentar.

    • Pada baris yang berisi pemisah */ , jika hanya ada ruang kosong hingga pemisah */ , garis tersebut diabaikan. Jika tidak, teks pada baris sampai pemisah */ diproses sebagai bagian dari komentar.

    • Untuk garis setelah baris yang dimulai dengan pemisah /** , pengkompilasi mencari pola umum di awal setiap baris. Pola dapat terdiri dari spasi putih opsional dan/atau tanda bintang (*), diikuti dengan spasi kosong yang lebih opsional. Jika kompilator menemukan pola umum di awal setiap baris yang tidak dimulai dengan pembatas /** atau diakhiri dengan pembatas */, maka kompilator akan mengabaikan pola tersebut pada setiap baris.

    • Satu-satunya bagian dari komentar berikut yang diproses adalah baris yang dimulai dengan <summary>. Tiga format tag menghasilkan komentar yang sama.

      /** <summary>text</summary> */

/**
<summary>text</summary>
*/

/**
* <summary>text</summary>
*/

    • Pengkompilasi mengidentifikasi pola umum " * " di awal baris kedua dan ketiga. Pola tidak disertakan dalam output.

      /**
* <summary>
* text </summary>*/

    • Pengkompilasi tidak menemukan pola umum dalam komentar berikut karena karakter kedua pada baris ketiga bukan tanda bintang. Semua teks pada baris kedua dan ketiga diproses sebagai bagian dari komentar.

      /**
* <summary>
   text </summary>
*/

    • Pengkompilasi tidak menemukan pola dalam komentar berikut karena dua alasan. Pertama, jumlah spasi sebelum tanda bintang tidak konsisten. Kedua, baris kelima dimulai dengan tab, yang tidak selaras dengan spasi. Semua teks dari baris dua hingga lima diproses sebagai bagian dari komentar.

      /**
  * <summary>
  * text
*  text2
 	*  </summary>
*/

Untuk merujuk ke elemen XML (misalnya, fungsi Anda memproses elemen XML tertentu yang ingin Anda jelaskan dalam komentar dokumentasi XML), Anda dapat menggunakan mekanisme kutipan standar (&lt; dan &gt;). Untuk merujuk ke pengidentifikasi generik dalam elemen referensi kode (cref), Anda dapat menggunakan karakter escape (misalnya, cref="List&lt;T&gt;") atau kurung kurawal (cref="List{T}"). Sebagai kasus khusus, kompiler mengartikan kurung kurawal sebagai tanda kurung sudut untuk mempermudah penulis membuat komentar dokumentasi saat merujuk pada pengidentifikasi generik.

Nota

Jika Anda menulis komentar menggunakan pemisah komentar XML baris tunggal, ///, tetapi tidak menyertakan tag apa pun, pengkompilasi menambahkan teks komentar tersebut ke file output XML. Namun, output tidak menyertakan elemen XML seperti <summary>. Sebagian besar alat yang menggunakan komentar XML (termasuk Visual Studio IntelliSense) tidak membaca komentar ini.

Alat yang menerima input dokumentasi XML

Alat berikut membuat output dari komentar XML:

  • DocFX: DocFX adalah generator dokumentasi API untuk .NET, yang saat ini mendukung C#, Visual Basic, dan F#. Ini juga memungkinkan Anda untuk menyesuaikan dokumentasi referensi yang dihasilkan. DocFX membangun situs web HTML statis dari kode sumber dan file Markdown Anda. Selain itu, DocFX memberi Anda fleksibilitas untuk menyesuaikan tata letak dan gaya situs web Anda melalui templat. Anda juga dapat membuat templat kustom.
  • Sandcastle: Alat Sandcastle membuat file bantuan untuk pustaka kelas terkelola yang berisi halaman referensi konseptual dan API. Alat Sandcastle berbasis baris perintah dan tidak memiliki front-end GUI, fitur manajemen proyek, atau proses build otomatis. Sandcastle Help File Builder menyediakan GUI mandiri dan alat berbasis baris perintah untuk membangun file bantuan secara otomatis. Paket integrasi Visual Studio juga tersedia untuknya sehingga proyek bantuan dapat dibuat dan dikelola sepenuhnya dari dalam Visual Studio.
  • Doxygen: Doxygen menghasilkan browser dokumentasi online (dalam HTML) atau manual referensi offline (di LaTeX) dari sekumpulan file sumber yang didokumentasikan. Ada juga dukungan untuk menghasilkan output di halaman manual RTF (MS Word), PostScript, PDF hyperlink, HTML terkompresi, DocBook, dan Unix. Anda dapat mengonfigurasi Doxygen untuk mengekstrak struktur kode dari file sumber yang tidak terdokumentasi.

Nota

Komentar dokumentasi XML bukan metadata; mereka tidak disertakan dalam rakitan yang dikompilasi dan oleh karena itu mereka tidak dapat diakses melalui pantulan.

Rangkaian ID

Setiap jenis atau anggota disimpan dalam elemen dalam file XML output. Masing-masing elemen tersebut memiliki string ID unik yang mengidentifikasi jenis atau anggota. String ID harus memperhitungkan operator, parameter, nilai pengembalian, parameter jenis generik, ref, in, dan out parameter. Untuk mengodekan semua elemen potensial tersebut, pengkompilasi mengikuti aturan yang ditentukan dengan jelas untuk menghasilkan string ID. Program yang memproses file XML menggunakan string ID untuk mengidentifikasi metadata .NET atau item pantulan yang sesuai dengan yang diterapkan dokumentasi.

Pengkompilasi mengamati aturan berikut saat menghasilkan string ID:

  • Tidak ada spasi kosong dalam string.

  • Bagian pertama dari string mengidentifikasi jenis anggota menggunakan satu karakter diikuti oleh titik dua. Jenis anggota berikut digunakan:

    Karakter Jenis anggota Catatan
    N ruang nama Anda tidak dapat menambahkan komentar dokumentasi ke namespace, tetapi Anda dapat membuat referensi cref ke namespace tersebut, jika didukung.
    T tipe Jenisnya adalah kelas, antarmuka, struktur, enum, atau delegasi.
    F lapangan
    P harta benda Termasuk pengindeks atau properti terindeks lainnya.
    M Metode Termasuk metode khusus, seperti konstruktor dan operator.
    E peristiwa
    ! string kesalahan String lainnya menyediakan informasi tentang kesalahan. Pengkompilasi C# menghasilkan informasi kesalahan untuk tautan yang tidak dapat diselesaikan.

  • Bagian kedua dari string adalah nama item yang sepenuhnya memenuhi syarat, dimulai dari akar namespace. Nama item, jenis lampirannya, dan namespace dipisahkan oleh titik. Jika nama item itu sendiri memiliki titik, maka titik-titik tersebut akan diganti dengan tanda hash ('#'). Tata bahasa mengasumsikan bahwa tidak ada item yang memiliki tanda hash langsung atas namanya. Misalnya, nama konstruktor String yang sepenuhnya memenuhi syarat adalah "System.String.#ctor".

  • Untuk properti dan metode, daftar parameter yang diapit dalam tanda kurung mengikuti. Jika tidak ada parameter, tidak ada tanda kurung yang ada. Parameter dipisahkan oleh koma. Pengodean setiap parameter mengikuti langsung cara parameter dikodekan dalam signature .NET (Lihat Microsoft.VisualStudio.CorDebugInterop.CorElementType untuk definisi elemen berhuruf kapital dalam daftar berikut):

    • Jenis dasar. Jenis reguler (ELEMENT_TYPE_CLASS atau ELEMENT_TYPE_VALUETYPE) direpresentasikan sebagai nama jenis yang sepenuhnya memenuhi syarat.
    • Jenis intrinsik (misalnya, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF, dan ELEMENT_TYPE_VOID) diwakili sebagai nama yang memenuhi syarat sepenuhnya dari jenis lengkap yang sesuai. Misalnya, System.Int32 atau System.TypedReference.
    • ELEMENT_TYPE_PTR direpresentasikan sebagai '*' setelah jenis yang dimodifikasi.
    • ELEMENT_TYPE_BYREF direpresentasikan sebagai '@' setelah tipe yang dimodifikasi.
    • ELEMENT_TYPE_CMOD_OPT direpresentasikan sebagai '!' serta nama lengkap kelas pengubah yang sepenuhnya memenuhi syarat, mengikuti jenis yang dimodifikasi.
    • ELEMENT_TYPE_SZARRAY direpresentasikan sebagai "[]" mengikuti jenis elemen array.
    • ELEMENT_TYPE_ARRAY dinyatakan sebagai [batas bawah:size,batas bawah:size] di mana jumlah koma adalah peringkat - 1, dan batas dan ukuran yang lebih rendah dari setiap dimensi, jika diketahui, diwakili dalam desimal. Batas dan ukuran yang lebih rendah dihilangkan jika tidak ditentukan. Jika batas dan ukuran yang lebih rendah untuk dimensi tertentu dihilangkan, ':' juga dihilangkan. Misalnya, array dua dimensi dengan 1 sebagai batas bawah dan ukuran yang tidak ditentukan adalah [1:,1:].

  • Untuk operator konversi saja (op_Implicit dan op_Explicit), nilai pengembalian metode dikodekan sebagai ~ diikuti oleh jenis pengembalian. Misalnya: <member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32"> adalah tag untuk operator cast public static explicit operator int (decimal value); yang dideklarasikan di kelas System.Decimal.

  • Untuk jenis generik, nama jenis diikuti oleh backtick lalu angka yang menunjukkan jumlah parameter jenis generik. Misalnya: <member name="T:SampleClass`2"> adalah tag untuk jenis yang didefinisikan sebagai public class SampleClass<T, U>. Untuk metode yang menggunakan jenis generik sebagai parameter, parameter jenis generik ditentukan sebagai angka yang diawali dengan backtick (misalnya `0,`1). Setiap angka mewakili notasi array berbasis nol untuk jenis parameter generik.

    • ELEMENT_TYPE_PINNED direpresentasikan sebagai '^' setelah tipe yang dimodifikasi. Pengkompilasi C# tidak pernah menghasilkan pengodean ini.
    • ELEMENT_TYPE_CMOD_REQ direpresentasikan sebagai '|' dan nama lengkap kelas pengubah yang memenuhi syarat, mengikuti tipe yang dimodifikasi. Pengkompilasi C# tidak pernah menghasilkan pengodean ini.
    • ELEMENT_TYPE_GENERICARRAY direpresentasikan sebagai "[?]" mengikuti jenis elemen array. Pengkompilasi C# tidak pernah menghasilkan pengodean ini.
    • ELEMENT_TYPE_FNPTR direpresentasikan sebagai "=FUNC:type(signature)", di mana type adalah jenis pengembalian, dan tanda tangan adalah argumen metode . Jika tidak ada argumen, tanda kurung dihilangkan. Pengkompilasi C# tidak pernah menghasilkan pengodean ini.
    • Komponen tanda tangan berikut tidak diwakili karena tidak digunakan untuk membedakan metode yang kelebihan beban:
      • konvensi panggilan
      • jenis pengembalian
      • ELEMENT_TYPE_SENTINEL

Contoh berikut menunjukkan bagaimana string ID untuk kelas dan anggotanya dihasilkan:

namespace MyNamespace;

/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:MyNamespace.MyClass".
/// </summary>
public unsafe class MyClass
{
    /// <summary>
    /// Enter description here for the first constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor".
    /// </summary>
    public MyClass() { }

    /// <summary>
    /// Enter description here for the second constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public MyClass(int i) { }

    /// <summary>
    /// Enter description here for field Message.
    /// ID string generated is "F:MyNamespace.MyClass.Message".
    /// </summary>
    public string? Message;

    /// <summary>
    /// Enter description for constant PI.
    /// ID string generated is "F:MyNamespace.MyClass.PI".
    /// </summary>
    public const double PI = 3.14;

    /// <summary>
    /// Enter description for method Func.
    /// ID string generated is "M:MyNamespace.MyClass.Func".
    /// </summary>
    /// <returns>Describe return value.</returns>
    public int Func() => 1;

    /// <summary>
    /// Enter description for method SomeMethod.
    /// ID string generated is "M:MyNamespace.MyClass.SomeMethod(System.String,System.Int32@,System.Void*)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <param name="num">Describe parameter.</param>
    /// <param name="ptr">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int SomeMethod(string str, ref int num, void* ptr) { return 1; }

    /// <summary>
    /// Enter description for method AnotherMethod.
    /// ID string generated is "M:MyNamespace.MyClass.AnotherMethod(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 AnotherMethod(short[] array1, int[,] array) { return 0; }

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)".
    /// </summary>
    /// <param name="first">Describe parameter.</param>
    /// <param name="second">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static MyClass operator +(MyClass first, MyClass second) { return first; }

    /// <summary>
    /// Enter description for property.
    /// ID string generated is "P:MyNamespace.MyClass.Prop".
    /// </summary>
    public int Prop { get { return 1; } set { } }

    /// <summary>
    /// Enter description for event.
    /// ID string generated is "E:MyNamespace.MyClass.OnHappened".
    /// </summary>
    public event Del? OnHappened;

    /// <summary>
    /// Enter description for index.
    /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <returns></returns>
    public int this[string s] => 1;

    /// <summary>
    /// Enter description for class Nested.
    /// ID string generated is "T:MyNamespace.MyClass.Nested".
    /// </summary>
    public class Nested { }

    /// <summary>
    /// Enter description for delegate.
    /// ID string generated is "T:MyNamespace.MyClass.Del".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public delegate void Del(int i);

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32".
    /// </summary>
    /// <param name="myParameter">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static explicit operator int(MyClass myParameter) => 1;
}

Spesifikasi bahasa C#

Untuk informasi selengkapnya, lihat lampiran Spesifikasi Bahasa C# pada komentar dokumentasi.