C++で///を使ったコメント

Question

C++関係ないのかもしれませんが、最近コメント文で///とスラッシュを三つ使ったものをよく見ます。
VS2015で///を使うと//や/**/より濃い緑色になるのにも最近気が付きました。

そこで質問なのですが、///ってどういうときに使うものなのでしょうか？
なにか特別なことをコメントに残すときに使うのでしょうか？

Answer 1

メソッドや変数の上にC++やC#では「///」VBでは「'''」といったコメントアウトをすると、自動で残りのテキストをVisualStadioが表示してくれます。

/// <summary>
/// 名前
/// </summary>
/// <param name="hoge">変数名</param>
/// <returns>備考</returns>
public void test(int hoge)

といったコメントですが、別の場所でこれを呼び出してカーソルを合わせるとこの内容が吹き出しに出てくるため、説明文に使えます

Comments

[yaeyama]

回答ありがとうございます。
param name="hoge"と
int hogeが対応してるのですね。
わざわざコードまでありがとうございます。

[hmmm]

C++で自動で補完されますか？プロジェクトテンプレートでは見かけますが、Intellisenseは対応していない気がします。

[yaeyama]

hmmmさん
https://jyn.jp/visualstudio-cpp-xml-document/
拡張機能を追加すると補完できるみたいですね。

[hmmm]

@yaeyama さん。ありがとうございます。できました。

Answer 2

念の為に言うときますが、/// だとどうこうってのは言語仕様で規定されているものではなく、
あくまで Visual Studio/Visual C++ の独自機能。

Comments

[yaeyama]

回答ありがとうございます。
なるほど、Visual Studioの機能なのですね。

Answer 3

「ドキュメント コメント」と呼ばれるものです。

Visual C++ ドキュメント タグの区切り記号
ドキュメント コメントによって型やメンバの説明をコードに埋め込む方法

Comments

[yaeyama]

回答ありがとうございます。
ドキュメントコメントについては理解できました。

しかし、自分が目にした///を使ったコメント文ではXMLは使われておらず、
普通に関数の説明のような一行のコメントで使われていました。
この場合はどういった意味になるのでしょうか？

それとも、必ずしもXMLを使わなければならないということではないということでしょうか？
仮にそうだとすると、//や/**/との違いがわかりません。

Answer 4

/// はXMLドキュメントを生成するための書き方です。そのソースコードを元に作成できるようです。私は利用したことはないですが。

Answer 5

言語の文法上に違いはありません。

エディタや開発環境の機能によって画面表示が変わるだけです。１つの空白と10個の連続した空白の違いみたいなものです。（文法上に違いはないが、画面表示は変わる）

開発環境によっては補完機能やドキュメント生成ツールを持っているので、こちらの関係で差分が出る可能性もあります。もちろん、コンパイル結果（得られる実行ファイル）が変わるものではありません。

Answer 6

既にVisualStudioに関して話が出ていますが、似たようなツールで昔からDoxygenというソフトウェアがあります。

例えば、lenyaさんのサンプルをお借りして、Doxygen風に書くと、

/// @brief 概要
/// @param[in] hoge 変数の意味
/// @return 戻り値の説明
public void test(int hoge) 

のようになります。
もしくは簡単に、

/// 概要
public void test(int hoge)

なんて書き方もあります。
また、doxygenはある程度書き方があって、「@brief」が「\brief」だったり、「///」が「//!」だったりします。

こんな感じでコメントを書いておけば、doxygenでこんな感じのドキュメントを生成する事ができます。

doxygenはオープンソースで、マルチプラットフォームで動作するので、オープンソースプロジェクトや、VisualStudioを使わない開発環境でのプロジェクトでは、よく見るコメントの書き方ですね。

Comments

[yaeyama]

回答ありがとうございます。
/// @brief 概要
/// @param[in] hoge 変数の意味
/// @return 戻り値の説明
public void test(int hoge)
この書き方も同じプロジェクト内に見られたのでおそらくdoxygenの書き方で間違いないと思います。
doxygen初めて聞きましたけど便利そうですね。