.NET コードを XML コメントで文書化する方法

あらゆるプロフェッショナルな環境において、コードにコメントを付けて適切に文書化することは、長期的な可読性のために必要です。.NET コードに対して、マイクロソフトは、強化された IDE サポートを提供する XML ベースのコメントシステムを提供しています。

XML コメントとは何ですか？

基本的に、XML コメントは三重スラッシュ（///）で示される特別な種類のコメントです。

///

) および XML タグを使用して、コメントに構造を与えます。たとえば、シンプルな概要コメントは次のようになります:

これのポイントは、コード内の他の場所でこのメソッドを使用しようとするとき、Visual StudioがXMLを参照し、Intellisenseのポップアップに直接いくつかの情報を追加できるということです。このシステムはすべての種類の型に対応しており、戻り値や個々のパラメータの文書化にも使用できます。また、アセンブリを配布する際には、XMLファイルも一緒に配布することで、あなたのクラスライブラリを使用する誰でも同じ機能を利用できるようになります。これにより、DocFXやSandcastleなどの静的文書生成ツールを簡単に使用することも可能になります。

驚くべきことに、この機能はほとんど.NET専用のものです。他の言語でこのプラクティスを使うことを妨げるものはありませんが、これはMicrosoftが自社の言語やエディターに対して非常にサポートしているものですし、他の言語は通常、適切なサポートがありません。この機能が他の言語やエディターにも拡張されることを願っています。それはかなり普遍的に役立ちます。

使うのはとても簡単です。スラッシュキーを3回押すだけです。

///

メソッド、クラス、または他のタイプの上に ') ' を置くと、Visual Studio が入力用のテンプレートを挿入します。これにより、手動で入力する手間が省けるため、従来の二重スラッシュコメントを使わない理由は本当にありません。

メソッドに戻り値の型やパラメータがある場合、Visual Studioはそれらのためにフィールドを生成します。メソッドを使用する際にコメントが表示されます。

標準は多くの種類のタグをサポートしています。

• メソッドを使用するたびに、Intellisense に表示されます。
• は要約のようなもので、Intellisense には表示されません（拡張ドキュメントを書くのに役立ちます）。
• は戻り値の型を文書化します。
• は、開発者にメソッドがスローできる例外を知らせます。
• は、クラスプロパティのためのリターンのようなものです。
• はドキュメント用のコード例を示しています（と一緒に使用してください）。
• と は、通常はオーバーロードを文書化するために他のメソッドへのクリックできるリンクを生成します。
• は要素を順番に並べるためにリストを使用できます。

MicrosoftのXMLコメント標準に関するドキュメントを読んで、詳細を知ることができます。