じゅぴの記録帳

いったイベントや勉強したこと等を記録するブログです 間違ってるとこあれば指摘お願いします

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

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

環境

VisualStudio2017

VisualStudio2019

VSCode

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

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

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

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

前置簡易コメント

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

/// コメント

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

//! コメント

//!@brief   説明

後置コメント

int a;///<コメント

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

int a//!<コメント

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

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

各ファイルのコメント

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

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

変数、マクロのコメント

int hp;//!@brief コメント

//!@brief     コメント
//!@details   コメント
int mp;

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

関数のコメント

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

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

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

便利なコメント

@todo 書くとTODOリストが自動で作成されめっちゃ便利!
@see 参照したい関数、変数を書ける
@note メモを書ける
@n 文の途中で改行してくれます。
@retval @returnの代わりに使用 戻り値ごとの細かい説明を書ける。

参考にしたサイト

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

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

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