C#のドキュメントコメントを書く際の注意点
はじめに
C#にはドキュメントコメントというコメント記述法があり、定められた形式でコメントを記述することにより、自動的にドキュメントを作成することができる。詳細については『XML ドキュメント コメント (C#)』および『ドキュメント コメント用の推奨タグ (C#)』を参照のこと。本エントリでは、ドキュメントコメントを記述する際の注意点を記述する。
特殊文字
ドキュメントコメントは、ビルドによってXMLファイル化されるので、以下の特殊文字がある。ドキュメントコメントで特殊文字を使用したい場合、「&」から始まる代替文字列で記述する。以下で、「‥」の左側が特殊文字、右側が代替文字列。
- &‥&
- <‥<
- >‥>
- "‥"
<summary>内で<para>を使用しない
<summary>で、<para>を使って段落分けすると、VS2005でその内容がツールチップ表示される際、第1段落しか表示されないため。誤りではないが。
列挙体のそれぞれの値のドキュメントコメントには、<summary>のみを使用する
列挙体のそれぞれの値のドキュメントコメントに<summary>以外のタグを使っても、ドキュメント化されないため。
<example>は1つの対象につき1つまで
1つの対象に対して<example>を複数使用した場合、ヘルプファイルにした際の見た目が悪くなるため。2つ以上のサンプルがある場合、1つの<example>の中で<para>を使って段落分けする。
プロパティのコメントでは、<summary>内でデフォルト値に言及する
そうすれば、VS2005でプロパティのデフォルト値がツールチップ表示されることになる。