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

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

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

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

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> も検証されます。

注意

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

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

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

一般的なタグ

<summary>

<summary>description</summary>

<summary> タグは、型または型メンバーの説明に使用します。 型の説明に補足情報を追加するには、<remarks> を使用します。 DocFXSandcastle などのドキュメント ツールでコード要素のドキュメント ページへの内部ハイパーリンクを作成できるようにするには、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> タグは、<summary><remarks>、または <returns> などのタグ内で使用します。このタグを使用すると、テキストに構造を追加することができます。 <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> ブロックで指定されます。 定義リストを作成する場合は、termdescription の両方を指定する必要があります。 ただし、テーブル、箇条書きリスト、または番号付きリストの場合は、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 に関するドキュメントを参照してください。

<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 などの言語キーワード。

<see> タグを使用すると、テキスト内からリンクを指定できます。 テキストが「関連項目」セクションに配置されていることを示すには、<seealso> を使用します。 コード要素のドキュメント ページへの内部ハイパーリンクを作成するには、cref 属性を使用します。 型パラメーターを含めて、ジェネリック型またはメソッドへの参照を指定します (例: 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 属性は "コード参照" を意味します。 タグの内部テキストが、型、メソッド、プロパティなど、コード要素であることを指定します。 DocFXSandcastle のようなドキュメント ツールでは 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 への複数の出力形式をサポートできます。