Share via

Tag XML yang direkomendasikan untuk komentar dokumentasi C#

  • Artikel

Komentar dokumentasi C# menggunakan elemen XML untuk menentukan struktur dokumentasi output. Salah satu konsekuensi dari fitur ini adalah Anda dapat menambahkan XML apa pun yang valid dalam komentar dokumentasi Anda. Kompilator C# menyalin elemen-elemen ini ke dalam file XML output. Meskipun Anda dapat menggunakan XML apa pun yang valid dalam komentar Anda (termasuk elemen HTML apa pun yang valid), pendokumentasian kode direkomendasikan karena berbagai alasan.

Berikut ini adalah beberapa rekomendasi, skenario kasus penggunaan umum, dan hal-hal yang harus Anda ketahui saat menggunakan tag dokumentasi XML dalam kode C# Anda. Meskipun Anda dapat memasukkan tag apa pun ke dalam komentar dokumentasi Anda, artikel ini menjelaskan tag yang direkomendasikan untuk konstruksi bahasa yang paling umum. Dalam semua kasus, Anda harus mematuhi rekomendasi ini:

  • Demi konsistensi, semua jenis yang terlihat secara publik dan anggota publiknya harus didokumentasikan.
  • Anggota privat juga dapat didokumentasikan menggunakan komentar XML. Namun, ini mengekspos cara kerja bagian dalam (berpotensi rahasia) pustaka Anda.
  • Minimal, jenis dan anggotanya harus memiliki <summary> tag.
  • Teks dokumentasi harus ditulis dengan menggunakan kalimat lengkap yang diakhiri dengan titik.
  • Kelas parsial didukung sepenuhnya, dan informasi dokumentasi akan digabungkan menjadi satu entri untuk setiap jenis.

Dokumentasi XML dimulai dengan ///. Saat Anda membuat proyek baru, template memasukkan beberapa baris /// permulaan untuk Anda. Pemrosesan komentar ini memiliki beberapa batasan:

  • Dokumentasi harus berupa XML terbentuk. Jika XML tidak terbentuk, kompilator menghasilkan peringatan. File dokumentasi akan berisi komentar yang mengatakan bahwa terjadi kesalahan.
  • Beberapa tag yang direkomendasikan memiliki arti khusus:
    • Tag <param> digunakan untuk menjelaskan parameter. Jika digunakan, kompilator memverifikasi bahwa parameter ada dan semua parameter dijelaskan dalam dokumentasi. Jika verifikasi gagal, kompilator mengeluarkan peringatan.
    • Atribut cref dapat dilampirkan ke tag apa pun untuk mereferensikan elemen kode. Kompilator memverifikasi bahwa elemen kode ini ada. Jika verifikasi gagal, kompilator mengeluarkan peringatan. Kompilator mematuhi setiap pernyataan using saat mencari jenis yang dijelaskan dalam atribut cref.
    • Tag <summary> digunakan oleh IntelliSense di dalam Visual Studio untuk menampilkan informasi tambahan tentang jenis atau anggota.

      Catatan

      File XML tidak memberikan informasi lengkap tentang jenis dan anggota (misalnya, tidak berisi informasi jenis apa pun). Untuk mendapatkan informasi lengkap tentang jenis atau anggota, gunakan file dokumentasi beserta refleksi pada jenis atau anggota yang sebenarnya.

  • Pengembang bebas membuat kumpulan tag mereka sendiri. Kompilator akan menyalinnya ke file output.

Beberapa tag yang direkomendasikan dapat digunakan pada elemen bahasa apa pun. Lainnya memiliki penggunaan yang lebih khusus. Terakhir, beberapa tag digunakan untuk memformat teks dalam dokumentasi Anda. Artikel ini menjelaskan tag yang direkomendasikan yang diatur berdasarkan penggunaannya.

Kompilator memverifikasi sintaksis elemen diikuti oleh satu * dalam daftar berikut. Visual Studio menyediakan IntelliSense untuk tag yang diverifikasi oleh kompilator dan semua tag yang diikuti oleh ** dalam daftar berikut. Selain tag yang tercantum di sini, kompilator dan Visual Studio memvalidasi tag <b>, <i>, <u>, <br/>, dan <a>. Kompilator juga memvalidasi <tt>, yang merupakan HTML yang tidak digunakan lagi.

Catatan

Komentar dokumentasi tidak dapat diterapkan ke namespace layanan.

Jika Anda ingin tanda kurung sudut muncul dalam teks komentar dokumentasi, gunakan pengodean HTML < dan >, yang masing-masing adalah &lt; dan &gt;. Pengodean ini ditunjukkan dalam contoh berikut.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Tag umum

<ringkasan>

<summary>description</summary>

Tag <summary> harus digunakan untuk menjelaskan jenis atau anggota jenis. Gunakan <keterangan> untuk menambahkan informasi tambahan ke deskripsi jenis. Gunakan atribut cref untuk mengaktifkan alat dokumentasi seperti DocFX dan Sandcastle guna membuat hyperlink internal ke halaman dokumentasi untuk elemen kode. Teks untuk <summary> tag ditampilkan di IntelliSense dan di jendela Browser Objek.

<keterangan>

<remarks>
description
</remarks>

Tag <remarks> digunakan untuk menambahkan informasi tentang jenis atau anggota jenis, melengkapi informasi yang ditentukan dengan <ringkasan>. Informasi ini ditampilkan di jendela Object Browser. Tag ini mungkin menyertakan penjelasan yang lebih panjang. Anda mungkin menemukan bahwa menggunakan bagian CDATA untuk markdown membuat penulisan menjadi lebih nyaman. Alat seperti docfx memproses teks markdown di bagian CDATA.

Anggota dokumen

<pengembalian>

<returns>description</returns>

Tag <returns> harus digunakan dalam komentar untuk deklarasi metode guna menjelaskan nilai kembali.

<param>

<param name="name">description</param>
  • name: Nama parameter metode. Sertakan nama dalam tanda kutip ganda (" "). Nama untuk parameter harus cocok dengan tanda tangan API. Jika satu atau lebih parameter tidak tercakup, kompilator mengeluarkan peringatan. Kompilator juga mengeluarkan peringatan jika nilai name tidak cocok dengan parameter formal dalam deklarasi metode.

Tag <param> harus digunakan dalam komentar untuk deklarasi metode guna menjelaskan salah satu parameter metode. Untuk mendokumentasikan beberapa parameter, gunakan beberapa tag <param>. Teks untuk tag <param> ditampilkan di IntelliSense, Object Browser, dan Code Comment Web Report.

<paramref>

<paramref name="name"/>
  • name: Nama parameter yang dirujuk. Sertakan nama dalam tanda kutip ganda (" ").

Tag <paramref> memberi Anda cara untuk menunjukkan bahwa sebuah kata dalam komentar kode, misalnya di blok <summary> atau <remarks> mengacu pada parameter. File XML dapat diproses untuk memformat kata ini dalam beberapa cara yang berbeda, seperti dengan font tebal atau miring.

<pengecualian>

<exception cref="member">description</exception>
  • cref = "member": Referensi ke pengecualian yang tersedia dari lingkungan kompilasi saat ini. Kompilator memeriksa bahwa pengecualian yang diberikan ada dan menerjemahkan member ke nama elemen kanonis dalam XML output. member harus muncul dalam tanda kutip ganda (" ").

Tag <exception> memungkinkan Anda menentukan pengecualian mana yang dapat dilemparkan. Tag ini dapat diterapkan pada definisi untuk metode, properti, peristiwa, dan pengindeks.

<value>

<value>property-description</value>

Tag <value> memungkinkan Anda menjelaskan nilai yang diwakili oleh properti. Saat Anda menambahkan properti melalui panduan kode di lingkungan pengembangan Visual Studio .NET, ia menambahkan tag <ringkasan> untuk properti baru. Anda menambahkan tag <value> secara manual untuk menjelaskan nilai yang diwakili oleh properti.

Format output dokumentasi

<p>ara

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

Tag <para> digunakan di dalam tag, seperti <ringkasan>, <keterangan>, atau <pengembalian>, dan memungkinkan Anda menambahkan struktur ke teks. Tag <para> membuat paragraf spasi ganda. Gunakan tag <br/> jika Anda menginginkan paragraf dengan spasi tunggal.

<daftar>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

Blok <listheader> digunakan untuk menentukan baris judul tabel atau daftar definisi. Saat menentukan tabel, Anda hanya perlu menyediakan entri untuk term di judul. Setiap item dalam daftar ditentukan dengan blok <item>. Saat membuat daftar definisi, Anda harus menentukan term dan description. Namun, untuk tabel, daftar berpoin, atau daftar bernomor, Anda hanya perlu memasukkan entri untuk description. Daftar atau tabel dapat memiliki blok <item> sebanyak yang diperlukan.

<c>

<c>text</c>

Tag <c> memberi Anda cara untuk menunjukkan bahwa teks dalam deskripsi harus ditandai sebagai kode. Gunakan <kode> untuk menunjukkan beberapa baris sebagai kode.

<code>

<code>
    var index = 5;
    index++;
</code>

Tag <code> digunakan untuk menunjukkan beberapa baris kode. Gunakan <c> untuk menunjukkan bahwa teks satu baris dalam deskripsi harus ditandai sebagai kode.

<contoh>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

Tag <example> memungkinkan Anda menentukan contoh cara menggunakan metode atau anggota pustaka lainnya. Contoh biasanya melibatkan penggunaan tag <kode>.

Gunakan kembali teks dokumentasi

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Mewarisi komentar XML dari kelas dasar, antarmuka, dan metode serupa. Menggunakan inheritdoc menghilangkan penyalinan dan penempelan yang tidak diinginkan dari komentar XML duplikat dan secara otomatis membuat komentar XML tetap sinkron. Perhatikan bahwa saat Anda menambahkan tag <inheritdoc> ke suatu jenis, semua anggota juga akan mewarisi komentar.

  • cref: Menentukan anggota yang akan mewarisi dokumentasi. Tag yang sudah ditentukan pada anggota saat ini tidak diambil alih oleh yang diwarisi.
  • path: Kueri ekspresi JalurX yang akan menghasilkan kumpulan node untuk ditampilkan. Anda dapat menggunakan atribut ini untuk memfilter tag yang akan disertakan atau dikecualikan dari dokumentasi yang diwarisi.

Tambahkan komentar XML Anda di kelas dasar atau antarmuka dan biarkan inheritancedoc menyalin komentar ke kelas penerapan. Tambahkan komentar XML Anda ke metode sinkron Anda dan biarkan inheritancedoc menyalin komentar ke versi asinkron Anda dari metode yang sama. Jika Anda ingin menyalin komentar dari anggota tertentu, gunakan atribut cref untuk menentukan anggota.

<termasuk>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Nama file XML yang berisi dokumentasi. Nama file dapat dikualifikasikan dengan jalur relatif terhadap file kode sumber. Sertakan filename dalam tanda petik tunggal (' ').
  • tagpath: Jalur tag di filename yang mengarah ke tag name. Sertakan jalur dalam tanda kutip tunggal (' ').
  • name: Penentu nama di tag yang mendahului komentar; name akan memiliki id.
  • id: ID untuk tag yang mendahului komentar. Sertakan ID dalam tanda kutip ganda (" ").

Tag <include> memungkinkan Anda merujuk ke komentar di file lain yang menjelaskan jenis dan anggota dalam kode sumber Anda. Menyertakan file eksternal adalah alternatif untuk menempatkan komentar dokumentasi secara langsung di file kode sumber Anda. Dengan meletakkan dokumentasi dalam file terpisah, Anda dapat menerapkan kontrol sumber ke dokumentasi secara terpisah dari kode sumber. Satu orang dapat memeriksa file kode sumber dan orang lain dapat memeriksa file dokumentasi. Tag <include> menggunakan sintaksis JalurX XML. Lihat dokumentasi JalurX untuk mengetahui cara menyesuaikan penggunaan <include> Anda.

Misalnya, kode sumber berikut menggunakan <include> tag untuk menyertakan keterangan. Jalur file relatif terhadap sumber.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

Sumber XML untuk file sertakan diperlihatkan dalam sampel berikut. Ini disusun sama dengan file XML yang dihasilkan oleh pengkompilasi C#. File XML dapat berisi teks untuk beberapa metode atau jenis, selama ekspresi XPath dapat mengidentifikasinya.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

Output XML untuk metode ini diperlihatkan dalam contoh berikut:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Tip

Tim Runtime .NET menggunakan <include> tag secara ekstensif dalam dokumentasinya. Anda dapat melihat banyak contoh dengan mencari dotnet/runtime repositori.

<lihat>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": Referensi ke anggota atau bidang yang tersedia untuk dipanggil dari lingkungan kompilasi saat ini. Kompilator memeriksa apakah elemen kode yang diberikan ada dan meneruskan member ke nama elemen dalam XML keluaran. Tempatkan anggota di dalam tanda kutip ganda (" "). Anda dapat memberikan teks tautan yang berbeda untuk "cref", dengan menggunakan tag penutup terpisah.
  • href="link": Tautan yang dapat diklik ke URL tertentu. Misalnya, <see href="https://github.com">GitHub</see> menghasilkan link yang dapat diklik dengan teks GitHub yang tertaut ke https://github.com.
  • langword="keyword": Kata kunci bahasa, seperti true atau salah satu kata kunci valid lainnya.

Tag <see> memungkinkan Anda menentukan link dari dalam teks. Gunakan <seealso> untuk menunjukkan bahwa teks harus ditempatkan di bagian Lihat Juga. Gunakan atribut cref untuk membuat hyperlink internal ke halaman dokumentasi untuk elemen kode. Anda menyertakan parameter jenis untuk menentukan referensi ke jenis atau metode umum, seperti cref="IDictionary{T, U}". Selain itu, href adalah atribut yang valid yang akan berfungsi sebagai hyperlink.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Referensi ke anggota atau bidang yang tersedia untuk dipanggil dari lingkungan kompilasi saat ini. Kompilator memeriksa apakah elemen kode yang diberikan ada dan meneruskan member ke nama elemen dalam XML keluaran. member harus muncul dalam tanda kutip ganda (" ").
  • href="link": Tautan yang dapat diklik ke URL tertentu. Misalnya, <seealso href="https://github.com">GitHub</seealso> menghasilkan link yang dapat diklik dengan teks GitHub yang tertaut ke https://github.com.

Tag <seealso> memungkinkan Anda menentukan teks yang mungkin ingin Anda tampilkan di bagian Lihat Juga. Gunakan <see> untuk menentukan tautan dari dalam teks. Anda tidak dapat menyarangkan tag seealso di dalam tag summary.

atribut cref

Atribut cref dalam tag dokumentasi XML berarti "referensi kode". Ini menentukan bahwa teks bagian dalam dari tag adalah elemen kode, seperti jenis, metode, atau properti. Alat dokumentasi seperti DocFX dan Sandcastle menggunakan atribut cref untuk secara otomatis membuat hyperlink ke laman tempat jenis atau anggota didokumentasikan.

atribut href

Atribut href berarti referensi ke halaman web. Anda dapat menggunakannya untuk referensi langsung dokumentasi online tentang API atau pustaka Anda.

Metode dan jenis generik

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: Nama parameter jenis. Sertakan nama dalam tanda kutip ganda (" ").

Tag <typeparam> harus digunakan dalam komentar untuk deklarasi metode atau jenis generik untuk menjelaskan parameter jenis. Tambahkan tag untuk setiap parameter jenis dari metode atau jenis generik. Teks untuk tag <typeparam> akan ditampilkan di IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: Nama parameter jenis. Sertakan nama dalam tanda kutip ganda (" ").

Gunakan tag ini untuk memungkinkan penggunaan file dokumentasi memformat kata dalam beberapa cara yang berbeda, misalnya dalam huruf miring.

Tag yang ditentukan pengguna

Semua tag yang diuraikan di atas mewakili tag yang dikenali oleh kompilator C#. Tetapi, pengguna bebas menentukan tag mereka sendiri. Alat seperti Sandcastle memberikan dukungan untuk tag tambahan seperti <peristiwa> dan <catatan>, dan bahkan mendukung mendokumentasikan namespace layanan. Alat pembuatan dokumentasi khusus atau internal juga dapat digunakan dengan tag standar, dan beberapa format output dari HTML ke PDF dapat didukung.