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

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

C# 言語リファレンスには、C# 言語の最新リリース バージョンが記載されています。 また、今後の言語リリースのパブリック プレビューの機能に関する初期ドキュメントも含まれています。

このドキュメントでは、言語の最後の 3 つのバージョンまたは現在のパブリック プレビューで最初に導入された機能を特定します。

ヒント

C# で機能が初めて導入された時期を確認するには、 C# 言語バージョン履歴に関する記事を参照してください。

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

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

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

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

    注意

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

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

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

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

注意

<br/>などの HTML タグは、ドキュメント コメント内の書式設定に役立ちます。 <br/> タグは改行を作成し、他の HTML タグはテキストの書式設定を提供します。 これらのタグは、IntelliSense のヒントと生成されたドキュメントで機能します。

• 複数の要素に使用される 一般的なタグ - これらのタグは、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> **
  • <b>
  • <i>
  • <u>
  • <br/>
  • <a>
• ドキュメント テキストの再使用 - これらのタグを使用すると、ツールで 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> タグを使用して、メソッドのパラメーターの 1 つを記述します。 複数のパラメーターをドキュメント化するには、複数の <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>

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

<para>と<br/>の違いを示す例を次に示します。

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<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>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</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>を使用して、説明内の 1 行のテキストをコードとしてマークします。

<example>

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

<example> タグを使用して、メソッドまたはその他のライブラリ メンバーを使用する方法の例を示します。 一般的な例として、 <code> タグの使用が含まれます。

<b>

<b>text</b>

ドキュメント コメント内でテキストを太字にするには、 <b> タグを使用します。 コンパイラと Visual Studio は、この HTML 書式設定タグを検証します。 書式設定されたテキストが IntelliSense と生成されたドキュメントに表示されます。

<i>

<i>text</i>

ドキュメント コメント内でテキストを斜体にするには、 <i> タグを使用します。 コンパイラと Visual Studio は、この HTML 書式設定タグを検証します。 書式設定されたテキストが IntelliSense と生成されたドキュメントに表示されます。

<u>

<u>text</u>

ドキュメント コメント内のテキストに下線を引くには、 <u> タグを使用します。 コンパイラと Visual Studio は、この HTML 書式設定タグを検証します。 書式設定されたテキストが IntelliSense と生成されたドキュメントに表示されます。

<br/>

Line one<br/>Line two

ドキュメント コメント内に改行を挿入するには、 <br/> タグを使用します。 このタグは、二重間隔の段落を作成する <para> タグではなく、1 つの間隔を持つ段落が必要な場合に使用します。

<a>

<a href="https://example.com">Link text</a>

ドキュメント コメント内にハイパーリンクを作成するには、 <a> タグを使用します。 href属性は、リンク先の URL を指定します。 コンパイラと Visual Studio は、この HTML 書式設定タグを検証します。

注意

コンパイラは、非推奨の HTML である <tt> タグも検証します。 インライン コードの書式設定には、代わりに <c> タグを使用します。

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

<inheritdoc>

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

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

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

注意

Visual Studio は、文書化されていないメンバーの XML ドキュメントを自動的に継承し、文書化されたメンバーをオーバーライドまたは実装します。 この機能では、 <inheritdoc> タグを必要とせずに、IntelliSense とクイック ヒントに継承されたドキュメントが表示されます。 ただし、この自動継承は Visual Studio IDE 内でのみ適用され、コンパイラによって生成される XML ドキュメント ファイルには影響しません。

配布するライブラリのパブリック API の場合は、 <inheritdoc> タグを明示的に使用するか、完全なドキュメントを提供して、生成された XML ドキュメント ファイルにライブラリのコンシューマーに必要なすべての情報が含まれていることを確認します。

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

<include>

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

• filename: ドキュメントを含む XML ファイルの名前。 ファイル名は、ソース コード ファイルに対する相対パスで修飾できます。 filename を単一引用符 (' ') で囲みます。
• tagpath: タグの filename につながる name タグのパス。 パスを単一引用符 (' ') で囲みます。
• 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> によって生成されるクリック可能なリンクには、GitHub にリンクされたテキスト https://github.com が含まれます。 crefはコード参照用に設計されており、外部 URL のクリック可能なリンクは作成されないため、外部 Web ページにリンクする場合は、crefの代わりにhrefを使用します。
• langword="keyword": true のような言語キーワード、または他の有効なキーワードの 1 つです。

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

外部 URL を参照するときの cref と href の違いを示す例を次に示します。

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<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> によって生成されるクリック可能なリンクには、GitHub にリンクされたテキスト https://github.com が含まれます。

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

cref 属性

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

href 属性

href 属性は、Web ページへの参照を意味します。 これを使用すると、API またはライブラリに関するオンライン ドキュメントを直接参照できます。 ドキュメント コメント内の外部 URL にリンクする必要がある場合は、hrefではなくcrefを使用して、IntelliSense のヒントと生成されたドキュメントでリンクがクリック可能であることを確認します。

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

<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 への複数の出力形式をサポートできます。