付録 D 文書化コメント

本付録は、参考情報です。

D.1 全般

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

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

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

D.2 概要

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

説明の目的で、2 つの文法規則としてドキュメント コメントの形式を次に示します: Single_Line_Doc_Comment および Delimited_Doc_Comment。 ただし、これらの規則は、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 に隣接する /// の 文字の後にホワイトスペース文字がある場合、そのホワイトスペース文字は XML 出力に含まれません。

Delimited_Doc_Comment で、2 行目の最初のホワイトスペース以外の文字がアスタリスクで、任意のホワイトスペース文字と同じパターンで、アスタリスク文字が、Delimited_Doc_Comment 内の各行の最初で繰り返されている場合、繰り返されているパターンの文字は、XML 出力に含まれません。 パターンには、アスタリスク文字の前だけでなく後ろにも ホワイトスペース文字を含めることができます。

例:

/// <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 属性に記述された名前を検索する場合、ドキュメント ジェネレーターは、ソース コード内に表示されるステートメントを使用して、名前空間の可視性を尊重する必要があります。 汎用的なコード要素の場合、無効な XML が生成されるため、List<T> などの通常の汎用構文は使用できません。 角括弧の代わりに中括弧を使用することもできます (例: List{T})。また、XML エスケープ構文を使用することもできます (例: List<T>)。

• <summary> タグは、ドキュメント ビューアで型またはメンバーに関する追加情報を表示するために使用することを目的としています。

• <include> タグには、外部 XML ファイルからの情報が含まれます。

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

部分型または部分メソッドは複数の部分で宣言することができ、各部分は 1 つ以上のコンパイル ユニット内に存在でき、各部分は 1 つ以上のドキュメント コメントを持つことができます。 部分メソッドには通常、「定義部分宣言」と「実装部分宣言」があります。

部分型の場合、その型に直接適用されるドキュメント コメントは、その各部分から、すべて不特定の順序でドキュメント ファイルに書き込まれます。

部分メソッドの場合:

• 定義部分宣言に対応する実装部分宣言がない場合、その定義部分宣言内のすべてのドキュメント コメントは無視されます (その宣言は削除されるため)。
• それ以外の場合、実装部分宣言にドキュメント コメントがある場合は、それらがドキュメント ファイルに書き込まれ、定義部分宣言内のドキュメント コメントは無視されます。
• それ以外の場合、定義部分宣言内のすべてのドキュメント コメントがドキュメント ファイルに書き込まれます。

D.3 推奨タグ

D.3.1 全般

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

D.3.2 <c>

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

構文 :

<c> テキスト</c>

例:

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

D.3.3 <コード>

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

構文 :

<code> source code または program output</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 <例>

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

構文 :

<example> 形容</example>

例:

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

D.3.5 <例外>

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

構文 :

<exception cref=" メンバー">形容</exception>

どこ

• cref=" member" は、メンバー名です。 ドキュメント ジェネレーターは、指定メンバーが既存しているかを確認し、ドキュメント ファイルで member を Canonical 要素名に変換します。
• 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=" ファイル名" path="XPath" />

どこ

• file=" filename" は、外部 XML ファイルのファイル名です。 ファイル名は、include タグを含むファイルに対して相対的に解釈されます。
• 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 <一覧>

このタグは、項目のリストやテーブルを作成するために使用します。 テーブルまたは定義リストの見出し行を定義する <listheader> ブロックが含まれます。 (テーブルを定義するときのみ、見出しの term の入力を指定する必要があります)。

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

どこ

• term は、定義する用語で、その定義は、description にあります。
• 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 <パラ>

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

構文 :

<para> コンテンツ</para>

どこ

• 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 name=" 名前">形容</param>

どこ

• 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 は、パラメーターの名前です。

例:

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 cref=" メンバー">形容</permission>

どこ

• member は、メンバー名です。 ドキュメント ジェネレーターは、指定コード要素が既存しているかを確認し、ドキュメント ファイルで member を Canonical 要素名に変換します。
• description メンバーへのアクセスに関する説明です。

例:

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

D.3.12 <備考>

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

構文 :

<remarks> 形容</remarks>

どこ

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

どこ

• 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 <参照>

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

構文 :

<see cref=" メンバー" href="URLです" langword="キーワード" />

どこ

• 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 <関連項目>

このタグを使用すると、See Also サブ句に対して生成されるエントリを許可します。 <see> (§D.3.14) 使用して、テキスト内でリンクを指定します。

構文 :

<seealso cref=" メンバー" href="関連URL" />

どこ

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

どこ

• 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 name=" 名前">形容</typeparam>

どこ

• 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 name=" 名前"/>

どこ

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

どこ

• 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 文字列を生成します。

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

• 文字列の最初の部分は、単一の文字とそれに続くコロンによって、文書化されているメンバーの種類を識別します。 次の種類のメンバーが定義されています。

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

• 文字列の 2 番目の部分は、要素の完全修飾名で、名前空間のルートから始まります。 要素の名前、それを囲む型、名前空間はピリオドで区切られます。 項目の名前自体にピリオドがある場合、# (U+0023) 文字で置き換えられます。 (要素名にこの文字が含まれないことが前提となります。) 完全修飾名の型引数は、メンバーがジェネリック インターフェイスのメンバーを明示的に実装する場合、それらを囲む「<」と「>」を「{」と「}」の文字に置き換えることによってエンコードされます。

• 引数を持つメソッドとプロパティの場合は、括弧で囲まれた引数リストが続きます。 引数がない場合は、括弧は省略されます。 引数はコンマで区切られます。 各引数のエンコードは、次のように CLI 署名と同じです。

  • 引数は、次のように変更された完全修飾名に基づいたドキュメント名で表されます。
    • ジェネリック型を表す引数には「'」文字が付加され、その後に型パラメータの数が続きます。
    • in、out または ref 修飾子がある引数には、型名の後に @ が続きます。 値または params 経由で渡される引数には特別な記法はありません。
    • 配列としての引数は、[lowerbound:size, … として表記されます。 , lowerbound:size] カンマ数はランクから 1 を引いた数であり、各ディメンションの下限とサイズは (既知の場合) 10 進数で表されます。 下限またはサイズの指定がない場合は省略されます。 特定の次元で下限およびサイズが省略されている場合は、「:」も省略されます。 ジャグ配列はレベルごとに 1 つの「[]」で表されます。 1 次元配列では、下限 が0 (デフォルト) の場合、下限は省略されます (§17.1)。
    • void 以外のポインタ型を持つ引数は、型名の後に * を使用して表されます。 void ポインタは System.Void という型名を使用して表されます。
    • 型で定義されたジェネリック型パラメータを参照する引数は、「`」文字とそれに続く型パラメータのゼロベースのインデックスを使用してエンコードされます。
    • メソッドで定義されたジェネリック型パラメータを使用する引数では、型に使用される「``」の代わりに二重バックティック「`」が使用されます。
    • 構築されたジェネリック型を参照する引数は、ジェネリック型の後に「{」、その後にカンマで区切られた型引数のリスト、最後に「}」を使用してエンコードされます。

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 のソース コードを指定したときに、あるドキュメント ジェネレータによって生成された出力です。

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

情報テキストの末尾。