Mendokumentasikan kode Anda dengan komentar XML

Artikel
04/08/2023

Anda dapat menghasilkan dokumentasi dari komentar kode tiga garis miring (///) di F#. Komentar XML dapat mendahului deklarasi dalam file kode (.fs) atau file tanda tangan (.fsi).

Komentar dokumentasi XML adalah jenis komentar khusus, ditambahkan di atas definisi jenis atau anggota yang ditentukan pengguna. Ini istimewa karena dapat diproses oleh kompilator untuk menghasilkan file dokumentasi XML pada waktu kompilasi. File XML yang dihasilkan kompilator dapat didistribusikan bersama rakitan .NET Anda, sehingga IDE dapat menggunakan tips alat untuk menampilkan informasi cepat tentang jenis atau anggota. Selain itu, file XML dapat dijalankan melalui alat seperti fsdoc untuk menghasilkan situs web referensi API.

Komentar dokumentasi XML, seperti semua komentar lainnya, diabaikan oleh kompiler, kecuali opsi yang dijelaskan di bawah ini diaktifkan untuk memeriksa validitas dan kelengkapan komentar pada waktu kompilasi.

Anda dapat membuat file XML pada waktu kompilasi dengan melakukan salah satu hal berikut:

Anda dapat menambahkan GenerateDocumentationFile elemen ke bagian <PropertyGroup> file proyek .fsproj Anda, yang menghasilkan file XML di direktori proyek dengan nama file akar yang sama dengan rakitan. Misalnya:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Untuk informasi selengkapnya, lihat properti GenerateDocumentationFile.
Jika Anda mengembangkan aplikasi menggunakan Visual Studio, klik kanan pada proyek dan pilih Properti. Dalam dialog properti, pilih tab Build, dan periksa file dokumentasi XML. Anda juga dapat mengubah lokasi tempat kompilator menulis file.

Ada dua cara untuk menulis komentar dokumentasi XML: dengan dan tanpa tag XML. Keduanya menggunakan komentar tiga garis miring.

Komentar tanpa tag XML

Jika komentar /// tidak dimulai dengan <, maka seluruh teks komentar diambil sebagai dokumentasi ringkasan untuk konstruksi kode yang segera mengikuti. Gunakan metode ini ketika Anda hanya ingin menulis ringkasan singkat untuk setiap konstruk.

Komentar dikodekan ke XML selama persiapan dokumentasi, sehingga karakter seperti <, >, dan & tidak perlu diloloskan. Jika Anda tidak menentukan tag ringkasan secara eksplisit, Anda tidak boleh menentukan tag lain, seperti tag param atau pengembalian.

Contoh berikut menunjukkan metode alternatif, tanpa tag XML. Dalam contoh ini, seluruh teks dalam komentar dianggap sebagai ringkasan.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

Komentar dengan tag XML

Jika isi komentar dimulai dengan < (biasanya <summary>), maka itu diperlakukan sebagai isi komentar berformat XML menggunakan tag XML. Cara kedua ini memungkinkan Anda menentukan catatan terpisah untuk ringkasan singkat, komentar tambahan, dokumentasi untuk setiap parameter dan parameter jenis dan pengecualian yang dilemparkan, dan deskripsi nilai yang dikembalikan.

Berikut ini adalah komentar dokumentasi XML umum dalam file tanda tangan:

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

Tag yang Direkomendasikan

Jika Anda menggunakan tag XML, tabel berikut menjelaskan tag luar yang dikenali dalam komentar kode F# XML.

Sintaks tag	Deskripsi
`<summary>`*text*`</summary>`	Menentukan bahwa teks adalah deskripsi singkat dari elemen program. Deskripsi biasanya terdiri dari satu atau dua kalimat.
`<remarks>`*text*`</remarks>`	Menentukan bahwa teks berisi informasi tambahan tentang elemen program.
`<param name="`*nama`">`deskripsi*`</param>`	Menentukan nama dan deskripsi untuk parameter fungsi atau metode.
`<typeparam name="`*nama`">`deskripsi*`</typeparam>`	Menentukan nama dan deskripsi untuk parameter jenis.
`<returns>`*text*`</returns>`	Menentukan bahwa teks menjelaskan nilai pengembalian fungsi atau metode.
`<exception cref="`*jenis`">`Deskripsi*`</exception>`	Menentukan jenis pengecualian yang dapat dihasilkan dan keadaan di mana pengecualian tersebut dilemparkan.
`<seealso cref="`*referensi*`"/>`	Menentukan tautan Lihat Juga ke dokumentasi untuk jenis lain. Referensi adalah nama seperti yang muncul dalam file dokumentasi XML. Lihat Juga tautan biasanya muncul di bagian bawah halaman dokumentasi.

Tabel berikut ini menjelaskan tag untuk digunakan di dalam bagian deskripsi:

Sintaks tag	Deskripsi
`<para>`*text*`</para>`	Menentukan paragraf teks. Ini digunakan untuk memisahkan teks di dalam tag keterangan.
`<code>`*text*`</code>`	Menentukan bahwa teks adalah beberapa baris kode. Tag ini dapat digunakan oleh generator dokumentasi untuk menampilkan teks dalam font yang sesuai untuk kode.
`<paramref name="`*nama*`"/>`	Menentukan referensi ke parameter dalam komentar dokumentasi yang sama.
`<typeparamref name="`*nama*`"/>`	Menentukan referensi ke parameter jenis dalam komentar dokumentasi yang sama.
`<c>`*text*`</c>`	Menentukan bahwa teks adalah kode sebaris. Tag ini dapat digunakan oleh generator dokumentasi untuk menampilkan teks dalam font yang sesuai untuk kode.
`<see cref="`*referensi`">`teks*`</see>`	Menentukan tautan sebaris ke elemen program lain. Referensi adalah nama seperti yang muncul dalam file dokumentasi XML. Teks adalah teks yang ditampilkan dalam tautan.

Tag yang ditentukan pengguna

Tag sebelumnya mewakili tag yang dikenali oleh kompilator F# dan alat editor F# khusus. Tetapi, pengguna bebas menentukan tag mereka sendiri. Alat seperti fsdoc membawa dukungan untuk tag tambahan seperti <namespacedoc>. Alat pembuatan dokumentasi khusus atau internal juga dapat digunakan dengan tag standar, dan beberapa format output dari HTML ke PDF dapat didukung.

Pemeriksaan waktu kompilasi

Ketika --warnon:3390 diaktifkan, kompilator memverifikasi sintaks XML dan parameter yang dimaksud dalam tag <param> dan <paramref>.

Mendokumentasikan Konstruksi F#

Konstruksi F# seperti modul, anggota, kasus serikat, dan bidang rekaman didokumentasikan oleh komentar /// segera sebelum dideklarasikan. Jika diperlukan, konstruktor implisit kelas didokumentasikan dengan memberikan komentar /// sebelum daftar argumen. Misalnya:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Batasan

Beberapa fitur dokumentasi XML dalam C# dan bahasa .NET lainnya tidak didukung di F#.

Di F#, referensi silang harus menggunakan tanda tangan XML lengkap dari simbol yang sesuai cref="T:System.Console". Referensi silang gaya C# sederhana seperti cref="Console" tidak diuraikan ke tanda tangan XML penuh dan elemen-elemen ini tidak diperiksa oleh kompilator F#. Beberapa alat dokumentasi memungkinkan penggunaan referensi silang ini dengan pemrosesan selanjutnya, tetapi tanda tangan lengkap harus digunakan.
Tag <include>, <inheritdoc> tidak didukung oleh kompilator F#. Tidak akan ada kesalahan jika itu digunakan, tetapi hanya disalin ke file dokumentasi yang dibuat tanpa memengaruhi dokumentasi yang dibuat.
Referensi silang tidak diperiksa oleh kompilator F#, bahkan ketika -warnon:3390 digunakan.
Nama-yang digunakan dalam tag <typeparam> dan <typeparamref> tidak diperiksa oleh kompilator F#, meskipun --warnon:3390 digunakan.
Tidak ada peringatan yang diberikan jika tidak ada dokumentasi, bahkan ketika --warnon:3390 digunakan.

Rekomendasi

Kode dokumen disarankan karena berbagai alasan. Berikut ini adalah beberapa praktik terbaik, skenario kasus penggunaan umum, dan hal-hal yang harus Anda ketahui saat menggunakan tag dokumentasi XML dalam kode F# Anda.

Aktifkan opsi --warnon:3390 dalam kode Anda untuk membantu memastikan dokumentasi XML Anda valid XML.
Pertimbangkan untuk menambahkan file tanda tangan untuk memisahkan komentar dokumentasi XML yang panjang dari implementasi Anda.
Demi konsistensi, semua jenis yang terlihat secara publik dan anggotanya harus didokumentasikan. Jika Anda harus melakukannya, maka lakukan semuanya.
Minimal, modul, jenis, dan anggotanya harus memiliki komentar /// atau tag <summary> biasa. Ini akan ditampilkan di jendela tips alat pelengkapan otomatis di alat pengeditan F#.
Teks dokumentasi harus ditulis dengan menggunakan kalimat lengkap yang diakhiri dengan titik.