Sisipkan komentar XML untuk pembuatan dokumentasi

Artikel ini menjelaskan bagaimana Visual Studio dapat membantu Anda mendokumentasikan elemen kode seperti kelas dan metode dengan membuat struktur komentar dokumentasi XML standar secara otomatis. Pada waktu kompilasi, Anda dapat menghasilkan file XML yang berisi komentar dokumentasi.

Anda dapat mendistribusikan file XML yang dihasilkan kompilator bersama dengan rakitan .NET Anda sehingga Visual Studio dan IDEs lainnya dapat menggunakan IntelliSense untuk menampilkan informasi cepat tentang jenis dan anggota. Anda juga dapat menjalankan file XML melalui alat seperti DocFX dan Sandcastle untuk menghasilkan situs web referensi API.

Catatan

Perintah Sisipkan Komentar untuk menyisipkan struktur komentar dokumentasi XML secara otomatis tersedia di C# dan Visual Basic. Untuk C++, Anda dapat menyisipkan komentar dokumentasi XML secara manual dan masih menghasilkan file dokumentasi XML pada waktu kompilasi.

Mengaktifkan pembuatan dokumentasi

Untuk mengaktifkan pembuatan dokumentasi, pilih kotak centang Buat file yang berisi dokumentasi API pada tab Output Build>properti proyek Anda.

Secara default, file dokumentasi bernama sama dengan rakitan Anda dengan ekstensi file .xml dihasilkan dalam direktori yang sama dengan rakitan. Jika Anda ingin mengonfigurasi nama atau lokasi nondefault untuk file tersebut, masukkan atau telusuri ke lokasi alternatif di bawah jalur file dokumentasi XML.

Atau, Anda dapat menambahkan properti GenerateDocumentationFile atau DocumentationFile ke file .csproj, .vbproj, atau .fsproj Anda. Atur GenerateDocumentationFile ke true untuk menghasilkan file dokumentasi dengan nama dan lokasi default. DocumentationFile Gunakan properti untuk menentukan nama atau lokasi yang berbeda.

Jika Anda menggunakan DocumentationFile dengan sendirinya atau dengan properti diatur GenerateDocumentationFile ke true, file dokumentasi dengan nama dan lokasi yang ditentukan dihasilkan. Namun, jika Anda mengatur GenerateDocumentationFile ke false, tidak ada file dokumentasi yang dihasilkan bahkan jika Anda mengatur DocumentationFile properti .

Mengaktifkan pintasan keyboard penyisipan komentar

Anda bisa mengatur opsi Komentar untuk menyisipkan struktur komentar XML secara otomatis setelah Anda mengetik /// C# atau ''' di Visual Basic.

1. Dari bilah menu Visual Studio, pilih Opsi Alat>.
2. Dalam kotak dialog Opsi, navigasi ke Editor>Teks C# (atau Visual Basic) >Tingkat Lanjut.
3. Di bawah bagian Komentar , pilih atau batal pilih Hasilkan komentar dokumentasi XML untuk \\\ (atau ''').

Menyisipkan komentar XML secara otomatis

1. Di Visual Studio, letakkan kursor Anda di atas elemen yang ingin Anda dokumentasikan, misalnya metode.

2. Ikuti salah satu tindakan berikut:

   • Jika pintasan penyisipan komentar otomatis diaktifkan, ketik /// C#, atau ''' di Visual Basic.
   • Dari menu Edit, pilih IntelliSense>Sisipkan Komentar.
   • Dari menu klik kanan atau konteks, pilih Cuplikan>Sisipkan Komentar.

   Struktur komentar XML segera dihasilkan di atas elemen kode. Misalnya, saat mengomentari metode berikut GetUserName , templat menghasilkan <summary> elemen, <param> elemen untuk parameter, dan <returns> elemen untuk mendokumentasikan nilai yang dikembalikan.

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

3. Masukkan deskripsi untuk setiap elemen XML untuk sepenuhnya mendokumenkan kode. Contohnya:

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

Anda bisa menggunakan elemen dan gaya XML dalam komentar yang dirender di Info Cepat saat Anda mengarahkan mouse ke atas kode. Elemen-elemen ini mencakup gaya miring atau tebal, daftar berpoin atau bernomor, dan dapat diklik cref atau href ditautkan.

Misalnya, masukkan kode berikut ke dalam file program C#:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Saat Anda mengarahkan mouse ke atas GetUserName, panel Info Cepat muncul sebagai berikut:

Konten terkait

• Komentar dokumentasi
• Dokumentasi XML di Visual Basic
• Komentar (C++)
• Dokumentasi XML (Visual C++)
• Pembuatan kode