この記事は、2021/11/29に記載

doxygenとは

コードの中に、クラスや関数、変数などにとある規則に従って説明をつけることで、HTMLやWordなどにシステムの設計書を”ペッ”て吐き出す便利なツール

ダウンロードとインストール

doxygen←リンク
Window 版なので、サイト中央の「ソースディストリビューション」からダウンロード

インストールの手順は下記のサイトを参考に行うと良いかと、、、

doxygenの設定

基本は下記のサイトを参考に設定した。
ここでは、最低限必要な個所を赤く囲っている

エディタの環境による。

除外したいフォルダ名を記載する。ビルドでDebugやReleaseフォルダが作られてしまう為、除外リストに追加した。

「Run doxygen」をクリックするとプロジェクトディレクトリに下図のようなファイルなどが生成される。
「Doxyfile」は設定ファイルであり、こちらを共有すれば他の人も同じ設定でドキュメント出力できる。
また、「rtf」フォルダの『refman.rtf』はWordでも開ける形式になっている。

コメントの定義、種類

コメントの書き方は、先程の設定方法を参考にさせていただいた記事にもコメントの記載方法が記されていたが、ドキュメントコメントでもdoxygenは対応している為、一部だけ参考にさせていただいた。

ドキュメントコメントは以下のサイトを参考にしている。

ファイル名へのコメント

@fileと@briefだけでもドキュメントに反映されます．

/**
* @file ファイル名.h
* @brief 簡単な説明
* @author 作成者
* @date 作成日
* @details 詳細な説明
*/

関数へのコメント

<remarks>はなくてもドキュメントに反映されます．

/// <summary> 関数の簡単な説明</summary>
/// <param name="a">引数aの説明</param>
/// <param name="b">引数bの説明</param>
/// <returns>　戻り値の説明 </returns>
/// <remarks>詳細な説明</remarks> 
bool function(int a, int b) {
    b = a + 3;
    return true;
}

クラス、プロパティ、変数のコメント

基本<summary>でくくり説明を書けば伝わる

最後に

ドキュメントコメントはコード内でも、関数や変数の説明が記載されている為、ドキュメントの書き起こしとコード説明の一石二鳥になる為、
積極的にドキュメントコメントを使う方がいいと思う。

doxygen 備忘録