Bagikan melalui

Mendokumentasikan kode Anda dengan komentar XML

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. Mereka istimewa karena dapat diproses oleh pengkompilasi untuk menghasilkan file dokumentasi XML pada waktu kompilasi. File XML yang dihasilkan oleh kompilator dapat didistribusikan bersama rakitan .NET Anda sehingga IDE dapat menggunakan tooltip untuk menampilkan informasi singkat tentang jenis atau anggota. Selain itu, file XML dapat dijalankan melalui alat seperti fsdocs untuk menghasilkan situs web referensi API.

Secara default, komentar dokumentasi XML diabaikan oleh pengkompilasi. Untuk mengubah ini, atur --warnon:3390. Pengkompilasi kemudian akan memverifikasi sintaks XML dan parameter yang dimaksud dalam tag <param> dan <paramref>.

Anda dapat mengaktifkan peringatan ini di file proyek Anda dengan menambahkan <WarnOn> elemen ke <PropertyGroup> bagian:

<WarnOn>3390</WarnOn>

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

  • Anda dapat menambahkan elemen GenerateDocumentationFile 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 pengkompilasi 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 konstruksi.

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 param atau mengembalikan tag.

Nota

Saat Anda menggunakan komentar tanpa tag XML, markup apa pun yang Anda sertakan (seperti tag HTML atau sintaks seperti XML) tidak akan diurai atau diperiksa oleh pengkompilasi atau alat F#. Beberapa alat eksternal seperti GitHub mungkin mencoba mengurai markup, tetapi dapat gagal jika sintaks berisi kesalahan. Jika Anda perlu menggunakan tag XML dalam dokumentasi Anda, bungkus komentar Anda dengan tag XML yang tepat seperti <summary> untuk memastikan mereka divalidasi oleh pengkompilasi saat --warnon:3390 diaktifkan.

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. Pendekatan kedua ini memungkinkan Anda menentukan catatan terpisah untuk ringkasan singkat, komentar tambahan, dokumentasi untuk setiap parameter dan jenis parameter 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

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

Sintaks tag Deskripsi
<summary> teks</summary> Menentukan bahwa teks adalah deskripsi singkat tentang elemen program. Deskripsi biasanya satu atau dua kalimat.
<remarks> teks</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> teks</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"/> Menunjukkan tautan Lihat Juga ke dokumentasi untuk tipe 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> teks</para> Menentukan paragraf teks. Ini digunakan untuk memisahkan teks di dalam tag keterangan.
<code> teks</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> teks</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 diperlihatkan dalam tautan.

Tag yang ditentukan pengguna

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

Pemeriksaan waktu kompilasi

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

Mendokumen konstruksi F#

Konstruksi F# seperti modul, anggota, kasus gabungan, dan field rekaman didokumentasikan dengan komentar /// tepat sebelum deklarasinya. 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

Keterbatasan

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, misalnya cref="T:System.Console". Referensi silang C#-style sederhana seperti cref="Console" tidak dijabarkan ke tanda tangan XML penuh dan elemen-elemen ini tidak diperiksa oleh pengkompilasi F#. Beberapa alat dokumentasi dapat memungkinkan penggunaan referensi silang ini dengan pemrosesan berikutnya, tetapi tanda tangan lengkap harus digunakan.

  • Tag <include>, <inheritdoc> tidak didukung oleh pengkompilasi F#. Tidak ada kesalahan yang diberikan jika mereka digunakan, tetapi hanya disalin ke file dokumentasi yang dihasilkan tanpa memengaruhi hasil dokumentasi tersebut.

  • Referensi silang tidak diperiksa oleh pengkompilasi F#, bahkan ketika -warnon:3390 digunakan.

  • Nama yang digunakan dalam tag <typeparam> dan <typeparamref> tidak diperiksa oleh kompilator F#, bahkan ketika --warnon:3390 digunakan.

  • Tidak ada peringatan yang diberikan jika dokumentasi hilang, bahkan ketika --warnon:3390 digunakan.

Rekomendasi

Kode dokumentasi direkomendasikan 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 panjang dari implementasi Anda.

  • Demi konsistensi, semua jenis yang terlihat secara publik dan anggotanya harus didokumentasikan. Jika Anda harus melakukannya, lakukan semuanya.

  • Minimal, modul, jenis, dan anggotanya harus memiliki komentar /// biasa atau tag <summary>. Ini akan ditampilkan di jendela tipsalat pelengkapan otomatis di alat pengeditan F#.

  • Teks dokumentasi harus ditulis menggunakan kalimat lengkap yang berakhiran dengan penghentian penuh.

Lihat juga

  • Last updated on