純規の暇人趣味ブログ

手を突っ込んで足を洗う

[VisualStudio]C++でもXMLドキュメントコメントを自動挿入したい!!

      2016/10/20    HimaJyun

神速の黒魔術、C++、Perlなんて屁でもない様な難読奇怪な言葉遣いで驚異的な速度を叩き出す闇の魔術で、一度その魅力に取り憑かれるともう二度と抜け出せないんだとか……

さて、そのC++ですが、VisualStudioで組んでいると、C#のXMLドキュメントコメント(一部の人の為に言い換えるとJavaDocやDoxygen)と同じ物が使えます。

ただ、VisualStudio 2015 Communityの段階では、なぜかそれを自動で挿入する機能はないみたいなので、今回はこれを自動で挿入出来る様にしてみようと思います。

ドキュメントコメント

結論から言ってしまえば、拡張機能を入れる事なのですが、それだけではつまらないので色々オマケ解説もしましょう。

正式名称が良く分からないので、ここではこの様なコメントを全てまとめて「ドキュメントコメント」と呼ぶ事にしましょう。

とりあえず、このドキュメントコメントを知らない人はここは読まないと思われますので、それらの説明は後回しにするとして、さっそく本文に参りましょうか。

C++でもXMLドキュメントコメント

例えば、C#(と言うよりVisualStudio?)では以下の様なXML形式のコメントを記入する事によって、ドキュメントコメントを利用出来ます。

/// <summary>
/// ほげぇ!!
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
private int hoge(String str) {
  return 114514;
}

シンタックスハイライトの調子が悪いので<>が大文字ですけどご愛敬。(これだからWordPressは……)

これを入れておくと、関数名にマウスカーソルを重ねた際に説明が表示され、関数呼び出しの際に引数の説明が表示されます。
visualstudio-cpp-xml-document-001

要は「/」を3つ入れる訳ですね、C#では///と入力した時点で自動的に<summary>や<param>が対象のメソッドに合わせて追加されます。

そして、この機能、C++でも利用できるのですが、「///」を入力した際の自動挿入には対応しておらず、手で<summary>なんて打ち込む必要がある。(C#を広めたいM$の意図的な物ではないかと勘ぐってしまう)

拡張機能で対処する

こう言う時、2013から追加されたCommunity版であれば拡張機能が利用出来る。(前までは有料版が必要だった)

探してみた所「Cpp Triple Slash」と言う文字通りの拡張機能で出来るみたい。

と言う訳で「ツール」->「拡張機能と更新プログラム」へと進む
visualstudio-cpp-xml-document-002

いつもどおり拡張機能を追加する、「Cpp Triple Slash」とでも検索しよう。

きっと出て来るであろうから、それを選択してダウンロード、インストールする。
visualstudio-cpp-xml-document-003

使い方

もはや解説の必要すらない。

単に「///」を入れるだけ、編集用にコメント部にIntelliSenseが使える様にもなっている。

/// <summary>
/// ほげぇ!!
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
	return 114514;
}

「///」を導入してコメントさえ入れてしまえば、後はカーソルを重ねたりした時の表示や、関数を呼び出す時の引数の説明なんかもそのまま利用出来る。

むしろなぜ自動挿入が標準の機能として提供されていないのかが分からない限り、MSさん……

個人的にはJavaDocの「/**」より「///」の方がキーから手を離さなくて済むので好きですね。

コメントいろは

とは言え、これだけでは流石に内容が白湯よりも薄いので、このドキュメントコメントのいろは……ちょっとだけ教えちゃう。

XMLを出力する

プロジェクトの構成プロパティから「C++->出力ファイル->XMLドキュメントファイルの生成」を「はい(/doc)」にする事で、ソースコード内のXMLドキュメントコメントをXMLとして出力することが出来ます。
visualstudio-cpp-xml-document-004

上手く扱えば(そう言うソフトを用意すれば)自動で公開用のMarkdownやらドキュメントを生産する事も出来るでしょう。

改行したい

JavaDocとかでも良くあることなんですけど、コメント内での改行はひと工夫必要。

普通に改行しただけではダメ。

/// <summary>
/// ほげぇ!!
/// ふがぁ!!
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
	return 114514;
}

ちなみに<br />とか付けて無理やり改行しようとしても「むだぁ!!」

改行したい時は<para>を使う。

/// <summary>
/// <para>ほげぇ!!</para>
/// <para>ふがぁ!!</para>
/// </summary>
/// <param name="str">文字列(はぁと</param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
	return 114514;
}

<para>は<param>とかでも使える。

/// <summary>
/// <para>ほげぇ!!</para>
/// <para>ふがぁ!!</para>
/// </summary>
/// <param name="str">
/// <para>もじれつぅ!!</para>
/// <para>すとりんぐぅ!!</para>
/// </param>
/// <returns>数値(すぅぱぁはぁと</returns>
int hoge(std::string str) {
    return 114514;
}

まぁ、見た目はJavaDocで<br>とか書き込むより綺麗だしすき。

さっきも書いたが、CppTripleSlashはドキュメントコメントでIntelliSenseが使えるので入力もラクチン

ドキュメントコメントの必要性

プログラミング初学者(が、こんな所を読むのかどうかは別として)、及びコメントを書かない人(私も面倒だと省きますが……(^^;))のために、ドキュメントコメントの素晴らしさ、必要性を軽く紹介しましょう。

例えば、JavaであればJavaDocと言うのが業界標準で、以下の様な形式でコメントを書く事でIDE上で様々な補助機能(?)が利用出来るようになります。

/**
 * ほげぇ!!
 * @param str 文字列(はぁと
 * @return 数値(すぅぱぁはぁと
 */
private int hoge(String str) {
	return 114514;
}

Javaで一般的なIDEのEclipseであれば、関数名にカーソルを重ねた際に以下の様に表示されます。
visualstudio-cpp-xml-document-005

VisualStudio、無念!!

残念ながらドキュメントコメントの表示はEclipseの方が優れているみたいです。(VisualStudioは実際に引数を入れる段階まで来ないと引数の説明が表示されない)

とにもかくにも、VisualStudioだろうがEclipseだろうか、この様に関数に「どのような処理を行うのか」「どのような引数が必要なのか」「どのような戻り値を得られるのか」を書いておくことで、実際に関数を利用する際に実装部まで飛んでソースコードを眺めたりする必要がなくなり、使いやすいプログラムになります。

優れたライブラリなんかはコメントの段階から既に下手なライブラリとの差があります。

とは言え、私も「分かりやすいコメント」と言うのは苦手なので、そこはどうすれば良いのか各自でググって頂ければと思われます。

 - プログラミング ,