c,c++のコメントメモ(doxygenを使用)
この記事ははてなをメインにQrunch(閉鎖済み)、Crieitにクロス投稿しています
環境
VisualStudio2017
VisualStudio2019
Doxygenで生成したドキュメントのどこで表示されるかわからない
変数等の@briefは詳解の前の簡単な説明と詳解の後のところに表示。
@detailsは詳解のところに表示される。
コメントの書く場所をどうすべきか
VisualStudioではcppに書いたときInteliSenseが機能しなかったので
ヘッダーに書くのが良さそうです。
ただテンプレート関数をクラス内で多用するとコメントと合わせかなり行数が増えるので注意が必要です。
どうにかしたい・・・
前置簡易コメント
/// コメント /// @detailsと同じ扱いに int i; /// コメント
このコメントはvisualstudioで使うとxmlコメントの書き方に被るみたいで
InteliSense(変数や関数を選んだときに表示されるやつ)に表示されません。
なので以下を使用しました。
//! コメント //!@brief 説明
後置コメント
int a;///<コメント
これもvisualstudioでは「XMLコメントに無効なXMLが含まれます」と表示されるので
int a//!<コメント
を使用しました。
あと、Visual studioのc++用の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
関数やクラスの前、ファイルの先頭で/**と改行だけで必要な内容を生成できるのでとてもおすすめです。