XMLドキュメントコメントに関するメモ

XMLドキュメントコメントを真面目に書こうと思って調査したので、メモとして残しておきます。

XMLドキュメントコメントの書き方

まず、基本的なXMLドキュメントコメントの書き方はMSDNで。

ガイドライン

XMLドキュメントを書く際のガイドラインや注意点は、以下が参考になります。

書くべき内容

以下はJavadocの記事ですが、C#でもそのまま適用することができます。チェックリストはよく利用させてもらってます。

その他ちょっとしたネタ

  • 改行
<br/>
  • Genericsの<>は{}で書くことができます。*1
<see cref="MyTemplate{TDataType}"/>
  • namespaceの説明を追加するには、生成されたXMLドキュメントに下記のmemberを追記します。
<?xml version="1.0"?>
<doc>
 <members>
   <member name="N:MyNamespace">
     <summary>
       namespaceの説明
     </summary>
   </member>
 </members>
</doc>
  • partial classにはどれか1つのクラスにコメントを書きます。*2
  • などで参照している型が見つからない場合、ビルド時に警告してくれます。また、生成されたXMLドキュメントを!:で検索するとエラーが見つかります。


あとは、コメントの内容を日本語と英語を切り替えられるようにできればよいんですが。doxygenだと@if〜@endifで書けるけど、一般的な方法はないのかなぁ。

*1:http://d.hatena.ne.jp/saiya_moebius/20090129/1233243475

*2:http://d.hatena.ne.jp/takakuro/20060326/1143325380