C# ドキュメント コメントとして推奨される XML タグ

C# ドキュメント コメントは、XML 要素を使用して出力ドキュメントの構造を定義します。 この機能の結果の 1 つは、ドキュメント コメントに有効な XML を追加できることです。 C# コンパイラにより、これらの要素は出力 XML ファイルにコピーされます。 コメントでは任意の有効な XML (有効な HTML 要素を含む) を使用できますが、多くの理由からコードを文書化することが推奨されます。

いくつかの推奨事項、一般的なユース ケースのシナリオ、XML ドキュメント タグを C# コードで使用するときに知っておく必要があることを次に示します。 ドキュメント コメントに任意のタグを付けることができますが、この記事では、最も一般的な言語コンストラクトに推奨されるタグについて説明します。 すべての場合において、次の推奨事項に従う必要があります。

• 整合性を維持するために、公開されているすべての型とその公開メンバーを文書化する必要があります。
• プライベート メンバーも XML コメントを使用して文書化できます。 ただし、これにより、ライブラリの内部 (機密の可能性がある) の動作が公開されます。
• 型とそのメンバーには少なくとも <summary> タグが必要です。
• 文書化のテキストは、句点で終わる完全な文を使用して作成する必要があります。
• 部分クラスは完全にサポートされており、ドキュメント情報は型ごとに 1 つのエントリに連結されます。 partial メンバーの両方の宣言にドキュメント コメントがある場合、実装宣言のコメントが出力 XML に書き込まれます。

XML ドキュメントは、/// で始まります。 新しいプロジェクトを作成すると、テンプレートによっていくつかのスターター /// 行が挿入されます。 これらのコメントの処理にはいくつか制限があります。

• ドキュメントは整形式の XML である必要があります。 XML が正しい形式ではない場合、コンパイラによって警告が生成されます。 ドキュメント ファイルには、エラーが発生したことを示すコメントが含まれます。
• 推奨されるタグの一部には特別な意味があります。
  • <param> タグは、パラメーターの記述に使用します。 このタグがあると、コンパイラは、パラメーターが存在すること、およびすべてのパラメーターがドキュメントで記述されていることを確認します。 検証が失敗する場合は、コンパイラが警告を生成します。
  • cref 属性は任意のタグにアタッチされて、コード要素を参照することができます。 コンパイラは、このコード要素が存在することを確認します。 検証が失敗すると、コンパイラは警告を発行します。 コンパイラは、cref 属性内で記述されている型を探す際、すべての using ディレクティブを考慮に入れます。
  • <summary> タグは、型またはメンバーに関する追加情報を表示するために、Visual Studio 内の IntelliSense によって使用されます。

    注意

    XML ファイルでは、型とメンバーに関する完全な情報は提供されません (たとえば、型の情報は含まれません)。 型またはメンバーに関する完全な情報を取得するには、ドキュメント ファイルと併せて、実際の型またはメンバーでリフレクションを使う必要があります。

• 開発者は、独自のタグ セットを自由に作成できます。 コンパイラにより、これらのタグが出力ファイルにコピーされます。

一部の推奨タグは、どの言語要素でも使用できます。 それ以外は、より特化された使い方があります。 最後に、一部のタグは、ドキュメント内のテキストの書式設定に使用されます。 この記事では、推奨タグを用途別に整理して説明します。

コンパイラにより、次の一覧にある 1 つの * が後に続く要素について、構文が検証されます。 Visual Studio では、コンパイラによって検証されるタグと、次の一覧にある ** が続くすべてのタグのための IntelliSense が用意されています。 コンパイラと Visual Studio では、ここに列挙するタグに加えて、<b>、<i>、<u>、<br/>、<a> の各タグも検証されます。 コンパイラでは、非推奨の HTML タグである <tt> も検証されます。

• 複数の要素に使用される 一般的なタグ - これらのタグは、API 用の最小セットです。
  • <summary>: この要素の値は、Visual Studio の IntelliSense に表示されます。
  • <remarks> **
• メンバーに使用されるタグ - これらのタグは、メソッドおよびプロパティを文書化する場合に使用されます。
  • <returns>: この要素の値は、Visual Studio の IntelliSense に表示されます。
  • <param> *: この要素の値は、Visual Studio の IntelliSense に表示されます。
  • <paramref>
  • <exception> *
  • <value>: この要素の値は、Visual Studio の IntelliSense に表示されます。
• ドキュメント出力の書式設定 - これらのタグを使用して、ドキュメントを生成するツールに書式設定を指示します。
  • <para>
  • <list>
  • <c>
  • <code>
  • <example> **
• ドキュメント テキストの再使用 - これらのタグを使用すると、ツールで XML コメントを再使用しやすくなります。
  • <inheritdoc> **
  • <include> *
• リンクと参照の生成 - これらのタグを使用して、他のドキュメントへのリンクを生成します。
  • <see> *
  • <seealso> *
  • cref
  • href
• ジェネリック型およびメソッド用のタグ - これらのタグは、ジェネリック型およびメソッドでのみ使用されます。
  • <typeparam> *: この要素の値は、Visual Studio の IntelliSense に表示されます。
  • <typeparamref>

注意

ドキュメント コメントは、名前空間に適用できません。

ドキュメント コメントのテキストに山かっこを表示する場合は、< と > の HTML エンコードを使用します。これらはそれぞれ、< と > になります。 このエンコードは次の例に示されています。

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

一般的なタグ

<summary>

<summary>description</summary>

<summary> タグは、型または型メンバーの説明に使用します。 型の説明に補足情報を追加するには、<remarks> タグを使用します。 DocFX や Sandcastle などのドキュメント ツールでコード要素のドキュメント ページへの内部ハイパーリンクを作成できるようにするには、cref 属性を使用します。 <summary> タグのテキストは、IntelliSense とオブジェクト ブラウザー ウィンドウに表示されます。

<remarks>

<remarks>
description
</remarks>

<remarks> タグを使用して、型または型メンバーの情報を追加し、<summary> で指定された情報を補足します。 この情報はオブジェクト ブラウザー ウィンドウに表示されます。 このタグに含める説明は、長くなる場合があります。 マークダウンに CDATA セクションを使用すると、簡単に記述できるようになります。 docfx などのツールでは、CDATA セクションのマークダウン テキストが処理されます。

メンバーの文書化

<returns>

<returns>description</returns>

<returns> タグは、戻り値を説明するためにメソッドの宣言のコメントで使用する必要があります。

<param>

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

• name: メソッド パラメーターの名前。 名前は引用符 (") で囲みます。 パラメーターの名前は、API シグネチャと一致する必要があります。 1 つ以上のパラメーターがカバーされていない場合、コンパイラによって警告が発行されます。 また、name の値がメソッド宣言の仮パラメーターと一致していない場合も警告が発行されます。

<param> タグは、メソッドのいずれかのパラメーターを記述するために、メソッド宣言のコメントで使用する必要があります。 複数のパラメーターをドキュメント化するには、複数の <param> タグを使用します。 <param> タグのテキストは、IntelliSense、オブジェクト ブラウザー、コード コメント Web レポートに表示されます。

<paramref>

<paramref name="name"/>

• name: 参照されるパラメーターの名前。 名前は引用符 (") で囲みます。

<paramref> タグを使用すると、<summary> または <remarks> ブロックなどのコード コメント内の単語がパラメーターを参照することを示すことができます。 この単語を、太字や斜体のフォントを使うなど、何らかの独自の方法で書式設定するために XML ファイルを処理できます。

<exception>

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

• cref = "member": 現在のコンパイル環境から使用できる例外の参照。 コンパイラは、指定された例外が存在し、出力の XML で member が正規要素名に変換されることを確認します。 member は引用符 (") で囲む必要があります。

<exception> タグを使用すると、スローできる例外を指定できます。 このタブは、メソッド、プロパティ、イベント、インデクサーの定義に適用できます。

<value>

<value>property-description</value>

<value> タグを使用して、プロパティが表す値を記述することができます。 Visual Studio .NET 開発環境では、コード ウィザードを使用してプロパティを追加するときに、新しいプロパティの <summary> タグが追加されます。 手動で <value> タグを追加して、プロパティが表す値を記述します。

ドキュメント出力の書式設定

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

<para> タグは、<para>、<、または > などのタグ内で使用し、テキストに構造を追加することができます。 <para> を使用して、ダブル スペースの段落を作成します。 段落をシングル スペースにする場合は、<br/> タグを使用します。

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

<listheader> ブロックを使用して、テーブルまたは定義リストの見出し行を定義します。

テーブルを定義する場合、

• 必要なことは、見出しに term のエントリを指定することだけです。
• リストの各項目は、<item> ブロックで指定されます。 それぞれの item について、description のエントリのみを指定する必要があります。

定義リストを作成する場合、

• 見出しに term のエントリを指定する必要があります。
• リストの各項目は、<item> ブロックで指定されます。 各 item には、term と description の両方が含まれている必要があります。

リストまたはテーブルでは、必要な数の <item> ブロックを使用できます。

<c>

<c>text</c>

<c> タグを使用すると、説明内のテキストをコードとしてマークする必要があることを指定できます。 複数行をコードとして指定する場合は、<code> タグを使用します。

<code>

<code>
    var index = 5;
    index++;
</code>

<code> タグを使用して、複数行をコードとして指定します。 説明内の単一行テキストをコードとしてマークすることを示すには、<c> を使用します。

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

<example> タグを使用すると、メソッドまたは他のライブラリ メンバーの使用例を指定できます。 例では、一般的に、<code> タグが使用されます。

ドキュメント テキストの再使用

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

基底クラス、インターフェイス、および同様のメソッドから、XML コメントを継承します。 inheritdoc を使用することにより、重複する XML コメントの不要なコピーと貼り付けを行う必要がなくなり、XML コメントが自動的に同期されたままになります。 <inheritdoc> タグを型に追加する場合、すべてのメンバーがコメントも継承します。

• cref: ドキュメントの継承元であるメンバーを指定します。 現在のメンバーで既に定義されているタグは、継承されたタグによってオーバーライドされません。
• path: ノード セットが表示されるようになる XPath 式クエリ。 この属性を使用すると、継承されたドキュメントに含めるタグ、または除外するタグをフィルター処理できます。

基底クラスまたはインターフェイスに XML コメントを追加し、inheritdoc によって、そのコメントが実装するクラスにコピーされるようにします。 同期メソッドに XML コメントを追加し、inheritdoc によって、そのコメントが同じメソッドの非同期バージョンにコピーされるようにします。 特定のメンバーからコメントをコピーする場合は、cref 属性を使用してそのメンバーを指定できます。

<include>

<include file='filename' path='tagpath[@name="id"]' />

• filename: ドキュメントを含む XML ファイルの名前。 ファイル名は、ソース コード ファイルの相対パスを使用して修飾することができます。 filename を単一引用符 (' ') で囲みます。
• tagpath: タグの name につながる filename タグのパス。 パスを単一引用符 (' ') で囲みます。
• name: コメントの前に配置するタグの名前指定子。name には id が含まれます。
• id: コメントの前に配置するタグの ID。 ID は引用符 (") で囲みます。

<include> タグを使用すると、ソース コード内の型とメンバーを記述する別のファイル内のコメントを参照することができます。 ドキュメント コメントをソース コード ファイル内に直接配置する代わりに、外部ファイルを含めることができます。 別のファイルにドキュメントを配置することで、ソース コードから分離して、ソースの制御をドキュメントに適用できます。 1 人のユーザーがソース コード ファイルをチェックアウトし、他のユーザーがドキュメント ファイルをチェックアウトすることができます。<include> タグでは、XML XPath 構文を使用します。 <include> の使用をカスタマイズする方法については、XPath に関するドキュメントを参照してください。

たとえば、次のソース コードでは、<include> タグを使用して注釈を含めています。 ファイル パスはソースに対する相対パスです。

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

インクルード ファイルの XML ソースを次の例に示します。 これは、C# コンパイラによって生成された XML ファイルと同じ構造になっています。 XPath 式で識別できる限り、XML ファイルには複数のメソッドまたは型のテキストを含めることができます。

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

このメソッドの XML 出力を次の例に示します。

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

ヒント

.NET ランタイム チームは、ドキュメントで幅広く <include> タグを使用しています。 dotnet/runtime リポジトリを検索すると、多くの例を確認できます。

リンクおよび参照の生成

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>

• cref="member": 現在のコンパイル環境から呼び出すことができるメンバーまたはフィールドへの参照。 コンパイラは、指定されたコード要素が存在するかどうかを確認し、member を出力 XML 内の要素名に渡します。 メンバーは引用符 (") で囲む必要があります。 別の終了タグを使用して、"cref" に異なるリンク テキストを指定できます。
• href="link": 特定の URL へのクリック可能なリンク。 たとえば、<see href="https://github.com">GitHub</see> によって生成されるクリック可能なリンクには、https://github.com にリンクされたテキスト GitHub が含まれます。
• langword="keyword": true のような言語キーワード、または他の有効な キーワード の 1 つです。

<see> タグを使用すると、テキスト内からリンクを指定できます。 テキストが参照セクションに配置されていることを示すには、<seealso> を使用します。 コード要素のドキュメント ページへの内部ハイパーリンクを作成するには、cref 属性を使用します。 型パラメーターを含めて、ジェネリック型またはメソッドへの参照を指定します (例: cref="IDictionary{T, U}")。 また、href も、ハイパーリンクとして機能する有効な属性です。

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>

• cref="member": 現在のコンパイル環境から呼び出すことができるメンバーまたはフィールドへの参照。 コンパイラは、指定されたコード要素が存在するかどうかを確認し、member を出力 XML 内の要素名に渡します。 member は引用符 (") で囲む必要があります。
• href="link": 特定の URL へのクリック可能なリンク。 たとえば、<seealso href="https://github.com">GitHub</seealso> によって生成されるクリック可能なリンクには、https://github.com にリンクされたテキスト GitHub が含まれます。

<seealso> タグを使用して、「関連項目」セクションに表示するテキストを指定することができます。 <see> タグを使用すると、テキスト内からリンクを指定できます。 summary タグ内に seealso タグを入れ子にすることはできません。

cref 属性

XML ドキュメントタグの cref 属性は、"コード参照" を意味します。タグの内部テキストが、タイプ、メソッド、プロパティなどのコード要素であることを指定します。 DocFX や Sandcastle のようなドキュメント ツールでは cref 属性が使用されて、型やメンバーが文書化されるページのハイパーリンクが自動的に生成されます。

href 属性

href 属性は、Web ページへの参照を意味します。 これを使用すると、API またはライブラリに関するオンライン ドキュメントを直接参照できます。

ジェネリック型とメソッド

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>

• TResult: 型パラメーターの名前。 名前は引用符 (") で囲みます。

<typeparam> タグは、型パラメーターを説明するためにジェネリック型またはメソッドの宣言のコメントで使用する必要があります。 ジェネリック型またはメソッドの型パラメーターごとにタグを追加します。 <typeparam> タグのテキストは、IntelliSense に表示されます。

<typeparamref>

<typeparamref name="TKey"/>

• TKey: 型パラメーターの名前。 名前は引用符 (") で囲みます。

ドキュメント ファイルを使用するときに何らかの方法で単語の書式 (斜体など) を指定するには、このタグを使用します。

ユーザー定義タグ

この記事で示したすべてのタグは、C# コンパイラで認識されるタグを表します。 ただし、ユーザー独自のタグも自由に定義できます。 Sandcastle などのツールを使用すると、<event>、<note> などの追加のタグや、名前空間の文書化もサポートされます。 カスタムまたは社内のドキュメント生成ツールも標準タグで使用でき、HTML から PDF への複数の出力形式をサポートできます。