プログラムに XML ドキュメントコメントを記載する - Visual C# プログラミング

Microsoft Visual Studio 2005 にて C# プログラミングをしていると、メソッド名やその引数を入力しようとしているときに、それに関する詳細な説明文が画面に表示されることに気がつきます。

こういうコメントが表示されると、とってもプログラミングしやすいものですね。それだけでなく、後でコードを読む時にも大きな手助けとなってくれそうです。ただ、あらかじめ用意されているメソッドなどを入力する時にはそれが表示されるのですけど、自分で宣言した関数やクラスなどで普通にコメントを書いただけでは説明文は表示されてくれません。

同じように自分で作成したクラスなどの説明文を表示させたい時には、C# の "XML ドキュメントコメント" の約束に従った方法でコメントを記載してあげる必要があるようでした。

大きなルールとしては、コメントを "//" ではなく "///" で書き始める必要がある感じです。その中で定められたタグを用いて情報を記載してあげることで、その内容が解釈されて、必要な箇所でその内容が自動的に表示される感じになります。

たとえばメソッドのコメントを設定したい場合には、目的のメソッドの直前にて <summary> タグを使用します。これによって、タグ内に指定した文字列をそのメソッドの説明とすることができます。また、続けて <param> タグを利用することによって、メソッドに渡す引数の説明文も記載することができるようになります。

例として、二つの値 ( a, b ) を足し算して返す関数 Addition を実装する場合を挙げてみます。

最初の <summary> にて Addition 関数自体のコメントを設定して、そのタグを閉じた後で、続いて <param> タグによって引数のコメントを設定しています。<param> タグには "name" 属性を指定することができて、それによってどの引数の説明であるかを指定することができるようになっています。

また、戻り値の説明を記載するために <returns> タグも利用しています。処理内で発生する例外を告知するには <exception cref="System.Exception"></exception> というように、<exception> タグを用いて指定します。複数種類の例外を発生させる可能性がある場合には、このタグをいくつも登録することでそれらを全て記載することが可能です。

他にもいろいろ使用できるタグがあるようですけど、とりあえずのプログラミングではこれくらいで十分そうな感じがしました。詳しくは MSDN ライブラリの "XML ドキュメント コメント （C# プログラミング ガイド）" などを参照してみてください。

[ もどる ]