Komentar Dokumentasi Annex D

Lampiran ini informatif.

D.1 Umum

C# menyediakan mekanisme bagi programmer untuk mendokumentasikan kode mereka menggunakan sintaks komentar yang berisi teks XML. Dalam file kode sumber, komentar yang memiliki bentuk tertentu dapat digunakan untuk mengarahkan alat agar menghasilkan XML dari komentar tersebut dan elemen kode sumber yang mendahului. Komentar yang menggunakan sintaks seperti itu disebut komentar dokumentasi. Mereka harus langsung mendahului jenis yang didefinisikan oleh pengguna (seperti kelas, delegasi, atau antarmuka) atau anggota (seperti bidang, event, properti, atau metode). Alat pembuatan XML disebut generator dokumentasi. (Generator ini bisa, tetapi tidak perlu, menjadi kompiler C# itu sendiri.) Output yang dihasilkan oleh pembuat dokumentasi disebut file dokumentasi. File dokumentasi digunakan sebagai input ke penampil dokumentasi; alat yang dimaksudkan untuk menghasilkan semacam tampilan visual informasi jenis dan dokumentasi terkait.

Pengkompilasi C# yang sesuai tidak diperlukan untuk memeriksa sintaks komentar dokumentasi; komentar seperti itu hanya komentar biasa. Namun, pengkompilasi yang sesuai diizinkan untuk melakukan pemeriksaan tersebut.

Spesifikasi ini menyarankan sekumpulan tag standar untuk digunakan dalam komentar dokumentasi, tetapi penggunaan tag ini tidak diperlukan, dan tag lain dapat digunakan jika diinginkan, selama aturan XML yang terbentuk dengan baik diikuti. Untuk implementasi C# yang menargetkan CLI, ia juga menyediakan informasi tentang generator dokumentasi dan format file dokumentasi. Tidak ada informasi yang diberikan tentang penampil dokumentasi.

Pengantar D.2

Komentar yang memiliki bentuk tertentu dapat digunakan untuk mengarahkan alat untuk menghasilkan XML dari komentar tersebut dan elemen kode sumber yang mendahuluinya. Komentar tersebut adalah Single_Line_Comment (§6.3.3) yang dimulai dengan tiga garis miring (///), atau Delimited_Comment (§6.3.3) yang dimulai dengan satu garis miring dan dua bintang (/**). Mereka harus langsung mendahului tipe yang ditentukan oleh pengguna atau anggota yang mereka anotasi. Bagian atribut (§22.3) dianggap sebagai bagian dari deklarasi, sehingga komentar dokumentasi harus mendahului atribut yang diterapkan ke jenis atau anggota.

Untuk tujuan eksposisi, format komentar dokumen ditunjukkan di bawah ini sebagai dua aturan tata bahasa: Single_Line_Doc_Comment dan Delimited_Doc_Comment. Namun, aturan ini bukan bagian dari tata bahasa C#, melainkan mewakili format aturan Single_Line_Comment dan Delimited_Comment lexer tertentu.

Sintaks:

Single_Line_Doc_Comment
    : '///' Input_Character*
    ;
   
Delimited_Doc_Comment
    : '/**' Delimited_Comment_Section* ASTERISK+ '/'
    ;

Dalam Single_Line_Doc_Comment, jika ada karakter Ruang Kosong yang mengikuti karakter /// pada setiap Single_Line_Doc_Comments yang berdekatan dengan Single_Line_Doc_Comment saat ini, maka karakter Ruang Kosong tersebut tidak termasuk dalam keluaran XML.

Dalam Delimited_Doc_Comment, jika karakter non-Spasi Kosong pertama pada baris kedua adalah ASTERISK dan pola karakter Spasi Putih opsional yang sama dan karakter ASTERISK diulang di awal setiap baris dalam Delimited_Doc_Comment, maka karakter pola berulang tidak disertakan dalam output XML. Pola dapat menyertakan karakter Spasi setelah, serta sebelum, karakter ASTERISK.

Contoh:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
    /// <summary>
    /// Method <c>Draw</c> renders the point.
    /// </summary>
    void Draw() {...}
}

Teks dalam komentar dokumentasi harus terbentuk dengan baik sesuai dengan aturan XML (http://www.w3.org/TR/REC-xml). Jika XML salah bentuk, peringatan akan dikeluarkan dan file dokumentasi akan berisi komentar yang mengatakan bahwa terjadi kesalahan.

Meskipun pengembang bebas membuat sekumpulan tag mereka sendiri, set yang direkomendasikan didefinisikan dalam §D.3. Beberapa tag yang direkomendasikan memiliki arti khusus:

• Tag <param> digunakan untuk menjelaskan parameter. Jika tag seperti itu digunakan, generator dokumentasi harus memverifikasi bahwa parameter yang ditentukan ada dan bahwa semua parameter dijelaskan dalam komentar dokumentasi. Jika verifikasi tersebut gagal, generator dokumentasi mengeluarkan peringatan.

• Atribut cref dapat dilampirkan ke tag apa pun untuk memberikan referensi ke elemen kode. Generator dokumentasi harus memverifikasi bahwa elemen kode ini ada. Jika verifikasi gagal, generator dokumentasi mengeluarkan peringatan. Saat mencari nama yang dijelaskan dalam cref atribut, generator dokumentasi harus menghormati visibilitas namespace sesuai dengan menggunakan pernyataan yang muncul dalam kode sumber. Untuk elemen kode yang umum, sintaks umum normal (misalnya, "List<T>") tidak dapat digunakan karena menghasilkan XML yang tidak valid. Kurung kurawal dapat digunakan alih-alih tanda kurung siku (misalnya; "List{T}"), atau sintaks keluar XML dapat digunakan (misalnya, "List<T>").

• Tag <summary> dimaksudkan untuk digunakan oleh penampil dokumentasi untuk menampilkan informasi tambahan tentang jenis atau anggota.

• Tag <include> menyertakan informasi dari file XML eksternal.

Perhatikan dengan cermat bahwa file dokumentasi tidak memberikan informasi lengkap tentang jenis dan anggota (misalnya, file tersebut tidak berisi informasi jenis apa pun). Untuk mendapatkan informasi seperti itu tentang jenis atau anggota, file dokumentasi harus digunakan bersama dengan pantulan pada jenis atau anggota.

Jenis parsial atau metode parsial dapat dideklarasikan dalam beberapa bagian, yang masing-masing dapat berada di satu atau beberapa unit kompilasi, dan masing-masing dapat memiliki satu atau beberapa komentar dokumentasi. Metode parsial biasanya memiliki "mendefinisikan deklarasi parsial" dan "menerapkan deklarasi parsial."

Untuk tipe parsial, komentar dokumen yang berlaku langsung pada tipe tersebut dari setiap bagiannya, semuanya ditulis ke file dokumentasi dalam urutan yang tidak ditentukan.

Untuk metode parsial:

• Jika deklarasi parsial yang mendefinisikan tidak memiliki deklarasi parsial penerapan yang sesuai, setiap komentar dokumentasi dalam deklarasi parsial yang menentukan diabaikan (karena deklarasi tersebut akan dihapus).
• Jika tidak, jika deklarasi parsial yang diimplementasikan memiliki komentar dokumentasi, komentar tersebut akan ditulis ke file dokumentasi, dan komentar dokumentasi apa pun dalam deklarasi parsial yang mendefinisikan diabaikan.
• Jika tidak, setiap komentar dokumentasi pada deklarasi parsial yang mendefinisikan ditulis ke dalam file dokumentasi.

D.3 Tag yang Direkomendasikan

D.3.1 Umum

Generator dokumentasi harus menerima dan memproses tag apa pun yang valid sesuai dengan aturan XML. Tag berikut menyediakan fungsionalitas yang umum digunakan dalam dokumentasi pengguna. (Tentu saja, tag lain dimungkinkan.)

Tag	Referensi	Tujuan
<c>	§D.3.2	Mengatur teks dalam font seperti kode
<code>	§D.3.3	Mengatur satu atau beberapa baris kode sumber atau output program
<example>	§D.3.4	Menunjukkan contoh
<exception>	§D.3.5	Mengidentifikasi pengecualian yang dapat dilemparkan metode
<include>	§D.3.6	Menyertakan XML dari file eksternal
<list>	§D.3.7	Membuat daftar atau tabel
<para>	§D.3.8	Izinkan struktur ditambahkan ke teks
<param>	§D.3.9	Menjelaskan parameter untuk metode atau konstruktor
<paramref>	§D.3.10	Mengidentifikasi bahwa sebuah kata adalah nama parameter
<permission>	§D.3.11	Mendokumentasikan aksesibilitas keamanan anggota
<remarks>	§D.3.12	Menjelaskan informasi tambahan tentang jenis
<returns>	§D.3.13	Menjelaskan nilai pengembalian metode
<see>	§D.3.14	Tentukan tautan
<seealso>	§D.3.15	Membuat entri Lihat Juga
<summary>	§D.3.16	Menggambarkan jenis atau anggota dari suatu tipe
<typeparam>	§D.3.17	Menjelaskan parameter jenis untuk jenis atau metode generik
<typeparamref>	§D.3.18	Mengidentifikasi bahwa kata tersebut adalah nama parameter tipe
<value>	§D.3.19	Deskripsikan properti

D.3.2 <c>

Tag ini menyediakan mekanisme untuk menunjukkan bahwa fragmen teks dalam deskripsi harus diatur dalam font khusus seperti yang digunakan untuk blok kode. Untuk baris kode aktual, gunakan <code> (§D.3.3).

Sintaks:

<c> Teks</c>

Contoh:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
}

Kode D.3.3 <>

Tag ini digunakan untuk mengatur satu atau beberapa baris kode sumber atau output program dalam beberapa font khusus. Untuk fragmen kode kecil dalam narasi, gunakan <c> (§D.3.2).

Sintaks:

<code> kode sumber atau output program</code>

Contoh:

public class Point
{
    /// <summary>
    /// This method changes the point's location by the given x- and y-offsets.
    /// <example>
    /// For example:
    /// <code>
    /// Point p = new Point(3,5);
    /// p.Translate(-1,3);
    /// </code>
    /// results in <c>p</c>'s having the value (2,8).
    /// </example>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

Contoh D.3.4 <>

Tag ini memungkinkan contoh kode dalam komentar, untuk menentukan bagaimana metode atau anggota pustaka lainnya dapat digunakan. Biasanya, ini juga akan melibatkan penggunaan tag <code> (§D.3.3) juga.

Sintaks:

<example> deskripsi</example>

Contoh:

Lihat <code> (§D.3.3) misalnya.

Pengecualian D.3.5 <>

Tag ini menyediakan cara untuk mendokumen pengecualian yang dapat dilemparkan metode.

Sintaks:

<exception cref=" anggota">deskripsi</exception>

di mana

• cref=" anggota" adalah nama anggota. Generator dokumentasi memeriksa bahwa anggota yang diberikan ada dan menerjemahkan anggota ke nama elemen kanonis dalam file dokumentasi.
• deskripsi adalah deskripsi keadaan di mana pengecualian dilemparkan.

Contoh:

class PrimaryFileFormatCorruptException : System.Exception { ... }
class PrimaryFileLockedOpenException : System.Exception { ... }

public class DataBaseOperations
{
    /// <exception cref="PrimaryFileFormatCorruptException">
    /// Thrown when the primary file is corrupted.
    /// </exception>
    /// <exception cref="PrimaryFileLockedOpenException">
    /// Thrown when the primary file is already open.
    /// </exception>
    public static void ReadRecord(int flag)
    {
        if (flag == 1)
        {
            throw new PrimaryFileFormatCorruptException();
        }
        else if (flag == 2)
        {
            throw new PrimaryFileLockedOpenException();
        }
        ...
    }
}

D.3.6 <meliputi>

Tag ini memungkinkan menyertakan informasi dari dokumen XML yang berada di luar file kode sumber. File eksternal harus berupa dokumen XML yang terbentuk dengan baik, dan ekspresi XPath diterapkan ke dokumen tersebut untuk menentukan XML apa dari dokumen yang akan disertakan. Tag <include> kemudian diganti dengan XML yang dipilih dari dokumen eksternal.

Sintaks:

<include file=" nama" path="file xpath" />

di mana

• file=" filename" adalah nama file XML eksternal. Nama file ditafsirkan relatif terhadap file yang berisi tag sertakan.
• path=" xpath" adalah ekspresi XPath yang memilih beberapa XML dalam file XML eksternal.

Contoh:

Jika kode sumber berisi deklarasi seperti:

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { ... }

dan file eksternal "docs.xml" memiliki konten berikut:

<?xml version="1.0"?>
<extradoc>
    <class name="IntList">
        <summary>
            Contains a list of integers.
        </summary>
    </class>
    <class name="StringList">
        <summary>
            Contains a list of strings.
        </summary>
    </class>
</extradoc>

maka dokumentasi yang sama akan dihasilkan sebagai jika kode sumber mengandung:

/// <summary>
/// Contains a list of integers.
/// </summary>
public class IntList { ... }

Daftar D.3.7 <>

Tag ini digunakan untuk membuat daftar atau tabel item. Ini dapat berisi <listheader> blok untuk menentukan baris judul tabel atau daftar definisi. (Saat menentukan tabel, hanya entri untuk istilah dalam judul yang perlu disediakan.)

Setiap item dalam daftar ditentukan dengan blok <item>. Saat membuat daftar definisi, istilah dan deskripsi harus ditentukan. Namun, untuk tabel, daftar berpoin, atau daftar bernomor, hanya deskripsi yang perlu ditentukan.

Sintaks:

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
    ...
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

di mana

• istilah adalah istilah untuk mendefinisikan, yang definisinya dalam deskripsi.
• deskripsi adalah item dalam daftar poin atau bernomor, atau definisi istilah.

Contoh:

public class MyClass
{
    /// <summary>Here is an example of a bulleted list:
    /// <list type="bullet">
    /// <item>
    /// <description>Item 1.</description>
    /// </item>
    /// <item>
    /// <description>Item 2.</description>
    /// </item>
    /// </list>
    /// </summary>
    public static void Main()
    {
        ...
    }
}

D.3.8 <para>

Tag ini untuk digunakan di dalam tag lain, seperti <summary> (§D.3.16) atau <returns> (§D.3.13), dan mengizinkan struktur ditambahkan ke teks.

Sintaks:

<para> konten</para>

di mana

• konten adalah teks paragraf.

Contoh:

public class Point
{
    /// <summary>This is the entry point of the Point class testing program.
    /// <para>
    /// This program tests each method and operator, and
    /// is intended to be run after any non-trivial maintenance has
    /// been performed on the Point class.
    /// </para>
    /// </summary>
    public static void Main() 
    {
        ...
    }
}

D.3.9 <param>

Tag ini digunakan untuk menjelaskan parameter untuk metode, konstruktor, atau pengindeks.

Sintaks:

<param name=" nama">deskripsi</param>

di mana

• nama adalah nama parameter.
• deskripsi adalah deskripsi parameter.

Contoh:

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates.
    /// </summary>
    /// <param name="xPosition">the new x-coordinate.</param>
    /// <param name="yPosition">the new y-coordinate.</param>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
}

D.3.10 <paramref>

Tag ini digunakan untuk menunjukkan bahwa kata adalah parameter. File dokumentasi dapat diproses untuk memformat parameter ini dengan beberapa cara yang berbeda.

Sintaks:

<paramref name=" nama"/>

di mana

• nama adalah nama parameter.

Contoh:

public class Point
{
    /// <summary>This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    /// <param name="xPosition">the new Point's x-coordinate.</param>
    /// <param name="yPosition">the new Point's y-coordinate.</param>
    public Point(int xPosition, int yPosition)
    {
        ...
    }
}

Izin D.3.11 <>

Tag ini memungkinkan aksesibilitas keamanan anggota untuk didokumentasikan.

Sintaks:

<permission cref=" anggota">deskripsi</permission>

di mana

• anggota adalah nama anggota. Generator dokumentasi memeriksa bahwa elemen kode yang diberikan ada dan menerjemahkan anggota ke nama elemen kanonis dalam file dokumentasi.
• deskripsi adalah deskripsi akses ke anggota.

Contoh:

public class MyClass
{
    /// <permission cref="System.Security.PermissionSet">
    /// Everyone can access this method.
    /// </permission>
    public static void Test()
    {
        ...
    }
}

Komentar D.3.12 <>

Tag ini digunakan untuk menentukan informasi tambahan tentang jenis. Gunakan <summary> (§D.3.16) untuk menjelaskan jenis itu sendiri dan anggota jenis.

Sintaks:

<remarks> deskripsi</remarks>

di mana

• deskripsi adalah teks keterangan.

Contoh:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
/// <remarks>
/// Uses polar coordinates
/// </remarks>
public class Point
{
    ...
}

D.3.13 <mengembalikan>

Tag ini digunakan untuk menjelaskan nilai pengembalian metode.

Sintaks:

<returns> deskripsi</returns>

di mana

• deskripsi adalah deskripsi nilai yang dikembalikan.

Contoh:

public class Point
{
    /// <summary>
    /// Report a point's location as a string.
    /// </summary>
    /// <returns>
    /// A string representing a point's location, in the form (x,y),
    /// without any leading, trailing, or embedded whitespace.
    /// </returns>
    public override string ToString() => $"({X},{Y})";
    public int X { get; set; }
    public int Y { get; set; }
}

D.3.14 <lihat>

Tag ini memungkinkan tautan ditentukan dalam teks. Gunakan <seealso> (§D.3.15) untuk menunjukkan teks yang akan muncul di subklaus Lihat Juga .

Sintaks:

<see cref=" anggota" href="url" langword="kata kunci" />

di mana

• anggota adalah nama anggota. Generator dokumentasi memeriksa bahwa elemen kode yang diberikan ada dan mengubah anggota ke nama elemen dalam file dokumentasi yang dihasilkan.
• url adalah referensi ke sumber eksternal.
• Langword adalah sebuah kata yang perlu disorot dengan cara tertentu.

Contoh:

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates. <see cref="Translate"/>
    /// </summary>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
    /// <summary>This method changes the point's location by
    /// the given x- and y-offsets. <see cref="Move"/>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.15 <lihat juga>

Tag ini memungkinkan sebuah entri dihasilkan untuk subklaus Lihat Juga. Gunakan <see> (§D.3.14) untuk menentukan tautan dari dalam teks.

Sintaks:

<seealso cref=" anggota" href="url" />

di mana

• anggota adalah nama anggota. Generator dokumentasi memeriksa bahwa elemen kode yang diberikan ada dan mengubah anggota ke nama elemen dalam file dokumentasi yang dihasilkan.
• url adalah referensi ke sumber eksternal.

Contoh:

public class Point
{
    /// <summary>
    /// This method determines whether two Points have the same location.
    /// </summary>
    /// <seealso cref="operator=="/>
    /// <seealso cref="operator!="/>
    public override bool Equals(object o)
    {
        ...
    }
}

D.3.16 Ringkasan <>

Tag ini dapat digunakan untuk menjelaskan jenis atau anggota tipe. Gunakan <remarks> (§D.3.12) untuk menentukan informasi tambahan tentang jenis atau anggota.

Sintaks:

<summary> deskripsi</summary>

di mana

• deskripsi adalah ringkasan jenis atau anggota.

Contoh:

public class Point
{

    /// <summary>
    /// This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    public Point(int xPosition, int yPosition) 
    {
        ...
    }

    /// <summary>This constructor initializes the new Point to (0,0).</summary>
    public Point() : this(0, 0)
    {
    }
}

D.3.17 <typeparam>

Tag ini digunakan untuk menjelaskan parameter jenis untuk jenis atau metode generik.

Sintaks:

<typeparam name=" nama">deskripsi</typeparam>

di mana

• nama adalah nama parameter jenis.
• deskripsi adalah deskripsi parameter jenis.

Contoh:

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T>
{
   ...
}

D.3.18 <typeparamref>

Tag ini digunakan untuk menunjukkan bahwa kata adalah parameter jenis. File dokumentasi dapat diproses untuk memformat parameter jenis ini dengan beberapa cara yang berbeda.

Sintaks:

<typeparamref name=" nama"/>

di mana

• nama adalah nama parameter jenis.

Contoh:

public class MyClass
{
    /// <summary>
    /// This method fetches data and returns a list of
    /// <typeparamref name="T"/>.
    /// </summary>
    /// <param name="query">query to execute</param>
    public List<T> FetchData<T>(string query)
    {
        ...
    }
}

D.3.19 <Nilai>

Tag ini memungkinkan Anda untuk menjelaskan sebuah properti.

Sintaks:

<value> deskripsi properti</value>

di mana

• deskripsi properti memberikan informasi tentang properti tersebut.

Contoh:

public class Point
{
    /// <value>Property <c>X</c> represents the point's x-coordinate.</value>
    public int X { get; set; }
}

D.4 Memproses file dokumentasi

D.4.1 Umum

Informasi berikut ditujukan untuk implementasi C# yang menargetkan CLI.

Generator dokumentasi menghasilkan string ID untuk setiap elemen dalam kode sumber yang ditandai dengan komentar dokumentasi. String ID ini secara unik mengidentifikasi elemen sumber. Penampil dokumentasi dapat menggunakan string ID untuk mengidentifikasi item terkait tempat dokumentasi diterapkan.

File dokumentasi bukan representasi hierarkis dari kode sumber; sebaliknya, ini adalah daftar datar dengan string ID yang dihasilkan untuk setiap elemen.

Format string ID D.4.2

Generator dokumentasi mengamati aturan berikut saat menghasilkan string ID:

• Tidak ada spasi kosong dalam string.

• Bagian pertama dari string mengidentifikasi jenis anggota yang didokumentasikan, melalui satu karakter diikuti oleh titik dua. Jenis anggota berikut didefinisikan:

  karakter	Keterangan
  E	Kejadian
  F	Bidang
  M	Metode (termasuk konstruktor, finalizer, dan operator)
  N	Ruang nama
  P	Properti (termasuk pengindeks)
  T	Jenis (seperti kelas, delegasi, enum, antarmuka, dan struktur)
  !	String kesalahan; string lainnya menyediakan informasi tentang kesalahan. Misalnya, generator dokumentasi menghasilkan informasi kesalahan untuk tautan yang tidak dapat diselesaikan.

• Bagian kedua dari string adalah nama elemen yang berkualifikasi penuh, dimulai dari akar namespace. Nama elemen, jenis yang mengapitnya, dan namespace dipisahkan oleh titik. Jika nama item itu sendiri memiliki titik, titik-titik tersebut digantikan oleh karakter # (U+0023). (Diasumsikan bahwa tidak ada elemen yang memiliki karakter ini dalam namanya.) Ketik argumen dalam nama yang memenuhi syarat sepenuhnya, ketika anggota secara eksplisit mengimplementasikan anggota dari antarmuka generik, dikodekan dengan mengganti karakter "<" dan ">" yang mengelilinginya menjadi karakter "{" dan "}".

• Untuk metode dan properti dengan argumen, daftar argumen ditempatkan setelahnya dalam tanda kurung. Untuk mereka yang tanpa argumen, tanda kurung dihilangkan. Argumen dipisahkan oleh koma. Pengodean setiap argumen sama dengan tanda tangan CLI, sebagai berikut:

  • Argumen diwakili oleh nama dokumentasinya, yang didasarkan pada nama yang sepenuhnya memenuhi syarat, dimodifikasi sebagai berikut:
    • Argumen yang mewakili jenis generik memiliki karakter "'" yang ditambahkan diikuti dengan jumlah parameter jenis
    • Argumen yang memiliki pengubah in, out, atau ref memiliki nama jenis @ di belakangnya. Argumen yang diteruskan oleh nilai atau melalui params tidak memiliki notasi khusus.
    • Argumen yang merupakan array direpresentasikan sebagai [batas bawah:ukuran, ... , hilir:tingginya] di mana jumlah koma adalah peringkat kurang satu, dan batas dan ukuran yang lebih rendah dari setiap dimensi, jika diketahui, diwakili dalam desimal. Jika batas atau ukuran yang lebih rendah tidak ditentukan, maka akan dihilangkan. Jika batas dan ukuran yang lebih rendah untuk dimensi tertentu dihilangkan, ":" juga dihilangkan. Array jagged diwakili oleh satu "[]" per tingkat. Larik berdimensi tunggal menghilangkan batas bawah saat batas bawah adalah 0 (nilai default) (§17,1).
    • Argumen yang memiliki tipe penunjuk selain void diwakili menggunakan * nama jenis berikut. void Penunjuk diwakili menggunakan nama jenis System.Void.
    • Argumen yang merujuk ke parameter jenis generik yang ditentukan pada jenis dikodekan menggunakan karakter "`" diikuti oleh indeks berbasis nol dari parameter jenis.
    • Argumen yang menggunakan parameter tipe generik yang ditentukan dalam metode menggunakan backtick ganda "``" alih-alih "`" yang digunakan untuk tipe.
    • Argumen yang merujuk ke jenis generik yang dibangun dikodekan menggunakan jenis generik, diikuti oleh "{", diikuti oleh daftar argumen jenis yang dipisahkan koma, diikuti oleh "}".

Contoh string pengenal D.4.3

Contoh berikut masing-masing menunjukkan fragmen kode C#, bersama dengan string ID yang dihasilkan dari setiap elemen sumber yang mampu memiliki komentar dokumentasi:

Jenis diwakili menggunakan nama mereka yang sepenuhnya memenuhi syarat, dilengkapi dengan informasi generik:

enum Color { Red, Blue, Green }

namespace Acme
{
    interface IProcess { ... }

    struct ValueType { ... }

    class Widget : IProcess
    {
        public class NestedClass { ... }
        public interface IMenuItem { ... }
        public delegate void Del(int i);
        public enum Direction { North, South, East, West }
    }

    class MyList<T>
    {
        class Helper<U,V> { ... }
    }
}

Id:

"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"
"T:Acme.MyList`1"
"T:Acme.MyList`1.Helper`2"

Bidang diwakili oleh nama lengkap secara spesifik.

namespace Acme
{
    struct ValueType
    {
        private int total;
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            private int value;
        }

        private string message;
        private static Color defaultColor;
        private const double PI = 3.14159;
        protected readonly double monthlyAverage;
        private long[] array1;
        private Widget[,] array2;
        private unsafe int *pCount;
        private unsafe float **ppValues;
    }
}

Id:

"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"
"F:Acme.Widget.pCount"
"F:Acme.Widget.ppValues"

Konstruktor

namespace Acme
{
    class Widget : IProcess
    {
        static Widget() { ... }
        public Widget() { ... }
        public Widget(string s) { ... }
    }
}

Id:

"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"

Penyelesai

namespace Acme
{
    class Widget : IProcess
    {
        ~Widget() { ... }
    }
}

Id:

"M:Acme.Widget.Finalize"

Metode

namespace Acme
{
    struct ValueType
    {
        public void M(int i) { ... }
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            public void M(int i) { ... }
        }

        public static void M0() { ... }
        public void M1(char c, out float f, ref ValueType v, in int i) { ... }
        public void M2(short[] x1, int[,] x2, long[][] x3) { ... }
        public void M3(long[][] x3, Widget[][,,] x4) { ... }
        public unsafe void M4(char *pc, Color **pf) { ... }
        public unsafe void M5(void *pv, double *[][,] pd) { ... }
        public void M6(int i, params object[] args) { ... }
    }

    class MyList<T>
    {
        public void Test(T t) { ... }
    }

    class UseList
    {
        public void Process(MyList<int> list) { ... }
        public MyList<T> GetValues<T>(T value) { ... } 
    }
}

Id:

"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@,System.Int32@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Char*,Color**)"
"M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
"M:Acme.Widget.M6(System.Int32,System.Object[])"
"M:Acme.MyList`1.Test(`0)"
"M:Acme.UseList.Process(Acme.MyList{System.Int32})"
"M:Acme.UseList.GetValues``1(``0)"

Properti dan pengindeks

namespace Acme
{
    class Widget : IProcess
    {
        public int Width { get { ... } set { ... } }
        public int this[int i] { get { ... } set { ... } }
        public int this[string s, int i] { get { ... } set { ... } }
    }
}

Id:

"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"

Peristiwa

namespace Acme
{
    class Widget : IProcess
    {
        public event Del AnEvent;
    }
}

Id:

"E:Acme.Widget.AnEvent"

Operator unary

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x) { ... }
    }
}

Id:

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"

Kumpulan lengkap nama fungsi operator unary yang digunakan adalah sebagai berikut: op_UnaryPlus, , op_UnaryNegation, op_LogicalNot, op_OnesComplementop_Increment, op_Decrement, op_True, dan op_False.

Operator biner

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x1, Widget x2) { ... }
    }
}

Id:

"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"

Kumpulan lengkap nama fungsi operator biner yang digunakan adalah sebagai berikut: op_Addition, op_Subtractionop_Multiply, op_Division, op_Modulusop_BitwiseAndop_BitwiseOrop_ExclusiveOrop_LeftShift, op_RightShift, op_Equality, op_Inequality, , op_LessThan, , op_LessThanOrEqual, , op_GreaterThandan .op_GreaterThanOrEqual

Operator konversi diikuti "~" diikuti oleh tipe pengembalian. Ketika sumber atau tujuan operator konversi adalah jenis generik, karakter "<" dan "">" digantikan oleh karakter "{" dan ""}, masing-masing.

namespace Acme
{
    class Widget : IProcess
    {
        public static explicit operator int(Widget x) { ... }
        public static implicit operator long(Widget x) { ... }
    }
}

Id:

"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"

D.5 Contoh

Kode sumber D.5.1 C#

Contoh berikut menunjukkan kode sumber kelas Titik:

namespace Graphics
{
    /// <summary>
    /// Class <c>Point</c> models a point in a two-dimensional plane.
    /// </summary>
    public class Point
    {
        /// <value>
        /// Property <c>X</c> represents the point's x-coordinate.
        /// </value>
        public int X { get; set; }
        
        /// <value>
        /// Property <c>Y</c> represents the point's y-coordinate.
        /// </value>
        public int Y { get; set; }
        
        /// <summary>
        /// This constructor initializes the new Point to (0,0).
        /// </summary>
        public Point() : this(0, 0) {}
        
        /// <summary>
        /// This constructor initializes the new Point to
        /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
        /// </summary>
        /// <param name="xPosition">The new Point's x-coordinate.</param>
        /// <param name="yPosition">The new Point's y-coordinate.</param>
        public Point(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's location to
        /// the given coordinates. <see cref="Translate"/>
        /// </summary>
        /// <param name="xPosition">The new x-coordinate.</param>
        /// <param name="yPosition">The new y-coordinate.</param>
        public void Move(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's location by
        /// the given x- and y-offsets.
        /// <example>For example:
        /// <code>
        /// Point p = new Point(3, 5);
        /// p.Translate(-1, 3);
        /// </code>
        /// results in <c>p</c>'s having the value (2, 8).
        /// <see cref="Move"/>
        /// </example>
        /// </summary>
        /// <param name="dx">The relative x-offset.</param>
        /// <param name="dy">The relative y-offset.</param>
        public void Translate(int dx, int dy)
        {
            X += dx;
            Y += dy;
        }
        
        /// <summary>
        /// This method determines whether two Points have the same location.
        /// </summary>
        /// <param name="o">
        /// The object to be compared to the current object.
        /// </param>
        /// <returns>
        /// True if the Points have the same location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="operator=="/>
        /// <seealso cref="operator!="/>
        public override bool Equals(object o)
        {
            if (o == null)
            {
                return false;
            }
            if ((object)this == o) 
            {
                return true;
            }
            if (GetType() == o.GetType()) 
            {
                Point p = (Point)o;
                return (X == p.X) && (Y == p.Y);
            }
            return false;
        }

        /// <summary>
        /// This method returns a Point's hashcode.
        /// </summary>
        /// <returns>
        /// The int hashcode.
        /// </returns>
        public override int GetHashCode()
        {
            return X + (Y >> 4);    // a crude version
        }
        
        /// <summary>Report a point's location as a string.</summary>
        /// <returns>
        /// A string representing a point's location, in the form (x,y),
        /// without any leading, training, or embedded whitespace.
        /// </returns>
        public override string ToString() => $"({X},{Y})";
        
        /// <summary>
        /// This operator determines whether two Points have the same location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points have the same location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator!="/>
        public static bool operator==(Point p1, Point p2)
        {
            if ((object)p1 == null || (object)p2 == null)
            {
                return false;
            }
            if (p1.GetType() == p2.GetType())
            {
                return (p1.X == p2.X) && (p1.Y == p2.Y);
            }
            return false;
        }
        
        /// <summary>
        /// This operator determines whether two Points have the same location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points do not have the same location and the
        /// exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator=="/>
        public static bool operator!=(Point p1, Point p2) => !(p1 == p2);
    }
}

D.5.2 XML yang Dihasilkan

Berikut adalah output yang dihasilkan oleh satu generator dokumentasi ketika diberikan kode sumber untuk kelas Point, yang ditunjukkan di atas:

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>Point</name>
  </assembly>
  <members>
    <member name="T:Graphics.Point">
    <summary>Class <c>Point</c> models a point in a two-dimensional
    plane.
    </summary>
    </member>
    <member name="M:Graphics.Point.#ctor">
      <summary>This constructor initializes the new Point to (0, 0).</summary>
    </member>
    <member name="M:Graphics.Point.#ctor(System.Int32,System.Int32)">
      <summary>
        This constructor initializes the new Point to
        (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
      </summary>
      <param name="xPosition">The new Point's x-coordinate.</param>
      <param name="yPosition">The new Point's y-coordinate.</param>
    </member>
    <member name="M:Graphics.Point.Move(System.Int32,System.Int32)">
      <summary>
        This method changes the point's location to
        the given coordinates.
        <see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
      </summary>
      <param name="xPosition">The new x-coordinate.</param>
      <param name="yPosition">The new y-coordinate.</param>
      </member>
    <member name="M:Graphics.Point.Translate(System.Int32,System.Int32)">
      <summary>
        This method changes the point's location by
        the given x- and y-offsets.
        <example>For example:
        <code>
        Point p = new Point(3,5);
        p.Translate(-1,3);
        </code>
        results in <c>p</c>'s having the value (2,8).
        </example>
        <see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
      </summary>
      <param name="dx">The relative x-offset.</param>
      <param name="dy">The relative y-offset.</param>
    </member>
    <member name="M:Graphics.Point.Equals(System.Object)">
      <summary>
        This method determines whether two Points have the same location.
      </summary>
      <param name="o">
        The object to be compared to the current object.
      </param>
      <returns>
        True if the Points have the same location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso 
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)" />
      <seealso 
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
     <member name="M:Graphics.Point.ToString">
      <summary>
        Report a point's location as a string.
      </summary>
      <returns>
        A string representing a point's location, in the form (x,y),
        without any leading, training, or embedded whitespace.
      </returns>
     </member>
    <member name="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points have the same location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
    <member
        name="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points do not have the same location and the
        exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
      </member>
      <member name="M:Graphics.Point.Main">
        <summary>
          This is the entry point of the Point class testing program.
          <para>
            This program tests each method and operator, and
            is intended to be run after any non-trivial maintenance has
            been performed on the Point class.
          </para>
        </summary>
      </member>
      <member name="P:Graphics.Point.X">
        <value>
          Property <c>X</c> represents the point's x-coordinate.
        </value>
      </member>
      <member name="P:Graphics.Point.Y">
        <value>
          Property <c>Y</c> represents the point's y-coordinate.
        </value>
    </member>
  </members>
</doc>

Akhir teks informatif.