c,c++のコメントメモ（doxygenを使用)

この記事ははてなをメインにQrunch(閉鎖済み)、Crieitにクロス投稿しています

環境

VisualStudio2017

VisualStudio2019

VSCode

Doxygenで生成したドキュメントのどこで表示されるかわからない

変数等の@briefは詳解の前の簡単な説明と詳解の後のところに表示。
@detailsは詳解のところに表示される。

コメントの書く場所をどうすべきか

VisualStudioではcppに書いたときInteliSenseが機能しなかったので
ヘッダーに書くのが良さそうです。
ただテンプレート関数をクラス内で多用するとコメントと合わせかなり行数が増えるので注意が必要です。
どうにかしたい・・・

前置簡易コメント

///　コメント
///　@detailsと同じ扱いに
int i;

///　コメント

このコメントはvisualstudioで使うとxmlコメントの書き方に被るみたいで
InteliSense（変数や関数を選んだときに表示されるやつ）に表示されません。
なので以下を使用しました。

//!　コメント

//[email protected]   説明

後置コメント

int a;///<コメント

これもvisualstudioでは「XMLコメントに無効なXMLが含まれます」と表示されるので

int a//!<コメント

を使用しました。
あと、Visual studioのc++用のxmlコメントは拡張機能で使用可能みたいです。

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

各ファイルのコメント

一番始めにいります。
最低限この２行あれば十分っぽいです。

/*!
@file    何も書かなくてもいい
@brief   このファイルの説明を書く ファイル一覧のところに出力されます
*/

変数、マクロのコメント

int hp;//[email protected] コメント

//[email protected] 　　　 コメント
//!＠details 　　コメント
int mp;

基本後置コメントがスマートでいいのですが複数行に対応してないみたいなので
複数行に書く場合は前置のほうがいいです。

関数のコメント

/*!
@brief 関数の要約
@param 引数名　引数の詳細引数の個数分かく
@return 戻り値の詳細
@details 関数の細かい説明
*/

クラス、列挙体へのコメント

/*!
@brief 要約　クラスなら一覧にも書かれます
@details 細かい説明
*/

便利なコメント

参考にしたサイト

Doxygen コマンド一覧
C++で///を使ったコメント - teratail

VSCodeの拡張機能(2020-11-25追記)

VSCodeにはDoxygen形式のコメントを自動生成してくれるとても便利な拡張機能があります
Doxygen Documentation Generator
関数やクラスの前、ファイルの先頭で/**と改行だけで必要な内容を生成できるのでとてもおすすめです。