ドキュメントコメントDocumentation comments

[アーティクル]
05/14/2021

C# には、XML テキストを含む特殊なコメント構文を使用してコードを文書化する機構が用意されています。C# provides a mechanism for programmers to document their code using a special comment syntax that contains XML text. ソースコードファイルでは、特定のフォームを含むコメントを使用して、そのコメントとソースコード要素の前にあるソースコード要素から XML を生成するようにツールに指示できます。In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. このような構文を使用するコメントは、*ドキュメントコメント _ と呼ばれます。Comments using such syntax are called *documentation comments . これらは、ユーザー定義型 (クラス、デリゲート、インターフェイスなど) またはメンバー (フィールド、イベント、プロパティ、メソッドなど) の直前に配置する必要があります。They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method). XML 生成ツールは、 *ドキュメントジェネレーター* と呼ばれています。The XML generation tool is called the documentation generator. (このジェネレーターは C# コンパイラ自体にすることができますが、そうである必要はありません)。ドキュメントジェネレーターによって生成される出力は、 *ドキュメントファイル* と呼ばれます。(This generator could be, but need not be, the C# compiler itself.) The output produced by the documentation generator is called the documentation file. ドキュメントファイルは、 ドキュメントビューアー * に対する入力として使用されます。型情報とそれに関連するドキュメントを視覚的に表示するためのツール。A documentation file is used as input to a _*documentation viewer**; a tool intended to produce some sort of visual display of type information and its associated documentation.

この仕様では、ドキュメントコメントで使用されるタグのセットを提示しますが、これらのタグの使用は必須ではなく、適切な形式の XML の規則に従う限り、必要に応じて他のタグを使用することもできます。This specification suggests a set of tags to be used in documentation comments, but use of these tags is not required, and other tags may be used if desired, as long the rules of well-formed XML are followed.

はじめにIntroduction

特別な形式のコメントを使用すると、そのコメントとソースコード要素の前にあるソースコード要素から XML を生成するようにツールに指示できます。Comments having a special form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. このようなコメントは、3つのスラッシュ () で始まる単一行のコメント /// か、スラッシュと2つの星 () で始まる区切られたコメントです /** 。Such comments are single-line comments that start with three slashes (///), or delimited comments that start with a slash and two stars (/**). これらは、ユーザー定義型 (クラス、デリゲート、インターフェイスなど)、または注釈を付けるメンバー (フィールド、イベント、プロパティ、メソッドなど) の直前に配置する必要があります。They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method) that they annotate. 属性セクション (属性の指定) は宣言の一部と見なされるため、ドキュメントコメントは、型またはメンバーに適用される属性の前に記述する必要があります。Attribute sections (Attribute specification) are considered part of declarations, so documentation comments must precede attributes applied to a type or member.

構文 :Syntax:

single_line_doc_comment
    : '///' input_character*
    ;

delimited_doc_comment
    : '/**' delimited_comment_section* asterisk+ '/'
    ;

Single_line_doc_comment では、現在の single_line_doc_comment に隣接する各 single_line_doc_comment の文字の後に空白文字がある場合、 /// その空白文字は XML 出力に含まれません。 In a single_line_doc_comment, if there is a whitespace character following the /// characters on each of the single_line_doc_comment s adjacent to the current single_line_doc_comment, then that whitespace character is not included in the XML output.

区切り記号で囲まれたドキュメントコメントでは、2行目の空白以外の最初の文字がアスタリスクで、省略可能な空白文字のパターンが同じであり、アスタリスク文字が区切り文字で区切られた各行の先頭で繰り返される場合、繰り返しパターンの文字は XML 出力に含まれません。In a delimited-doc-comment, if the first non-whitespace character on the second line is an asterisk and the same pattern of optional whitespace characters and an asterisk character is repeated at the beginning of each of the line within the delimited-doc-comment, then the characters of the repeated pattern are not included in the XML output. パターンには、アスタリスク文字の前と同様に、空白文字を含めることができます。The pattern may include whitespace characters after, as well as before, the asterisk character.

例:Example:

/// <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 の規則に従って適切な形式である必要があります (「」を参照してください https://www.w3.org/TR/REC-xml) 。The text within documentation comments must be well formed according to the rules of XML (https://www.w3.org/TR/REC-xml). XML の形式が正しくない場合は、警告が生成され、ドキュメントファイルにはエラーが発生したことを示すコメントが含まれます。If the XML is ill formed, a warning is generated and the documentation file will contain a comment saying that an error was encountered.

開発者は独自のタグセットを自由に作成できますが、推奨されるセットは推奨されるタグで定義されています。Although developers are free to create their own set of tags, a recommended set is defined in Recommended tags. 推奨されるタグの一部には特別な意味があります。Some of the recommended tags have special meanings:

<param> タグは、パラメーターの記述に使用します。The <param> tag is used to describe parameters. このようなタグが使用されている場合、ドキュメントジェネレーターは、指定されたパラメーターが存在すること、およびすべてのパラメーターがドキュメントコメントに記述されていることを確認する必要があります。If such a tag is used, the documentation generator must verify that the specified parameter exists and that all parameters are described in documentation comments. このような検証が失敗した場合は、ドキュメントジェネレーターによって警告が発行されます。If such verification fails, the documentation generator issues a warning.
cref 属性は任意のタグにアタッチでき、コード要素への参照を提供します。The cref attribute can be attached to any tag to provide a reference to a code element. ドキュメントジェネレーターは、このコード要素が存在することを確認する必要があります。The documentation generator must verify that this code element exists. 検証が失敗した場合は、ドキュメントジェネレーターによって警告が発行されます。If the verification fails, the documentation generator issues a warning. 属性で記述されている名前を検索する場合 cref 、ドキュメントジェネレーターは、ソースコード内に出現するステートメントに従って、名前空間の可視性を考慮する必要があり using ます。When looking for a name described in a cref attribute, the documentation generator must respect namespace visibility according to using statements appearing within the source code. ジェネリックであるコード要素の場合、通常のジェネリック構文 (つまり " List<T> ") を使用することはできません。これは、無効な XML が生成されるためです。For code elements that are generic, the normal generic syntax (that is, "List<T>") cannot be used because it produces invalid XML. かっこ ("") の代わりに中かっこを使用することも、XML エスケープ構文を使用することもでき List{T} ます (つまり、" List<T> ")。Braces can be used instead of brackets (that is, "List{T}"), or the XML escape syntax can be used (that is, "List<T>").
タグは、 <summary> ドキュメントビューアーが型またはメンバーに関する追加情報を表示するために使用することを目的としています。The <summary> tag is intended to be used by a documentation viewer to display additional information about a type or member.
タグには、 <include> 外部 XML ファイルからの情報が含まれます。The <include> tag includes information from an external XML file.

ドキュメントファイルでは、型とメンバーに関する完全な情報が提供されていないことに注意してください (たとえば、型情報が含まれていない場合)。Note carefully that the documentation file does not provide full information about the type and members (for example, it does not contain any type information). 型またはメンバーに関する情報を取得するには、ドキュメントファイルを実際の型またはメンバーのリフレクションと組み合わせて使用する必要があります。To get such information about a type or member, the documentation file must be used in conjunction with reflection on the actual type or member.

推奨タグRecommended tags

ドキュメントジェネレーターは、XML の規則に従って有効なすべてのタグを受け入れて処理する必要があります。The documentation generator must accept and process any tag that is valid according to the rules of XML. 次のタグによって、ユーザードキュメントで一般的に使用される機能が与えられます。The following tags provide commonly used functionality in user documentation. (もちろん、他のタグも使用できます)。(Of course, other tags are possible.)

TagTag	セクションSection	目的Purpose
`<c>`	`<c>`	コードに似たフォントでテキストを設定するSet text in a code-like font
`<code>`	`<code>`	ソースコードまたはプログラム出力の1行以上の行を設定するSet one or more lines of source code or program output
`<example>`	`<example>`	例を示します。Indicate an example
`<exception>`	`<exception>`	メソッドがスローできる例外を識別します。Identifies the exceptions a method can throw
`<include>`	`<include>`	外部ファイルから XML をインクルードします。Includes XML from an external file
`<list>`	`<list>`	リストまたはテーブルを作成するCreate a list or table
`<para>`	`<para>`	テキストへの構造の追加を許可するPermit structure to be added to text
`<param>`	`<param>`	メソッドまたはコンストラクターのパラメーターの記述Describe a parameter for a method or constructor
`<paramref>`	`<paramref>`	単語がパラメーター名であることを識別するIdentify that a word is a parameter name
`<permission>`	`<permission>`	メンバーのセキュリティアクセシビリティを文書化するDocument the security accessibility of a member
`<remarks>`	`<remarks>`	型に関する追加情報の記述Describe additional information about a type
`<returns>`	`<returns>`	メソッドの戻り値の説明Describe the return value of a method
`<see>`	`<see>`	リンクの指定Specify a link
`<seealso>`	`<seealso>`	関連項目を生成するGenerate a See Also entry
`<summary>`	`<summary>`	型または型のメンバーの記述Describe a type or a member of a type
`<value>`	`<value>`	プロパティの説明Describe a property
`<typeparam>`		ジェネリック型パラメーターの記述Describe a generic type parameter
`<typeparamref>`		単語が型パラメーター名であることを識別するIdentify that a word is a type parameter name

`<c>`

このタグは、記述に含まれるテキストのフラグメントを、コードブロックに使用される特殊なフォントで設定する必要があることを示す機構を提供します。This tag provides a mechanism to indicate that a fragment of text within a description should be set in a special font such as that used for a block of code. 実際のコード行の場合は、() を使用し <code> <code> ます。For lines of actual code, use <code> (<code>).

構文 :Syntax:

<c>text</c>

例:Example:

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

public class Point 
{
    // ...
}

`<code>`

このタグは、ソースコードまたはプログラム出力の1つ以上の行を特殊なフォントで設定するために使用されます。This tag is used to set one or more lines of source code or program output in some special font. ナレーションの小さなコードフラグメントの場合は、() を使用し <c> <c> ます。For small code fragments in narrative, use <c> (<c>).

構文 :Syntax:

<code>source code or program output</code>

例:Example:

/// <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 xor, int yor) {
    X += xor;
    Y += yor;
}

`<example>`

このタグでは、コメント内のコード例を使用して、メソッドまたはその他のライブラリメンバーの使用方法を指定できます。This tag allows example code within a comment, to specify how a method or other library member may be used. 通常は、タグ () も使用し <code> <code> ます。Ordinarily, this would also involve use of the tag <code> (<code>) as well.

構文 :Syntax:

<example>description</example>

例:Example:

<code> <code> 例については、() を参照してください。See <code> (<code>) for an example.

`<exception>`

このタグは、メソッドがスローできる例外を文書化する方法を提供します。This tag provides a way to document the exceptions a method can throw.

構文 :Syntax:

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

wherewhere

member メンバーの名前を指定します。member is the name of a member. ドキュメントジェネレーターは、指定されたメンバーが存在することを確認し、 member ドキュメントファイル内の正規要素名に変換します。The documentation generator checks that the given member exists and translates member to the canonical element name in the documentation file.
description 例外がスローされる状況の説明です。description is a description of the circumstances in which the exception is thrown.

例:Example:

public class DataBaseOperations
{
    /// <exception cref="MasterFileFormatCorruptException"></exception>
    /// <exception cref="MasterFileLockedOpenException"></exception>
    public static void ReadRecord(int flag) {
        if (flag == 1)
            throw new MasterFileFormatCorruptException();
        else if (flag == 2)
            throw new MasterFileLockedOpenException();
        // ...
    } 
}

`<include>`

このタグを使用すると、ソースコードファイルの外部にある XML ドキュメントの情報を含めることができます。This tag allows including information from an XML document that is external to the source code file. 外部ファイルは整形式の XML ドキュメントである必要があり、そのドキュメントに含まれる XML を指定するために XPath 式がそのドキュメントに適用されます。The external file must be a well-formed XML document, and an XPath expression is applied to that document to specify what XML from that document to include. タグは、 <include> 外部ドキュメントから選択された XML に置き換えられます。The <include> tag is then replaced with the selected XML from the external document.

構文 :Syntax:

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

wherewhere

filename 外部 XML ファイルのファイル名を指定します。filename is the file name of an external XML file. ファイル名は、include タグを含むファイルに対して相対的に解釈されます。The file name is interpreted relative to the file that contains the include tag.
xpath 外部 XML ファイル内の XML の一部を選択する XPath 式です。xpath is an XPath expression that selects some of the XML in the external XML file.

例:Example:

ソースコードに次のような宣言が含まれている場合:If the source code contained a declaration like:

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

外部ファイル "docs.xml" には次の内容が含まれていました。and the external file "docs.xml" had the following contents:

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

次に、同じドキュメントが、ソースコードに含まれているものとして出力されます。then the same documentation is output as if the source code contained:

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

`<list>`

このタグは、項目のリストまたはテーブルを作成するために使用されます。This tag is used to create a list or table of items. <listheader>テーブルまたは定義リストの見出し行を定義するブロックが含まれている場合があります。It may contain a <listheader> block to define the heading row of either a table or definition list. (テーブルを定義する場合は、見出し内ののエントリだけを term 指定する必要があります)。(When defining a table, only an entry for term in the heading need be supplied.)

リストの各項目は、<item> ブロックで指定されます。Each item in the list is specified with an <item> block. 定義リストを作成する場合は、との両方を term description 指定する必要があります。When creating a definition list, both term and description must be specified. ただし、テーブル、箇条書きリスト、番号付きリストの場合は、のみ description 指定する必要があります。However, for a table, bulleted list, or numbered list, only description need be specified.

構文 :Syntax:

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

wherewhere

term 定義を定義する用語を指定します。定義はに description あります。term is the term to define, whose definition is in description.
description は、箇条書きまたは番号付きリストの項目、またはの定義のいずれか term です。description is either an item in a bullet or numbered list, or the definition of a term.

例:Example:

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

`<para>`

このタグは、() や () などの他のタグ内で使用するためのもので、 <summary> <remarks> <returns> <returns> テキストに構造を追加することを許可します。This tag is for use inside other tags, such as <summary> (<remarks>) or <returns> (<returns>), and permits structure to be added to text.

構文 :Syntax:

<para>content</para>

ここで、 content は段落のテキストです。where content is the text of the paragraph.

例:Example:

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

`<param>`

このタグは、メソッド、コンストラクター、またはインデクサーのパラメーターを記述するために使用されます。This tag is used to describe a parameter for a method, constructor, or indexer.

構文 :Syntax:

<param name="name">description</param>

wherewhere

name は、パラメーターの名前です。name is the name of the parameter.
description パラメーターの説明を指定します。description is a description of the parameter.

例:Example:

/// <summary>This method changes the point's location to
///    the given coordinates.</summary>
/// <param name="xor">the new x-coordinate.</param>
/// <param name="yor">the new y-coordinate.</param>
public void Move(int xor, int yor) {
    X = xor;
    Y = yor;
}

`<paramref>`

このタグは、単語がパラメーターであることを示すために使用されます。This tag is used to indicate that a word is a parameter. ドキュメントファイルを処理して、このパラメーターを別の方法で書式設定することができます。The documentation file can be processed to format this parameter in some distinct way.

構文 :Syntax:

<paramref name="name"/>

ここで、 name はパラメーターの名前です。where name is the name of the parameter.

例:Example:

/// <summary>This constructor initializes the new Point to
///    (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
/// <param name="xor">the new Point's x-coordinate.</param>
/// <param name="yor">the new Point's y-coordinate.</param>

public Point(int xor, int yor) {
    X = xor;
    Y = yor;
}

`<permission>`

このタグにより、メンバーのセキュリティアクセシビリティを文書化することができます。This tag allows the security accessibility of a member to be documented.

構文 :Syntax:

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

wherewhere

member メンバーの名前を指定します。member is the name of a member. ドキュメントジェネレーターは、指定されたコード要素が存在することを確認し、 メンバー をドキュメントファイル内の正規要素名に変換します。The documentation generator checks that the given code element exists and translates member to the canonical element name in the documentation file.
description メンバーへのアクセスの説明を示します。description is a description of the access to the member.

例:Example:

/// <permission cref="System.Security.PermissionSet">Everyone can
/// access this method.</permission>

public static void Test() {
    // ...
}

`<remarks>`

このタグは、型に関する追加情報を指定するために使用されます。This tag is used to specify extra information about a type. (使用 <summary> () を入力して、型 <summary> 自体と型のメンバーを記述します。(Use <summary> (<summary>) to describe the type itself and the members of a type.)

構文 :Syntax:

<remarks>description</remarks>

ここで、 description はコメントのテキストです。where description is the text of the remark.

例:Example:

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

`<returns>`

このタグは、メソッドの戻り値を記述するために使用されます。This tag is used to describe the return value of a method.

構文 :Syntax:

<returns>description</returns>

ここで、 description は戻り値の説明です。where description is a description of the return value.

例:Example:

/// <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() {
    return "(" + X + "," + Y + ")";
}

`<see>`

このタグを使用すると、テキスト内でリンクを指定できます。This tag allows a link to be specified within text. <seealso>( <seealso> ) を使用して、[参照] セクションに表示されるテキストを指定します。Use <seealso> (<seealso>) to indicate text that is to appear in a See Also section.

構文 :Syntax:

<see cref="member"/>

ここで、 member はメンバーの名前です。where member is the name of a member. ドキュメントジェネレーターは、指定されたコード要素が存在することを確認し、生成されたドキュメントファイル内の要素名に メンバー を変更します。The documentation generator checks that the given code element exists and changes member to the element name in the generated documentation file.

例:Example:

/// <summary>This method changes the point's location to
///    the given coordinates.</summary>
/// <see cref="Translate"/>
public void Move(int xor, int yor) {
    X = xor;
    Y = yor;
}

/// <summary>This method changes the point's location by
///    the given x- and y-offsets.
/// </summary>
/// <see cref="Move"/>
public void Translate(int xor, int yor) {
    X += xor;
    Y += yor;
}

`<seealso>`

このタグを使用すると、[参照] セクションのエントリも生成されます。This tag allows an entry to be generated for the See Also section. <see>() を使用して <see> 、テキスト内からリンクを指定します。Use <see> (<see>) to specify a link from within text.

構文 :Syntax:

<seealso cref="member"/>

例:Example:

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

`<summary>`

このタグは、型または型のメンバーを記述するために使用できます。 <remarks> <remarks> 型自体を記述するには、() を使用します。Use <remarks> (<remarks>) to describe the type itself.

構文 :Syntax:

<summary>description</summary>

ここで description 、は型またはメンバーの概要です。where description is a summary of the type or member.

例:Example:

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

`<value>`

このタグを使用すると、プロパティを記述できます。This tag allows a property to be described.

構文 :Syntax:

<value>property description</value>

ここで property description 、はプロパティの説明です。where property description is a description for the property.

例:Example:

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

`<typeparam>`

このタグは、クラス、構造体、インターフェイス、デリゲート、またはメソッドのジェネリック型パラメーターを記述するために使用されます。This tag is used to describe a generic type parameter for a class, struct, interface, delegate, or method.

構文 :Syntax:

<typeparam name="name">description</typeparam>

ここで、 name は型パラメーターの名前、 description は説明です。where name is the name of the type parameter, and description is its description.

例:Example:

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

`<typeparamref>`

このタグは、単語が型パラメーターであることを示すために使用されます。This tag is used to indicate that a word is a type parameter. ドキュメントファイルを処理して、この型パラメーターを別の方法で書式設定することができます。The documentation file can be processed to format this type parameter in some distinct way.

構文 :Syntax:

<typeparamref name="name"/>

ここで、 name は型パラメーターの名前です。where name is the name of the type parameter.

例:Example:

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

ドキュメントファイルの処理Processing the documentation file

ドキュメントジェネレーターは、ドキュメントコメントでタグ付けされたソースコード内の各要素に対して ID 文字列を生成します。The documentation generator generates an ID string for each element in the source code that is tagged with a documentation comment. この ID 文字列は、ソース要素を一意に識別します。This ID string uniquely identifies a source element. ドキュメントビューアーでは、ID 文字列を使用して、ドキュメントが適用される、対応するメタデータ/リフレクション項目を識別できます。A documentation viewer can use an ID string to identify the corresponding metadata/reflection item to which the documentation applies.

ドキュメントファイルは、ソースコードの階層的な表現ではありません。代わりに、要素ごとに生成された ID 文字列を含む単純なリストになります。The documentation file is not a hierarchical representation of the source code; rather, it is a flat list with a generated ID string for each element.

ID 文字列の形式ID string format

ドキュメントジェネレーターは、ID 文字列を生成するときに、次の規則を監視します。The documentation generator observes the following rules when it generates the ID strings:

文字列に空白は配置されません。No white space is placed in the string.

文字列の最初の部分では、ドキュメント化されているメンバーの種類を、1つの文字の後にコロンを使用して識別します。The first part of the string identifies the kind of member being documented, via a single character followed by a colon. 次の種類のメンバーが定義されています。The following kinds of members are defined:

文字Character	説明Description
EE	EventEvent
FF	フィールドField
MM	メソッド (コンストラクター、デストラクター、および演算子を含む)Method (including constructors, destructors, and operators)
NN	名前空間Namespace
PP	プロパティ (インデクサーを含む)Property (including indexers)
TT	型 (クラス、デリゲート、列挙型、インターフェイス、構造体など)Type (such as class, delegate, enum, interface, and struct)
!!	エラー文字列;文字列の残りの部分は、エラーに関する情報を提供します。Error string; the rest of the string provides information about the error. たとえば、ドキュメントジェネレーターは、解決できないリンクのエラー情報を生成します。For example, the documentation generator generates error information for links that cannot be resolved.

文字列の2番目の部分は、要素の完全修飾名であり、名前空間のルートから始まります。The second part of the string is the fully qualified name of the element, starting at the root of the namespace. 要素の名前、それを囲む型、および名前空間は、ピリオドで区切られます。The name of the element, its enclosing type(s), and namespace are separated by periods. 項目の名前にピリオドが含まれている場合は、文字で置き換えられ #(U+0023) ます。If the name of the item itself has periods, they are replaced by #(U+0023) characters. (この文字が名前に含まれている要素がないことを前提としています)。(It is assumed that no element has this character in its name.)
引数を持つメソッドとプロパティについては、かっこで囲まれた引数リストが続きます。For methods and properties with arguments, the argument list follows, enclosed in parentheses. 引数を指定しない場合、かっこは省略されます。For those without arguments, the parentheses are omitted. 引数はコンマで区切られます。The arguments are separated by commas. 各引数のエンコーディングは、次のように CLI シグネチャと同じです。The encoding of each argument is the same as a CLI signature, as follows:
- 引数は、次のように変更された完全修飾名に基づいて、ドキュメント名によって表されます。Arguments are represented by their documentation name, which is based on their fully qualified name, modified as follows:
  - ジェネリック型を表す引数には、追加さ ` れた (バックティック) 文字の後に型パラメーターの数が続きます。Arguments that represent generic types have an appended ` (backtick) character followed by the number of type parameters
  - または修飾子を持つ引数の out ref 型名は、次のように @ なります。Arguments having the out or ref modifier have an @ following their type name. 値または via によって渡される引数には、 params 特別な表記はありません。Arguments passed by value or via params have no special notation.
  - 配列として指定される引数は、 [lowerbound:size, ... , lowerbound:size] コンマの数が1未満の値で表され、各次元の下限とサイズ (既知の場合) が decimal で表されます。Arguments that are arrays are represented as [lowerbound:size, ... , lowerbound:size] where the number of commas is the rank less one, and the lower bounds and size of each dimension, if known, are represented in decimal. 下限またはサイズが指定されていない場合は省略されます。If a lower bound or size is not specified, it is omitted. 特定の次元の下限とサイズが省略されている場合は、 : も省略されます。If the lower bound and size for a particular dimension are omitted, the : is omitted as well. ジャグ配列は、1レベルにつき1つので表され [] ます。Jagged arrays are represented by one [] per level.
  - Void 以外のポインター型を持つ引数は、次の型名を使用して表され * ます。Arguments that have pointer types other than void are represented using a * following the type name. Void ポインターは、型名を使用して表され System.Void ます。A void pointer is represented using a type name of System.Void.
  - 型に対して定義されているジェネリック型パラメーターを参照する引数は、 ` (バックティック) 文字の後に型パラメーターの0から始まるインデックスを使用してエンコードされます。Arguments that refer to generic type parameters defined on types are encoded using the ` (backtick) character followed by the zero-based index of the type parameter.
  - メソッドで定義されているジェネリック型パラメーターを使用する引数は `` 、 ` 型に使用されるではなく、二重バックティックを使用します。Arguments that use generic type parameters defined in methods use a double-backtick `` instead of the ` used for types.
  - 構築されたジェネリック型を参照する引数は、ジェネリック型を使用してエンコードされ、それに続いて、の後に { 型引数のコンマ区切りリストが続き } ます。Arguments that refer to constructed generic types are encoded using the generic type, followed by {, followed by a comma-separated list of type arguments, followed by }.

ID 文字列の例ID string examples

次の例は、C# コードのフラグメントと、ドキュメントコメントを持つことができる各ソース要素から生成された ID 文字列を示しています。The following examples each show a fragment of C# code, along with the ID string produced from each source element capable of having a documentation comment:

型は、完全修飾名を使用して表され、汎用情報で補完されます。Types are represented using their fully qualified name, augmented with generic information:

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

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

フィールドは、完全修飾名で表されます。Fields are represented by their fully qualified name:

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

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

コンストラクター。Constructors.

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

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

デストラクタ.Destructors.

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

"M:Acme.Widget.Finalize"

メソッド.Methods.

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) {...}
        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 inputValue) { return null; }
    }
}

"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@)"
"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``(``0)"

プロパティとインデクサー。Properties and indexers.

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

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

イベント。Events.

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

"E:Acme.Widget.AnEvent"

単項演算子。Unary operators.
```
namespace Acme
{
    class Widget: IProcess
    {
        public static Widget operator+(Widget x) {...}
    }
}

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
```
使用される単項演算子関数名の完全なセットは、、、、、、、 op_UnaryPlus op_UnaryNegation op_LogicalNot op_OnesComplement op_Increment op_Decrement op_True 、および op_False です。The complete set of unary operator function names used is as follows: op_UnaryPlus, op_UnaryNegation, op_LogicalNot, op_OnesComplement, op_Increment, op_Decrement, op_True, and op_False.
二項演算子。Binary operators.
```
namespace Acme
{
    class Widget: IProcess
    {
        public static Widget operator+(Widget x1, Widget x2) {...}
    }
}

"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 です。The complete set of binary operator function names used is as follows: 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, and op_GreaterThanOrEqual.

変換演算子には、末尾に " ~ " の後に戻り値の型があります。Conversion operators have a trailing "~" followed by the return type.

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

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

使用例An example

C# ソースコードC# source code

次の例は、クラスのソースコードを示してい Point ます。The following example shows the source code of a Point class:

namespace Graphics
{

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

    /// <summary>Instance variable <c>x</c> represents the point's
    ///    x-coordinate.</summary>
    private int x;

    /// <summary>Instance variable <c>y</c> represents the point's
    ///    y-coordinate.</summary>
    private int y;

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

    /// <value>Property <c>Y</c> represents the point's y-coordinate.</value>
    public int Y
    {
        get { return y; }
        set { y = value; }
    }

    /// <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="xor"/>,<paramref name="yor"/>).</summary>
    /// <param><c>xor</c> is the new Point's x-coordinate.</param>
    /// <param><c>yor</c> is the new Point's y-coordinate.</param>
    public Point(int xor, int yor) {
        X = xor;
        Y = yor;
    }

    /// <summary>This method changes the point's location to
    ///    the given coordinates.</summary>
    /// <param><c>xor</c> is the new x-coordinate.</param>
    /// <param><c>yor</c> is the new y-coordinate.</param>
    /// <see cref="Translate"/>
    public void Move(int xor, int yor) {
        X = xor;
        Y = yor;
    }

    /// <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>
    /// <param><c>xor</c> is the relative x-offset.</param>
    /// <param><c>yor</c> is the relative y-offset.</param>
    /// <see cref="Move"/>
    public void Translate(int xor, int yor) {
        X += xor;
        Y += yor;
    }

    /// <summary>This method determines whether two Points have the same
    ///    location.</summary>
    /// <param><c>o</c> is 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 (this == o) {
            return true;
        }

        if (GetType() == o.GetType()) {
            Point p = (Point)o;
            return (X == p.X) && (Y == p.Y);
        }
        return false;
    }

    /// <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() {
        return "(" + X + "," + Y + ")";
    }

    /// <summary>This operator determines whether two Points have the same
    ///    location.</summary>
    /// <param><c>p1</c> is the first Point to be compared.</param>
    /// <param><c>p2</c> is 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><c>p1</c> is the first Point to be compared.</param>
    /// <param><c>p2</c> is 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) {
        return !(p1 == p2);
    }

    /// <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() {
        // class test code goes here
    }
}
}

結果の XMLResulting XML

次に示すのは、上記のクラスのソースコードを指定した場合に、1つのドキュメントジェネレーターによって生成される出力です Point 。Here is the output produced by one documentation generator when given the source code for class Point, shown above:

<?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="F:Graphics.Point.x">
            <summary>Instance variable <c>x</c> represents the point's
            x-coordinate.</summary>
        </member>

        <member name="F:Graphics.Point.y">
            <summary>Instance variable <c>y</c> represents the point's
            y-coordinate.</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="xor"/>,<paramref name="yor"/>).</summary>
            <param><c>xor</c> is the new Point's x-coordinate.</param>
            <param><c>yor</c> is 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.</summary>
            <param><c>xor</c> is the new x-coordinate.</param>
            <param><c>yor</c> is the new y-coordinate.</param>
            <see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
        </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>
            </summary>
            <param><c>xor</c> is the relative x-offset.</param>
            <param><c>yor</c> is the relative y-offset.</param>
            <see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
        </member>

        <member name="M:Graphics.Point.Equals(System.Object)">
            <summary>This method determines whether two Points have the same
            location.</summary>
            <param><c>o</c> is 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><c>p1</c> is the first Point to be compared.</param>
            <param><c>p2</c> is 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><c>p1</c> is the first Point to be compared.</param>
            <param><c>p2</c> is 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>

ドキュメントコメントDocumentation comments

はじめにIntroduction

推奨タグRecommended tags

`<c>`

`<code>`

`<example>`

`<exception>`

`<include>`

`<list>`

`<para>`

`<param>`

`<paramref>`

`<permission>`

`<remarks>`

`<returns>`

`<see>`

`<seealso>`

`<summary>`

`<value>`

`<typeparam>`

`<typeparamref>`

ドキュメントファイルの処理Processing the documentation file

ID 文字列の形式ID string format

ID 文字列の例ID string examples

使用例An example

C# ソースコードC# source code

結果の XMLResulting XML

その他のリソース

その他のリソース

ドキュメント コメントDocumentation comments

はじめにIntroduction

推奨タグRecommended tags

<c>

<code>

<example>

<exception>

<include>

<list>

<para>

<param>

<paramref>

<permission>

<remarks>

<returns>

<see>

<seealso>

<summary>

<value>

<typeparam>

<typeparamref>

ドキュメント ファイルの処理Processing the documentation file

ID 文字列の形式ID string format

ID 文字列の例ID string examples

使用例An example

C# ソース コードC# source code

結果の XMLResulting XML

その他のリソース

その他のリソース

ドキュメントコメントDocumentation comments

`<c>`

`<code>`

`<example>`

`<exception>`

`<include>`

`<list>`

`<para>`

`<param>`

`<paramref>`

`<permission>`

`<remarks>`

`<returns>`

`<see>`

`<seealso>`

`<summary>`

`<value>`

`<typeparam>`

`<typeparamref>`

ドキュメントファイルの処理Processing the documentation file

C# ソースコードC# source code