Bagikan melalui

Cara menulis dokumen /// yang baik untuk referensi .NET API

Tujuan utama untuk dokumen .NET API adalah agar /// komentar XML dalam kode sumber .NET menjadi "sumber kebenaran". Untuk MSBuild, ASP.NET Core, dan EF Core, tujuan ini telah terpenuhi. Namun, saat ini repositori dotnet-api-docs tetap menjadi sumber kebenaran untuk beberapa namespace dalam referensi .NET API. Masalah dotnet/runtime ini melacak upaya untuk melakukan backport dokumen .NET dan menjadikan repositori dotnet/runtime sebagai sumber utama. Kehadiran atau tidak adanya tombol "edit" pada halaman sering menunjukkan bahwa dotnet-api-docs repositori adalah sumber kebenaran. Jika hilang, sumber kebenaran kemungkinan adalah komentar /// dalam repositori sumber.

Artikel ini menyediakan tips tentang menulis komentar dokumen yang baik dalam kode sumber itu sendiri.

Komentar yang baik berkontribusi pada dokumen yang bagus

Komentar triple-slash (.NET API) diubah menjadi dokumentasi publik di learn.microsoft.com dan juga muncul di IntelliSense di IDE. Komentar harus:

  • Selesai—entri dokumen kosong untuk metode, parameter, pengecualian, dan sebagainya, membuat API terlihat tidak memadai, sifatnya sementara, atau sepele.
  • Benar—pembaca memindai detail penting dan menjadi frustrasi saat informasi utama hilang atau salah.
  • Kontekstual—pembaca masuk ke halaman ini dari pencarian dan perlu mengetahui bagaimana dan kapan menggunakan API, dan apa implikasi kodenya.
  • Tersusun rapi—tata bahasa dan ejaan yang buruk atau terburu-buru dapat membingungkan pembaca dan bahkan membuat panggilan yang sederhana menjadi ambigu; juga, presentasi yang buruk menunjukkan investasi yang rendah.

Praktik terbaik

  1. Gunakan cref alih-alih href untuk menautkan ke jenis atau metode lain.

    Benar: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

    Salah: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

  2. Saat mereferensikan parameter, bungkus nama parameter dalam <paramref> tag, misalnya, The offset in <paramref name="source" /> where the range begins..

  3. Jika Anda memiliki lebih dari satu paragraf dalam komentar dokumen, pisahkan paragraf dengan <para> tag.

  4. Bungkus contoh kode dalam <code> tag dalam <example> tag.

  5. Gunakan <seealso> untuk menambahkan tautan ke API lain di bagian "Lihat Juga" yang dibuat secara otomatis.

Tag dokumen XML

Etiket Tujuan Contoh
<altmember> Menambahkan tautan "Lihat juga" ke API yang ditentukan. <altmember cref="System.Console.Out" />
<c> Memformat teks yang ditentukan sebagai kode dalam deskripsi. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Memformat beberapa baris sebagai kode. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Menambahkan contoh kode di bawah judul H2 "Contoh". <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Menjelaskan pengecualian yang dapat dilemparkan API. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Lihat komentar di file lain yang menjelaskan API dalam kode sumber Anda. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

Contoh .NET MAUI
<inheritdoc> Warisi komentar XML dari kelas dasar, antarmuka, dan metode serupa. <inheritdoc />
<list> Membuat daftar berpoin atau bernomor. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Memisahkan paragraf.
<paramref> Mengacu pada parameter metode. Returns the activity with the specified <paramref name="id" />.
<related> Menambahkan tautan "Lihat juga" ke artikel yang ditentukan. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Tautan ke API lain. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Memformat teks yang ditentukan sebagai kode. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Menambahkan tautan "Lihat juga" ke API yang ditentukan. <seealso cref="T:System.Single" />
<typeparamref> Mengacu pada parameter jenis. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Untuk informasi selengkapnya, lihat Tag XML yang direkomendasikan untuk C# dan spesifikasi C#. Spesifikasi ECMAXML juga memiliki informasi yang baik, meskipun perlu diketahui bahwa ada beberapa perbedaan antara komentar dokumentasi ECMAXML dan /// (misalnya, target cref sepenuhnya diperluas dan memiliki awalan di ECMAXML).

Referensi silang

Saat Anda menggunakan <see cref> tag untuk menautkan ke API lain, Anda tidak perlu menambahkan awalan ke nama jenis, seperti T: untuk jenis atau M: untuk metode. Bahkan, aturan analisis kode CA1200 menandai komentar kode yang menambahkan awalan ke nama jenis dalam cref tag. Namun, ada beberapa pengecualian untuk aturan ini:

  • Ketika Anda ingin menautkan ke bentuk umum metode yang memiliki lebih dari satu kelebihan beban, kompilator C# saat ini tidak mendukungnya. Solusi sementara untuk dokumen adalah dengan mengawali nama metode dengan O: dalam kode sumber (atau Overload: di ECMAXML) dan menekan aturan CA1200. Misalnya: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • Ketika API tidak dapat diakses dari konteks saat ini, yang mencakup setiap arahan using. Dalam hal ini, gunakan nama API yang lengkap dan memenuhi syarat dengan awalan.

Ketika tag <see cref> dikonversi ke ECMAXML, mdoc mengganti nama jenis dengan DocId lengkap API, yang termasuk awalan.

Deskripsi

Untuk panduan otoritatif tentang menjelaskan setiap jenis simbol dan berbagai bagiannya, lihat wiki dokumen .NET API.

Komentar kosong

Teks placeholder terkenal untuk komentar kosong adalah To be added.. Sistem build Learn mengenali teks ini dan menghapusnya saat ECMAXML dikonversi menjadi HTML, meninggalkan deskripsi kosong.

Pisahkan file kode

Jika contoh kode Anda panjang, Anda dapat memasukkannya ke dalam file terpisah di repositori dokumen dan menautkannya dari kode sumber dengan cara berikut:

/// <example>
/// <format type="text/markdown">
/// <![CDATA[
///  [!code-csharp[FieldAware](~/docs/samples/Microsoft.ML.Samples/Dynamic/FactorizationMachine.cs)]
/// ]]></format>
/// </example>

Untuk beberapa detail selengkapnya tentang cara menghubungkan file kode terpisah, lihat diskusi ini.

Atribut bahasa

Atribut bahasa pada <code> tag bersifat opsional, tetapi menyebabkan kode diformat dengan pengodean warna. Contohnya:

/// <example>
/// This sample shows the basic pattern for defining a typed client class.
///   <code language="csharp">
///     class ExampleClient
///     {
///       private readonly HttpClient _httpClient;
///       private readonly ILogger _logger;
///
///       // Typed clients can use constructor injection to access additional services.
///       public ExampleClient(HttpClient httpClient, ILogger&lt;ExampleClient&gt; logger)
///       {
///         _httpClient = httpClient;
///         _logger = logger;
///       }
///     }
///   </code>
/// </example>

Internal API

Saat mendokumenkan API yang tidak dimaksudkan untuk digunakan oleh konsumen, gunakan kata-kata yang mirip dengan yang berikut ini:

<summary>This type supports the .NET infrastructure and is not intended to be used directly from your code.</summary>

Lihat juga

  • Last updated on