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

2025-07-22

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

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

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

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

ドキュメントは整形式の XML である必要があります。 XML が正しい形式ではない場合、コンパイラによって警告が生成されます。ドキュメントファイルには、エラーが発生したことを示すコメントが含まれます。
推奨されるタグの一部には特別な意味があります。
- <param> タグは、パラメーターの記述に使用します。このタグがあると、コンパイラは、パラメーターが存在すること、およびすべてのパラメーターがドキュメントで記述されていることを確認します。検証が失敗する場合は、コンパイラが警告を生成します。
- cref 属性は任意のタグにアタッチされて、コード要素を参照することができます。コンパイラは、このコード要素が存在することを確認します。検証が失敗する場合は、コンパイラが警告を生成します。コンパイラは、using 属性内で記述されている型を探す際、すべての cref ディレクティブを考慮に入れます。
- <summary> タグは、型またはメンバーに関する追加情報を表示するために、Visual Studio 内の IntelliSense によって使用されます。
 
 注意
 
 XML ファイルでは、型とメンバーに関する完全な情報は提供されません (たとえば、型の情報は含まれません)。型またはメンバーに関する完全な情報を取得するには、ドキュメントファイルと併せて、実際の型またはメンバーでリフレクションを使う必要があります。
開発者は、独自のタグセットを自由に作成できます。コンパイラにより、これらのタグが出力ファイルにコピーされます。

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

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

注意

 などの HTML タグは、ドキュメントコメント内の書式設定に役立ちます。   タグは改行を作成し、他の 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> **
- 
- 
- 
-  
- <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>description</summary>

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

<注釈>

<remarks>
description
</remarks>

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

メンバーの文書化

< 戻り値>

<returns>description</returns>

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

<パラメータ>

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

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

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

<paramref>

<paramref name="name"/>

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

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

<例外>

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

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

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

<価値>

<value>property-description</value>

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

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

<パラメータ>

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

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

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

/// <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 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>
    var index = 5;
    index++;
</code>

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

<例>

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

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

<b>text</b>

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

<私>

<i>text</i>

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

<u>text</u>

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

Line one<br/>Line two

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

<ある>

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

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

注意

コンパイラは、非推奨の 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 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 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 が含まれます。 hrefはコード参照用に設計されており、外部 URL のクリック可能なリンクは作成されないため、外部 Web ページにリンクする場合は、crefの代わりにcrefを使用します。
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 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 への複数の出力形式をサポートできます。

次の方法で共有

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

一般的なタグ

<概要>

<注釈>

メンバーの文書化

< 戻り値>

<パラメータ>

<paramref>

<例外>

<価値>

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

<パラメータ>

<リスト>

<c>

<コード>

<例>

<b>

<私>

<u>

<br/>

<ある>

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

<inheritdoc>

<含める>

リンクおよび参照の生成

<見る>

<関連項目>

cref 属性

href 属性

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

<typeparam>

<typeparamref>

ユーザー定義タグ

フィードバック

その他のリソース

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

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