Bagikan melalui

Tag XML yang direkomendasikan untuk komentar dokumentasi C#

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.

Referensi bahasa C# mendanai versi bahasa C# yang terbaru dirilis. Ini juga berisi dokumentasi awal untuk fitur dalam pratinjau publik untuk rilis bahasa yang akan datang.

Dokumentasi mengidentifikasi fitur apa pun yang pertama kali diperkenalkan dalam tiga versi terakhir bahasa atau dalam pratinjau publik saat ini.

Petunjuk / Saran

Untuk menemukan kapan fitur pertama kali diperkenalkan di C#, lihat artikel tentang riwayat versi bahasa C#.

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. Patuhi rekomendasi ini:

  • Demi konsistensi, dokumentasikan semua jenis yang terlihat secara publik dan anggota publik mereka.
  • Anda juga dapat mendokumentasikan anggota privat dengan menggunakan komentar XML. Namun, pendekatan ini mengekspos pekerjaan dalam (berpotensi rahasia) pustaka Anda.
  • Minimal, jenis dan anggotanya harus memiliki <summary> tag.
  • Tulis teks dokumentasi menggunakan kalimat lengkap yang diakhir dengan penghentian penuh.
  • Kelas parsial didukung sepenuhnya, dan informasi dokumentasi digabungkan menjadi satu entri untuk setiap jenis. Jika kedua deklarasi anggota parsial memiliki komentar dokumentasi, komentar pada deklarasi penerapan ditulis ke XML output.

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 berisi komentar yang mengatakan bahwa terjadi kesalahan.
  • Beberapa tag yang direkomendasikan memiliki arti khusus:
    • Tag menjelaskan <param> parameter. Jika Anda menggunakan tag ini, pengkompilasi memverifikasi bahwa parameter ada dan bahwa semua parameter dijelaskan dalam dokumentasi. Jika verifikasi gagal, kompilator mengeluarkan peringatan.
    • Lampirkan cref atribut ke tag apa pun untuk mereferensikan elemen kode. Kompilator memverifikasi bahwa elemen kode ini ada. Jika verifikasi gagal, kompilator mengeluarkan peringatan. Pengkompilasi menghormati arahan apa pun using ketika mencari jenis yang dijelaskan dalam cref atribut.
    • IntelliSense di dalam Visual Studio menggunakan <summary> tag untuk menampilkan informasi tambahan tentang jenis atau anggota.

      Catatan

      File XML tidak memberikan informasi lengkap tentang jenis dan anggota (misalnya, file XML 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. Pengkompilasi menyalin tag ini 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

Tag HTML seperti <br/> berguna untuk pemformatan dalam komentar dokumentasi. Tag <br/> membuat pemisah baris, sementara tag HTML lainnya menyediakan pemformatan teks. Tag ini berfungsi pada tooltip IntelliSense dan dokumentasi yang dihasilkan.

Catatan

Anda tidak dapat menerapkan komentar dokumentasi ke namespace.

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

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

Tag umum

<summary>

<summary>description</summary>

<summary> Gunakan tag untuk menjelaskan jenis atau anggota jenis. Gunakan <remarks> 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 muncul di IntelliSense dan di jendela Browser Objek.

<remarks>

<remarks>
description
</remarks>

<remarks> Gunakan tag untuk menambahkan informasi tentang jenis atau anggota jenis, melengkapi informasi yang ditentukan dengan <summary>. Informasi ini muncul di jendela Browser Objek. Tag ini dapat mencakup penjelasan yang lebih panjang. Anda mungkin menemukan bahwa menggunakan CDATA bagian untuk markdown membuat penulisan lebih nyaman. Alat seperti docfx memproses teks markdown di bagian CDATA.

Anggota dokumen

<returns>

<returns>description</returns>

<returns> Gunakan tag dalam komentar untuk deklarasi metode untuk menjelaskan nilai yang dikembalikan.

<param>

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

<param> Gunakan tag dalam komentar untuk deklarasi metode untuk menjelaskan salah satu parameter untuk metode tersebut. Untuk mendokumentasikan beberapa parameter, gunakan beberapa tag <param>. Teks untuk <param> tag muncul di IntelliSense, Browser Objek, dan Laporan Web Komentar Kode.

<paramref>

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

Tag <paramref> menyediakan cara untuk menunjukkan bahwa kata dalam komentar kode, seperti di <summary> atau <remarks> blok, mengacu pada parameter. Anda dapat memproses file XML untuk memformat kata ini dengan cara yang berbeda, seperti dengan menggunakan font tebal atau miring.

<exception>

<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 (").

Tag <exception> memungkinkan Anda menentukan pengecualian mana yang dapat dilemparkan. Terapkan tag ini ke 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 dengan menggunakan wizard kode di lingkungan pengembangan Visual Studio .NET, <summary> properti menambahkan tag untuk properti baru. Anda menambahkan tag <value> secara manual untuk menjelaskan nilai yang diwakili oleh properti.

Format output dokumentasi

<para>

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

Gunakan tag di <para> dalam tag, seperti <summary>, , <remarks>atau <returns>, untuk menambahkan struktur ke teks. Tag <para> membuat paragraf spasi ganda. Gunakan tag <br/> jika Anda menginginkan paragraf dengan spasi tunggal.

Berikut adalah contoh yang menunjukkan perbedaan antara <para> dan <br/>:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<list>

<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>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</description>
    </item>
</list>

<listheader> Gunakan blok untuk menentukan baris judul tabel atau daftar definisi.

Saat menentukan tabel:

  • Berikan entri untuk term di judul.
  • Tentukan setiap item dalam daftar dengan <item> blok. Untuk setiap item, berikan entri untuk description.

Saat membuat daftar definisi:

  • Berikan entri untuk term di judul.
  • Tentukan setiap item dalam daftar dengan <item> blok. Masing-masing item harus berisi dan termdescription .

Daftar atau tabel dapat memiliki blok <item> sebanyak yang diperlukan.

<c>

<c>text</c>

<c> Gunakan tag untuk menandai teks dalam deskripsi sebagai kode. Gunakan <code> untuk menunjukkan beberapa baris sebagai kode.

<code>

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

<code> Gunakan tag untuk menunjukkan beberapa baris kode. Gunakan <c> untuk menandai teks baris tunggal dalam deskripsi sebagai kode.

<example>

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

<example> Gunakan tag untuk memberikan contoh cara menggunakan metode atau anggota pustaka lainnya. Contoh umumnya melibatkan penggunaan <code> tag.

<b>

<b>text</b>

<b> Gunakan tag untuk membuat teks tebal dalam komentar dokumentasi. Pengkompilasi dan Visual Studio memvalidasi tag pemformatan HTML ini. Teks yang diformat muncul di IntelliSense dan dokumentasi yang dihasilkan.

<i>

<i>text</i>

<i> Gunakan tag untuk membuat teks miring dalam komentar dokumentasi. Pengkompilasi dan Visual Studio memvalidasi tag pemformatan HTML ini. Teks yang diformat muncul di IntelliSense dan dokumentasi yang dihasilkan.

<u>

<u>text</u>

<u> Gunakan tag untuk menggaris bawahi teks dalam komentar dokumentasi. Pengkompilasi dan Visual Studio memvalidasi tag pemformatan HTML ini. Teks yang diformat muncul di IntelliSense dan dokumentasi yang dihasilkan.

<br/>

Line one<br/>Line two

<br/> Gunakan tag untuk menyisipkan pemisah baris dalam komentar dokumentasi. Gunakan tag ini saat Anda menginginkan paragraf berspasi tunggal, dibandingkan <para> dengan tag yang membuat paragraf berspasi ganda.

<a>

<a href="https://example.com">Link text</a>

<a> Gunakan tag untuk membuat hyperlink dalam komentar dokumentasi. Atribut href menentukan URL yang akan ditautkan. Pengkompilasi dan Visual Studio memvalidasi tag pemformatan HTML ini.

Catatan

Pengkompilasi juga memvalidasi <tt> tag, yang merupakan HTML yang tidak digunakan lagi. <c> Gunakan tag sebagai gantinya untuk pemformatan kode sebaris.

Gunakan kembali teks dokumentasi

<inheritdoc>

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

Mewarisi komentar XML dari kelas dasar, antarmuka, dan metode serupa. Dengan menggunakan inheritdoc, Anda menghilangkan penyalinan dan tempel komentar XML duplikat yang tidak diinginkan dan secara otomatis menjaga komentar XML tetap sinkron. Saat Anda menambahkan <inheritdoc> tag ke jenis, semua anggota juga mewarisi komentar.

  • cref: Menentukan anggota yang akan mewarisi dokumentasi. Tag yang diwariskan tidak mengambil alih tag yang sudah ditentukan pada anggota saat ini.
  • path: Kueri ekspresi XPath yang menghasilkan simpul yang diatur untuk ditampilkan. Gunakan atribut ini untuk memfilter tag untuk disertakan atau dikecualikan dari dokumentasi yang diwariskan.

Catatan

Visual Studio secara otomatis mewarisi dokumentasi XML untuk anggota yang tidak terdokumentasi yang mengambil alih atau menerapkan anggota yang didokumentasikan. Fitur ini menampilkan dokumentasi yang diwariskan di IntelliSense dan Info Cepat tanpa memerlukan <inheritdoc> tag. Namun, pewarisan otomatis ini hanya berlaku dalam VISUAL Studio IDE dan tidak memengaruhi file dokumentasi XML yang dihasilkan oleh pengkompilasi.

Untuk API publik di pustaka yang Anda distribusikan, gunakan tag secara <inheritdoc> eksplisit atau berikan dokumentasi lengkap untuk memastikan file dokumentasi XML yang dihasilkan menyertakan semua informasi yang diperlukan untuk konsumen pustaka Anda.

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. Untuk menyalin komentar dari anggota tertentu, gunakan cref atribut untuk menentukan anggota.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Nama file XML yang berisi dokumentasi. Anda dapat memenuhi syarat nama file dengan jalur yang 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 dalam tag yang mendahului komentar. Penentu nameidmemiliki .
  • id: ID untuk tag yang mendahului komentar. Sertakan ID dalam tanda kutip (").

Dengan menggunakan <include> tag, Anda dapat 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>

Petunjuk / Saran

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

<see>

<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 dapat Anda panggil dari lingkungan kompilasi saat ini. Kompilator memeriksa apakah elemen kode yang diberikan ada dan meneruskan member ke nama elemen dalam XML keluaran. Tempatkan anggota dalam tanda kutip ("). Anda dapat menyediakan teks tautan yang crefberbeda untuk , 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. Gunakan href alih-alih cref saat menautkan ke halaman web eksternal, seperti cref yang dirancang untuk referensi kode dan tidak membuat tautan yang dapat diklik untuk URL eksternal.
  • 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. Sertakan parameter jenis untuk menentukan referensi ke jenis atau metode generik, seperti cref="IDictionary{T, U}". Selain itu, href adalah atribut valid yang berfungsi sebagai hyperlink.

Berikut adalah contoh yang menunjukkan perbedaan antara cref dan href saat mereferensikan URL eksternal:

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Referensi ke anggota atau bidang yang dapat Anda panggil 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 (").
  • 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 menumpuk tag di seealso dalam summary tag.

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. Saat Anda perlu menautkan ke URL eksternal di komentar dokumentasi Anda, gunakan href alih-alih cref untuk memastikan tautan dapat diklik di tipsalat IntelliSense dan dokumentasi yang dihasilkan.

Metode dan jenis generik

<typeparam>

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

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 <typeparam> tag ditampilkan di IntelliSense.

<typeparamref>

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

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 dalam artikel ini mewakili tag yang dikenali oleh pengkompilasi C#. Tetapi, pengguna bebas menentukan tag mereka sendiri. Alat seperti Sandcastle menghadirkan dukungan untuk tag tambahan seperti <event> dan <note>, dan bahkan mendukung namespace dokumentasi. Alat pembuatan dokumentasi khusus atau internal juga dapat digunakan dengan tag standar, dan beberapa format output dari HTML ke PDF dapat didukung.

  • Last updated on