XML ドキュメント コメント
XML形式のマークアップを使用して、型やメンバの説明をコードに埋め込むことができます。
記述方法
ドキュメント コメントと認識させるには、コメント行を「///」で始めます。
/// <summary>
/// Loadイベントを発生させます
/// </summary>
/// <param name="e">イベントデータを格納しているEventArgs</param>
protected override void OnLoad( EventArgs e )
{
}
事前定義のXMLタグ
| タグ | 対象 | 説明 |
|---|---|---|
| <summary> | メンバ | 「概要」を記述する |
| <remarks> | 型 | 「詳しい説明」を記述する |
| <example> | メンバ、型 | 「サンプル・コード」を記述する |
| <value> | クラス | 「プロパティ」の説明を記述する |
| <exception> | メソッド | 「例外」の説明を記述する (cref属性で例外の型を指定できる) |
| <include> | 外部ファイルに書かれたドキュメント コメントを引用する (引用元をfile属性とpath属性で指定する) |
|
| <typeparam> | ジェネリック型のパラメータを説明する |
| タグ | 対象 | 説明 |
|---|---|---|
| <param> | メソッド | 「引数」の説明を記述する (name属性でパラメータを指定する) |
| <returns> | 「戻り値」の説明を記述する | |
| <see> | クラス、 クラスメンバ |
「リンク」を記述する (cref属性でリンク先を指定する) |
| <seealso> | 「参照」を記述する (cref属性で参照先を指定する) | |
| <permission> | 「アクセス許可」を記述する |
<see>
cref属性で指定するリンク先がオーバーロードされていると、「warning CS0419: '***' は cref 属性内のあいまいな参照です。'***()' を仮定しますが、'***(type)' を含む別のオーバーロードに一致した可能性もあります。」として警告されます。cref 属性 - C# プログラミング ガイド | Microsoft Learn
書式設定
| タグ | 説明 | 適用箇所 |
|---|---|---|
| <para> | 「段落」を作る |
|
| <c> | 指定箇所を「コード表記」にする | |
| <paramref> | 指定箇所を「引数表記」にする | |
| <list> | 箇条書きや番号付きの「リスト」を作る | |
| <listheader> | 「リスト」のヘッダを作る | |
| <item> | 「リスト」の項目を作る | |
| <typeparamref> | 単語の書式 (斜体など) を指定する | |
| <code> | 複数行を「コード表記」にする | <example> |
外部アセンブリから参照する方法 (IntelliSenseでの表示)
たとえばコードをDLLとして作成した場合などに、そのコメントを外部から参照できるようにする方法について解説します。このようにすることで IntelliSenseでもコメントが表示されるようになります。/doc (C# コンパイラ オプション) | MSDN
コメントをアセンブリと同名のXMLファイルとして出力し、それをアセンブリと同一のフォルダに置きます。これでアセンブリを参照したときに、コメントの書かれたXMLファイル (ドキュメント ファイル) も参照されるようになります。
ドキュメント ファイルの作成方法
C#でVisual Studioから前述の処理を行うには、プロジェクトのプロパティの[ビルド]タグにある[XML ドキュメント ファイル]にチェックを入れ、出力するファイル名を設定します。
参考
Microsoft Learnから検索