付属書 D ドキュメントのコメント

[アーティクル]
11/21/2024

この付属書は有益です。

D.1 全般

C# には、プログラマが XML テキストを含むコメント構文を使用してコードを文書化するためのメカニズムが用意されています。ソースコードファイルでは、特定の形式を持つコメントを使用して、これらのコメントとソースコード要素から XML を生成するようにツールに指示できます。前に記述したソースコード要素を使用します。このような構文を使用するコメントは、 documentation コメントと呼ばれます。ユーザー定義型 (クラス、デリゲート、インターフェイスなど) またはメンバー (フィールド、イベント、プロパティ、メソッドなど) の直前に置く必要があります。 XML 生成ツールは、 documentation ジェネレーターと呼ばれます。 (このジェネレーターは、C# コンパイラ自体である可能性がありますが、必要ありません)。ドキュメントジェネレーターによって生成される出力は、 documentation ファイルと呼ばれます。ドキュメントファイルは、 documentation viewer; 型情報とそれに関連するドキュメントの視覚的な表示を生成するためのツールへの入力として使用されます。

準拠している C# コンパイラは、ドキュメントコメントの構文を確認する必要はありません。このようなコメントは、単なる通常のコメントです。ただし、準拠コンパイラはこのようなチェックを行うことができます。

この仕様では、ドキュメントコメントで使用する一連の標準タグが提案されていますが、これらのタグの使用は必要ありません。また、適切な形式の XML の規則に従っている限り、必要に応じて他のタグを使用できます。 CLI を対象とする C# 実装の場合は、ドキュメントジェネレーターとドキュメントファイルの形式に関する情報も提供します。ドキュメントビューアーに関する情報は提供されません。

D.2 概要

特定のフォームを持つコメントを使用して、それらのコメントと、その前のソースコード要素から XML を生成するようにツールを指示できます。このようなコメントは、3 つのスラッシュ (///) で始まるSingle_Line_Comment (§6.3.3)、またはスラッシュと 2 つのアスタリスク (/**) で始まるDelimited_Comment (§6.3.3) です。ユーザー定義型または注釈を付けるメンバーの直前に置く必要があります。属性セクション (§22.3) は宣言の一部と見なされるため、ドキュメントコメントは型またはメンバーに適用される属性の前に記述する必要があります。

公開を目的として、ドキュメントコメントの形式は、 Single_Line_Doc_Comment と Delimited_Doc_Commentの 2 つの文法規則として以下に示されています。ただし、これらの規則は C# 文法の一部ではなく、それぞれ特定の形式のSingle_Line_CommentとDelimited_Comment lexer 規則を表します。

構文：

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

Single_Line_Doc_Commentで、現在のSingle_Line_Doc_Commentに隣接する各Single_Line_Doc_Commentsの///文字の後に Whitespace 文字がある場合、そのWhitespace文字は XML 出力に含まれません。

Delimited_Doc_Commentでは、2 行目の最初の非Whitespace文字が ASTERISK 省略可能な Whitespace 文字と ASTERISK 文字の同じパターンがDelimited_Doc_Comment内の各行の先頭で繰り返される場合、繰り返されるパターンの文字は XML 出力に含まれません。パターンには、ASTERISK 文字の後にWhitespace文字を含めることができます。

例:

/// <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() {...}
}

ドキュメントコメント内のテキストは、XML (http://www.w3.org/TR/REC-xml) の規則に従って整形式である必要があります。 XML の形式が正しくありません。警告が生成され、エラーが発生したことを示すコメントがドキュメントファイルに含まれます。

開発者は独自のタグセットを自由に作成できますが、推奨セットは §D.3で定義されています。推奨されるタグの一部には特別な意味があります。

<param> タグは、パラメーターの記述に使用します。このようなタグを使用する場合、ドキュメントジェネレーターは、指定されたパラメーターが存在し、すべてのパラメーターがドキュメントコメントに記述されていることを確認する必要があります。このような検証が失敗した場合、ドキュメントジェネレーターは警告を発行します。
cref 属性は任意のタグにアタッチでき、コード要素への参照を提供します。ドキュメントジェネレーターは、このコード要素が存在することを確認する必要があります。検証が失敗した場合、ドキュメントジェネレーターは警告を発行します。 cref属性で説明されている名前を探す場合、ドキュメントジェネレーターは、ソースコード内に表示される using ステートメントに従って名前空間の可視性を考慮する必要があります。ジェネリックであるコード要素の場合、通常のジェネリック構文 (例: "List<T>") は無効な XML を生成するため使用できません。かっこの代わりに中かっこを使用できます (例:"List{T}")、または XML エスケープ構文 (例: "List<T>") を使用できます。
<summary> タグは、ドキュメントビューアーが型またはメンバーに関する追加情報を表示するために使用することを目的としています。
<include> タグには、外部 XML ファイルからの情報が含まれています。

ドキュメントファイルでは、型とメンバーに関する完全な情報が提供されないことに注意してください (たとえば、型情報は含まれません)。型またはメンバーに関するこのような情報を取得するには、ドキュメントファイルを型またはメンバーのリフレクションと組み合わせて使用する必要があります。

D.3 推奨タグ

D.3.1 全般

ドキュメントジェネレーターは、XML の規則に従って有効なタグを受け入れて処理する必要があります。次のタグによって、ユーザードキュメントで一般的に使用される機能が与えられます。 (もちろん、他のタグも可能です。

Tag	リファレンス	目的
`<c>`	§D.3.2	コードに似たフォントでテキストを設定する
`<code>`	§D.3.3	1 行以上のソースコードまたはプログラム出力を設定する
`<example>`	§D.3.4	例を示す
`<exception>`	§D.3.5	メソッドがスローできる例外を識別します
`<include>`	§D.3.6	外部ファイルの XML を含む
`<list>`	§D.3.7	リストまたはテーブルを作成する
`<para>`	§D.3.8	テキストに構造体を追加することを許可する
`<param>`	§D.3.9	メソッドまたはコンストラクターのパラメーターを記述する
`<paramref>`	§D.3.10	単語がパラメーター名であることを識別する
`<permission>`	§D.3.11	メンバーのセキュリティアクセシビリティを文書化する
`<remarks>`	§D.3.12	型に関する追加情報について説明する
`<returns>`	§D.3.13	メソッドの戻り値について説明する
`<see>`	§D.3.14	リンクを指定する
`<seealso>`	§D.3.15	See Also エントリを生成する
`<summary>`	§D.3.16	型または型のメンバーを記述する
`<typeparam>`	§D.3.17	ジェネリック型またはメソッドの型パラメーターを記述する
`<typeparamref>`	§D.3.18	単語が型パラメーター名であることを識別する
`<value>`	§D.3.19	プロパティの説明

D.3.2 <c>

このタグは、説明内のテキストのフラグメントを、コードブロックに使用される特殊なフォントで設定する必要があることを示すメカニズムを提供します。実際のコード行には、 <code> (§D.3.3) を使用します。

構文：

<c>text</c>

例:

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

D.3.3 <code>

このタグは、1 行以上のソースコードまたはプログラム出力を特別なフォントで設定するために使用されます。物語の小さなコードフラグメントの場合は、 <c> (§D.3.2) を使用します。

構文：

<code>ソースコードまたはプログラムの出力</code>

例:

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)
    {
        ...
    }
}

D.3.4 <example>

このタグを使用すると、コメント内のコード例を使用して、メソッドまたは他のライブラリメンバーの使用方法を指定できます。通常、これにはタグ <code> (§D.3.3) も使用されます。

構文：

<example>説明</example>

例:

例については、 <code> (§D.3.3) を参照してください。

D.3.5 <exception>

このタグは、メソッドがスローできる例外を文書化する方法を提供します。

構文：

<exception cref="member">description</exception>

where

cref="member" はメンバーの名前です。ドキュメントジェネレーターは、指定されたメンバーが存在することを確認し、 member ドキュメントファイル内の正規の要素名に変換します。
description は、例外がスローされる状況の説明です。

例:

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 <組み込み>

このタグを使用すると、ソースコードファイルの外部にある XML ドキュメントからの情報を含むことができます。外部ファイルは整形式の XML ドキュメントである必要があり、XPath 式をそのドキュメントに適用して、そのドキュメントから含める XML を指定します。 <include> タグは、外部ドキュメントから選択した XML に置き換えられます。

構文：

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

where

file="filename" は外部 XML ファイルのファイル名です。ファイル名は、インクルードタグを含むファイルを基準にして解釈されます。
path="xpath" は、外部 XML ファイル内の XML の一部を選択する XPath 式です。

例:

ソースコードに次のような宣言が含まれている場合:

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

外部ファイル "docs.xml" には次の内容が含まれています。

<?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>

ソースコードに含まれている場合と同じドキュメントが出力されます。

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

D.3.7 <list>

このタグは、アイテムのリストまたはテーブルを作成するために使用されます。テーブルまたは定義リストの見出し行を定義する <listheader> ブロックを含めることができます。 (テーブルを定義する場合は、見出しに term のエントリのみを指定する必要があります)。

リストの各項目は、<item> ブロックで指定されます。定義リストを作成するときは、 term と description の両方を指定する必要があります。ただし、テーブル、箇条書き、または番号付きリストの場合は、説明のみを指定する必要があります。

構文：

<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>

where

term は定義する用語であり、その定義は 説明にあります。
description は、箇条書きまたは段落番号の項目、または term の定義です。

例:

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>

このタグは、 <summary> (§D.3.16) や <returns> (§D.3.13) などの他のタグ内で使用するために使用され、構造をテキストに追加できます。

構文：

<para>content</para>

where

content は段落のテキストです。

例:

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>

このタグは、メソッド、コンストラクター、またはインデクサーのパラメーターを記述するために使用されます。

構文：

<param name="名前">説明</param>

where

name はパラメーターの名前です。
description はパラメーターの説明です。

例:

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>

このタグは、単語がパラメーターであることを示すために使用されます。ドキュメントファイルは、このパラメーターを別の方法で書式設定するために処理できます。

構文：

<paramref name="name"/>

where

name はパラメーターの名前です。

例:

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)
    {
        ...
    }
}

D.3.11 <permission>

このタグを使用すると、メンバーのセキュリティアクセシビリティを文書化できます。

構文：

<permission cref="member">description</permission>

where

member はメンバーの名前です。ドキュメントジェネレーターは、指定されたコード要素が存在することを確認し、 member ドキュメントファイル内の正規の要素名に変換します。
description は、メンバーへのアクセスの説明です。

例:

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

D.3.12 <remarks>

このタグは、型に関する追加情報を指定するために使用されます。 <summary> (§D.3.16) を使用して、型自体と型のメンバーを記述します。

構文：

<remarks>説明</remarks>

where

description は解説のテキストです。

例:

/// <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 <ターン>

このタグは、メソッドの戻り値を記述するために使用されます。

構文：

<returns>説明</returns>

where

description は戻り値の説明です。

例:

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 <see>

このタグを使用すると、テキスト内でリンクを指定できます。 <seealso> (§D.3.15) を使用して、See Also サブ文書に表示されるテキストを指定します。

構文：

<see cref="member" href="url" langword="keyword" />

where

member はメンバーの名前です。ドキュメントジェネレーターは、指定されたコード要素が存在することを確認し、 member 生成されたドキュメントファイル内の要素名に変更します。
url は外部ソースへの参照です。
langword は何とか強調される単語です。

例:

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 <seealso>

このタグを使用すると、 See Also サブクラスのエントリを生成できます。テキスト内からリンクを指定するには、 <see> (§D.3.14) を使用します。

構文：

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

where

member はメンバーの名前です。ドキュメントジェネレーターは、指定されたコード要素が存在することを確認し、 member 生成されたドキュメントファイル内の要素名に変更します。
url は外部ソースへの参照です。

例:

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 <日>

このタグは、型または型のメンバーを記述するために使用できます。 <remarks> (§D.3.12) を使用して、型またはメンバーに関する追加情報を指定します。

構文：

<summary>説明</summary>

where

description は、型またはメンバーの概要です。

例:

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>

このタグは、ジェネリック型またはメソッドの型パラメーターを記述するために使用されます。

構文：

<typeparam name="名前">説明</typeparam>

where

name は型パラメーターの名前です。
description 型パラメーターの説明です。

例:

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

D.3.18 <typeparamref>

このタグは、単語が型パラメーターであることを示すために使用されます。ドキュメントファイルを処理して、この型パラメーターを別の方法で書式設定できます。

構文：

<typeparamref name="name"/>

where

name は型パラメーターの名前です。

例:

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 <value>

このタグを使用すると、プロパティを記述できます。

構文：

<value>プロパティの説明</value>

where

property description プロパティの説明です。

例:

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

D.4 ドキュメントファイルの処理

D.4.1 全般

次の情報は、CLI を対象とする C# 実装を対象としています。

ドキュメントジェネレーターは、ドキュメントコメントでタグ付けされたソースコード内の各要素の ID 文字列を生成します。この ID 文字列は、ソース要素を一意に識別します。ドキュメントビューアーでは、ID 文字列を使用して、ドキュメントが適用される対応する項目を識別できます。

ドキュメントファイルは、ソースコードの階層的な表現ではありません。むしろ、各要素に対して生成されたID文字列を持つフラットリストです。

D.4.2 ID 文字列形式

ドキュメントジェネレーターは、ID 文字列を生成するときに次の規則を観察します。

文字列に空白は配置されません。

文字列の最初の部分では、1 文字の後にコロンを使用して、文書化されるメンバーの種類を識別します。次の種類のメンバーが定義されています。

文字	説明
E	Event
F	フィールド
月	メソッド (コンストラクター、ファイナライザー、演算子を含む)
N	名前空間
P	プロパティ (インデクサーを含む)
T	型 (クラス、デリゲート、列挙型、インターフェイス、構造体など)
!	エラー文字列。残りの文字列はエラーに関する情報を提供します。たとえば、ドキュメントジェネレーターは、解決できないリンクのエラー情報を生成します。

文字列の 2 番目の部分は、名前空間のルートから始まる要素の完全修飾名です。要素の名前、その外側の型、および名前空間はピリオドで区切られます。項目自体の名前にピリオドがある場合は、#(U+0023) 文字に置き換えられます。 (この名前にこの文字を持つ要素はないと想定されます)。メンバーがジェネリックインターフェイスのメンバーを明示的に実装する場合の完全修飾名の型引数は、"<" および ">" を囲む "{" 文字と "}" 文字に置き換えることによってエンコードされます。
引数を持つメソッドとプロパティの場合、引数リストはかっこで囲まれた後に続きます。引数を指定しない場合、かっこは省略されます。引数はコンマで区切られます。各引数のエンコードは、次のように CLI 署名と同じです。
- 引数は、完全修飾名に基づくドキュメント名で表され、次のように変更されます。
  - ジェネリック型を表す引数には、"'" 文字が追加され、その後に型パラメーターの数が続きます。
  - in、out、またはref修飾子を持つ引数には、型名の後に@があります。値または params を介して渡される引数には、特別な表記はありません。
  - 配列である引数は、 [ lowerbound : size , ... として表されます。 ,lowerbound :size ]コンマの数は順位が 1 未満で、各ディメンションの下限とサイズ (既知の場合) は 10 進数で表されます。下限またはサイズが指定されていない場合は省略されます。特定のディメンションの下限とサイズを省略すると、":" も省略されます。ジャグ配列は、レベルごとに 1 つの "[]" で表されます。下限が 0 (既定値) の場合、1 次元配列では下限が省略されます (§17.1)。
  - void以外のポインター型を持つ引数は、型名に続く*を使用して表されます。 void ポインターは、System.Voidの型名を使用して表されます。
  - 型で定義されているジェネリック型パラメーターを参照する引数は、"`" 文字の後に型パラメーターの 0 から始まるインデックスを使用してエンコードされます。
  - メソッドで定義されているジェネリック型パラメーターを使用する引数では、型に使用される "`" ではなく、double-backtick "``" が使用されます。
  - 構築されたジェネリック型を参照する引数は、ジェネリック型を使用してエンコードされ、その後に "{" が続き、その後に型引数のコンマ区切りのリストが続き、その後に "}" が続きます。

D.4.3 ID 文字列の例

次の例は、C# コードのフラグメントと、ドキュメントコメントを持つことが可能な各ソース要素から生成された ID 文字列を示しています。

型は、汎用情報で補強された完全修飾名を使用して表されます。

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"

フィールド は完全修飾名で表されます。

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"

コンストラクター

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)"

ファイナライザー

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

ID:

"M:Acme.Widget.Finalize"

メソッド

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)"

プロパティとインデクサー

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)"

イベント

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

ID:

"E:Acme.Widget.AnEvent"

単項演算子

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

ID:

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

使用される単項演算子関数名の完全なセットは、 op_UnaryPlus、 op_UnaryNegation、 op_LogicalNot、 op_OnesComplement、 op_Increment、 op_Decrement、 op_True、および op_Falseです。

二項演算子

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

ID:

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

使用される二項演算子関数名の完全なセットは、 op_Addition、 op_Subtraction、 op_Multiply、 op_Division、 op_Modulus、 op_BitwiseAnd、 op_BitwiseOr op_ExclusiveOr、 op_LeftShift、 op_RightShift、 op_Equality、 op_Inequality、 op_LessThan、 op_LessThanOrEqual、 op_GreaterThan、および op_GreaterThanOrEqualです。

変換演算子 末尾に "~" が続き、戻り値の型が続きます。変換演算子の変換元または変換先がジェネリック型の場合、"<" 文字と "">" 文字はそれぞれ "{" 文字と "}" 文字に置き換えられます。

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 例

D.5.1 C# ソースコード

次の例は、Point クラスのソースコードを示しています。

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

上記のクラス Pointのソースコードを指定すると、1 つのドキュメントジェネレーターによって生成される出力を次に示します。

<?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>

情報テキストの末尾。

次の方法で共有

付属書 D ドキュメントのコメント

D.1 全般

D.2 概要

D.3 推奨タグ

D.3.1 全般

D.3.2 <c>

D.3.3 <code>

D.3.4 <example>

D.3.5 <exception>

D.3.6 <組み込み>

D.3.7 <list>

D.3.8 <para>

D.3.9 <param>

D.3.10 <paramref>

D.3.11 <permission>

D.3.12 <remarks>

D.3.13 <ターン>

D.3.14 <see>

D.3.15 <seealso>

D.3.16 <日>

D.3.17 <typeparam>

D.3.18 <typeparamref>

D.3.19 <value>

D.4 ドキュメントファイルの処理

D.4.1 全般

D.4.2 ID 文字列形式

D.4.3 ID 文字列の例

D.5 例

D.5.1 C# ソースコード

D.5.2 結果 XML

その他のリソース

次の方法で共有

付属書 D ドキュメントのコメント

D.1 全般

D.2 概要

D.3 推奨タグ

D.3.1 全般

D.3.2 <c>

D.3.3 <code>

D.3.4 <example>

D.3.5 <exception>

D.3.6 <組み込み>

D.3.7 <list>

D.3.8 <para>

D.3.9 <param>

D.3.10 <paramref>

D.3.11 <permission>

D.3.12 <remarks>

D.3.13 <ターン>

D.3.14 <see>

D.3.15 <seealso>

D.3.16 <日>

D.3.17 <typeparam>

D.3.18 <typeparamref>

D.3.19 <value>

D.4 ドキュメント ファイルの処理

D.4.1 全般

D.4.2 ID 文字列形式

D.4.3 ID 文字列の例

D.5 例

D.5.1 C# ソース コード

D.5.2 結果 XML

その他のリソース

D.4 ドキュメントファイルの処理

D.5.1 C# ソースコード