コメントでVisual Studio上にコード説明を表示させる方法
Visual Studioでコーディングしているときにメソッドやクラスの説明を書きたいと思ったことはないでしょうか。
コードの入力中や、カーソルを合わせた時に出るウインドウにある説明のことです。
ポップアップして機能やクラスの説明があるとコードを書いているときに楽でいいですよね。
そこで今回は、コメントを最大限に活用するために
コード記載中に出せるコメントの書き方、
そして、書いたコメントをさらにドキュメントとして出力する方法について紹介します。
目次
コメントでVisual Studio上にコード説明を表示させる方法
visual studioでC#をコーディングしているとき、
ポップアップでクラスやメソッドの内容を教えてくれる機能は便利ですよね。
定義に移動したりせずとも機能を簡単に確認できます。
そんなコーディングを楽にしてくれるメソッドやクラスの説明は、
「///」スラッシュ3回つとXML形式のコメントを記載することで実現できます。
試しにやってみましょう。
説明を書きたいメソッドのすぐ上でスラッシュを三回入力します。
すると、visual studioは自動でポップアップするためのコメントテンプレートを用意してくれます。
試しにsummaryタグの中に何か書いてみましょう。
これはクラスにコメントした例です。このコードをVisual Studioで呼び出しから確認すると、
こんな感じで、書いたコメントが表示されるようになります。
Visual Studio上で表示されるタグ5つ
Visual Studioで表示させるためのコメントが書く方法の次は
ウィンドウに表示できるコメントの種類について紹介します。
Visual Studioで表示できる主要なタグはこちら
- <summary>
- <param>
- <returns>
- <typeparam>
- <value>
それぞれ役割によって、個別のタグを持ちます。
ひとつずつ紹介しますので、見ていきましょう。
<Summary>は目的や「何」を表すタグ
最初に紹介するのは、すでに紹介したsummaryタグです。
今回紹介するタグの中で最も重要。
Visual Studio上で表示されるタグの中でどれか一つしか使えないとしたならば、
このsummaryタグを使います。
クラス、メソッド、プロパティ、etc.と幅広く使用することのできるタグで、
スラッシュ3回で生成されるコメントにはこのsummaryタグがあります。
説明なら、何を書いても良いのです。
しかし、他のタグとの使い分けをするなら、「目的:What（何）」を記載するためのタグとえるでしょう。
例として、既存のメソッドを見てみます。
Computes the sum of a sequence of int values.
日本語にすると、「数値のシーケンスの合計を計算します。」
メソッド名からもわかる通り、「何」をしているかがわかる内容になっていますね。
summaryタグには、自由に説明を記載できるのですけれども、
目的を意識してコメントを記述するとより、伝わりやすいコメントになるのでオススメです。
<param>は引数の説明用のタグ
次に、メソッドの引数で使用するparamタグです。
メソッドの引数に合わせて、複数定義することができます。
<param name=”arg1″>引数1</param>のように、
引数arg1をname属性で指定すれば、タグの中で説明が可能です。
このparamタグに記載した内容の表示はほかのタグとは違っていて、
コーディングの途中でポップアップし、表示されます。
実際にVisual Studioでどのように見えるかというと、
最初の引数を書くときには、第一引き数の説明が表示されて、
第二引数の記述に移動すると、
引き数の説明部分が切り替わっていきます。
コード入力中に表示されるタイプのコメントです。
ポップアップウインドウにつねに表示されているわけではないので注意しましょう。
<returns>はメソッドやプロパティの返値を説明するタグ
続いて、返値に対応するタグreturnsタグです。
<typeparam>はジェネリックを説明するタグ
typeparamタグはジェネリック型を利用するときに使うタグです。
使い方はparamタグと同じで、引き数名をname属性で指定が可能です。
こんな感じ。
このように、ジェネリック「T」に対して説明が可能です。
今回のサンプルでの紹介はジェネリック型は一つですが、
ジェネリック型の数に応じてタグを複数作成できます。
複数タグを作れることもparamタグと特徴が一緒ですね。
<value>はそのうち使われなくなるかもしれないタグ
こちらはプロパティに使われるタグです。
もしくは、よく使われていた。といったほうが良いかもしれません。
今回は参考情報として、プロパティに適用する例をとりあげます。
イメージはプロパティの補足事項を記述するためのタグです。
見え方としては、こんな感じになります。
しかし、最近では使われていない印象はぬぐえません。
大抵はsummaryタグとreturnsタグで事たりるためです。
Linqで利用できる基本的なプロパティをみても、
summaryタグとreturnsタグが使われていることを確認できるのですけれども、
valueタグは使われていないことがわかります。
むしろ画像だけで比較すると、returnsにとって替わられていますね。
コメントからドキュメントへ活用する方法
XML形式のコメントはVisual Studioにポップアップさせるだけのコメントではありません。
もう一つの機能としてドキュメント生成機能があります。
ドキュメント生成ができると、担当している開発の資料作成がはかどる可能性があります。
ここでは、ドキュメント出力形式ごとに、
- XML形式でドキュメント出力する方法
- HTML形式でドキュメント出力する方法
XMLでの利用、そして見やすい資料にして出力してくれるHTML形式の順で紹介していきます。
XML形式でドキュメント出力する方法
まずXML形式で出力する方法です。ビルド時にXML生成が可能です。
これはVisual Studioの標準機能に搭載されているのですぐにでも使うことができます。
XMLコメントを出力したい対象のプロジェクトをVisual Studio上で、
右クリック＞プロパティで選択してください。
プロジェクトプロパティのウインドウが開いたら
ビルド＞出力と進んでください。
そこに「XMLドキュメントファイル」のチェックボックスがあるので、
チェックを入れてXMLファイル出力を指定しましょう。
今回はcsprojのファイルと同じ階層に出力するために、「.\ConsoleApp.xml」としました。
あとはプロジェクトをビルドするとxmlファイルが生成されます。
HTML形式でドキュメント出力する方法
XML形式でコメントが出力する方法がわかったので、
自前でXMLからHTMLに変換していってもよいですが、
いきなりHTMLを生成できるツールがあるのでそちらを紹介いたします。
- DoxygenでHTML化
- Doxywizardで簡単にHTML出力
- Doxywizard/Doxygenのインストール
- Doxywizardの使い方
DoxygenでHTML化ができる
HTML化ができるDoxygenというツールでHTMLを生成します。無料でつかうことができます。
もとはC++の利用がメインでしたが、C#をはじめ、
PHP、Java、Pythonでも使えるツールです。
1997年にリリースされたようで、
いまでも多くのひとがGithubで開発をしています。
このDoxygenを使えば、プログラム中のコメントから
HTMLのドキュメントを作ることができます。
Doxywizardで簡単にHTML出力しよう
DoxygenでコメントのHTML化ができるのですけれども
Doxywizardを利用するとさらにHTML化が簡単です。
というのもDoxygenはかなり機能が多彩で、柔軟な出力ができるツールです。
しかし、設定が多いゆえに使いこなすのには学習が必要になります。
ドキュメントも提供されているのですが、それなりの量があって
把握するには時間がかかるでしょう。
そこで、大抵の設定を直感的に操作できるGUIツールが提供されました。
それがDoxywizard。
今回は操作が簡単にできるDoxywizardを使ってHTML化する方法に注目します。
Doxywizard/Doxygenのインストール
インストールについてです。
Doxygenをインストールで、Doxywizardも一緒に入ります。
公式サイトから、インストーラーやソースコードをダウンロードする方法をたどることができますので、ご覧ください。
また、各種インストール方法もドキュメントがありますので、そちらのリンクも載せておきます。
>>Doxywizard/Doxygenのダウンロードはこちら
>>Doxywizard/Doxygenのインストール方法はこちら
ソースコードからビルドもよいですし、
windowsをお使いの方は、「A binary distribution for Windows」の項目にインストーラーがあるので
クリック・ポチポチでインストール完了できます。
インストールできるとこのようなアイコンのアプリが入ります。
Doxywizardの使い方
DoxywizardでC#のコメントを出力する大まかな流れを説明します。
まずは上部のテキストボックスにディレクトリを指定してみてください。
この画像例の場合、「D:\dummy\html」配下にhtmlが出力されていきます。
細かい使い方などは別記事でいずれ紹介できればと思います。
WizardでC#のコメント出力設定を行う
まずはProjectで「Source code directory」の項目に.csprojファイルが含まれるディレクトリを指定します。
また、「Scan recursively」にチェックボックスを入れます。
「Scan recursively」にチェックをいれることで、サブディレクトリも含めてソースコードのコメントを出力することができます。
ModeでC#を選びましょう。
Exportの設定はwizardでおおよそ完了
さまざまな種類の設定があり、
Wizardで設定した言語用の変更がすでにExportに適用されています。
もちろん、自分なりの変更を加えることもできます。
例えば言語を日本語で出力したり、などなど。
興味のある方は見てみてください。
今回はExportの設定を特に変更せずにHTML化します。
Runの利用：いざHTML出力
ここまで、設定はあらかた完了しているので、
Runタブの「Run doxygen」を実行してみましょう。
うまく、実行できると「Show HTML output」が押下できるようになり、
クリックすれば、html形式で出力されたドキュメントと見ることができます！
コメントからドキュメント生成するメリット
コメントを効果的に利用することで、維持管理のコストが下がります。
特に「ほぼコーディング」みたいなところまで、設計している場合は特に効果があるでしょう。
もし、設計書を記述して、コード中にもコメントしているなら、
コメントとドキュメントを各作業が統一されるので、手間が減ります。
また、ドキュメントが一元管理されることになるので、
資料を更新してコメントの更新忘れなどの漏れも仕組みで解決できます。
まとめ
今回の記事のまとめです。
- コーディング中にコードの説明をだすにはXML形式のコメントを使う
- 説明でよく使うタグはsummary、param、returns、typeparamで、summaryが一番重要
- XMLコメントはファイル（XML形式,HTML形式）として出力できる
- XML形式での出力はVisual Studioの標準機能でできる
- HTML形式での出力はDoxywizard（Doxygen）でできる
コメントやドキュメントはチームでの開発ではコミュニケーションの一つになるため重要です。
コメントをうまく活用して、コーディングを効率よく行いたいですね。
では。
