atsukanrockのブログ

Microsoft系技術を中心にぼちぼち更新します

C#のドキュメントコメントを書く際の注意点

はじめに

C#にはドキュメントコメントというコメント記述法があり、定められた形式でコメントを記述することにより、自動的にドキュメントを作成することができる。詳細については『XML ドキュメント コメント (C#)』および『ドキュメント コメント用の推奨タグ (C#)』を参照のこと。本エントリでは、ドキュメントコメントを記述する際の注意点を記述する。

特殊文字

ドキュメントコメントは、ビルドによってXMLファイル化されるので、以下の特殊文字がある。ドキュメントコメントで特殊文字を使用したい場合、「&」から始まる代替文字列で記述する。以下で、「‥」の左側が特殊文字、右側が代替文字列。

  • &‥&
  • <‥&lt;
  • >‥&gt;
  • "‥&quot;

<summary>内で<para>を使用しない

<summary>で、<para>を使って段落分けすると、VS2005でその内容がツールチップ表示される際、第1段落しか表示されないため。誤りではないが。

列挙体のそれぞれの値のドキュメントコメントには、<summary>のみを使用する

列挙体のそれぞれの値のドキュメントコメントに<summary>以外のタグを使っても、ドキュメント化されないため。

<example>は1つの対象につき1つまで

1つの対象に対して<example>を複数使用した場合、ヘルプファイルにした際の見た目が悪くなるため。2つ以上のサンプルがある場合、1つの<example>の中で<para>を使って段落分けする。

プロパティのコメントでは、<summary>内でデフォルト値に言及する

そうすれば、VS2005でプロパティのデフォルト値がツールチップ表示されることになる。