XML ドキュメント コメントでの、ジェネリックな型やメンバに付く

Csharp

要約

XML コメントにて Generic な型やメンバを参照する場合、IEnumerable{int} のように書くことができる。

ちょっとしたことだが、忘れがちな事である上、ぱっと検索しても出てこなかったのでメモってみた。

詳細

C# の XML コメントにて、特に、 や ... などで型やメンバの名前を書く場合に、それらが Generic であると面倒がある。

というのも、例えば といった表記は XML の仕様もあって不可能なので、 のように書かねばならないのである。

上のように < や > を &lt; や &gt; に文字実体参照にエスケープすれば問題ないのだが、文字実体参照だと見づらくなりやすいという問題がある。例えば、XML コメントで

<see cref="IEnumerable&lt;KeyValuePair&lt;Guid, Func&lt;string, string&gt;&gt;&gt;" />

と書いてあっても、判読しづらいし、このようなコメントを書くのも辛いものである。

ところが、実は C# の XML コメントで cref などに型名を書く場合、< や > の代わりに { や } を使うことができるのである。

そうすると、上の例は

<see cref="IEnumerable{KeyValuePair{Guid, Func{string, string}}}" />

のようになり、読みやすくなるし書きやすい。

実際、MSDN の <see> (C# プログラミング ガイド) のページにあるサンプルを見ても、 < や > は &lt; や &gt; であっても、{ や } であっても構わない旨が書いてある。

という訳で、XML コメントで Generic な型やメンバを指したい場合、< や > の代わりに { や } を使うのがおすすめである。