【C/C++】ドキュメント作成(doxygen)まとめ

C/C++のドキュメント作成でdoxygenを使ってみたまとめです。

１．doxygenとは

Doxygen は、C++、C、Java、Objective-C、Python、IDL (Corba、Microsoft 風) 向けのドキュメンテーションシステムです。 PHP、C#、Dにもある程度対応しています。
http://www.doxygen.jp/

と、公式サイトで説明されている通り、ドキュメント生成を行うためのシステムです。
※ライセンスはGPLで、無料で使うことができます。
※OSはLinux, Windows, Macで使うことができます。

下図はドキュメント生成のざっくりとした流れです。

まずは、doxygenスタイルのコメントの記述方法からまとめていきたいと思います。

２．doxygenスタイルのコメント記述方法(とサンプルコード)

2-1 基本

doxygenはすべてのコメントをドキュメント化するのではなく、特定の形式で記述されたコメントのみをドキュメント化します。
※全部ドキュメント化されると逆に困りますよね…

doxygen形式のコメントの基本形がこれです。

/** doxygenスタイルのコメント　その１ */
/*! doxygenスタイルのコメント　その２ */
//! doxygenスタイルのコメント　その３

これらの形式で記述されたコメントのみがドキュメント化の対象となります。

注意点は、コメント開始の/**やコメント終了の*/と、コメント文との間は半角スペースが必須なところです。

また、複数行のコメントの場合は、以下のように記述します。

/**
* コメント一行目
* コメント二行目
*/

※その２、その３も複数行で書けますがここでは省略します。

複数行の場合も、コメントの本文と*との間には半角スペースが必須です。

このページでは、/** 〜 */を以降使用していきます。

doxygenコメントにはもう一つ覚えることがあります。
それが、@detailのような特殊コマンドです。

これは、doxygenがドキュメントを生成する際のヒントを与えるようなもので、例えば、以下のように@detailと記載した場合、
* @detail 詳細説明
ここに書かれたコメントは出力するドキュメントの詳細説明の欄に出力されます。

細かい意味は以降の章で触れますので、ここでは、コマンドの前後は半角スペースが必須である点だけ抑えておいてください。

2-2 ファイルのコメント

この章から、具体的なdoxygenスタイルコメントの説明をしていきます。

まずは、ファイルに対するコメントです。

ファイルに対するコメントがないと、グローバルな空間(名前空間の外)に定義した関数や変数の出力がなされなくなってしまいます。

ドキュメント化対象のファイルには必ずファイルコメントをつけましょう。

以下はサンプルになります。

/**
* @file doxygen_sample.cxx
* @brief ファイルの説明
* @author 作成者名
* @date 作成日
*
* @details 詳細説明
* @note 補足説明とかメモ
*/

@fileでファイル名、@briefでファイルの概要、@authorで作者名、@dateで作成日を記述できます。

@author, @dateは省略可能です。
(構成管理しているなら不要なはず。~~コミット毎にこれを更新するのはクソダサい。~~)

@detailは関数の詳細説明です。省略可能です。
@noteは補足説明やメモです。省略可能です。

@detail, @noteは、ファイル以外でも、関数や変数など、どのコメントでも使用可能です。
以降の章での説明は省略していますが、使用可能なので必要に応じて使ってください。

2-3 関数のコメント

続いて関数のコメントです。

特に注意点等はないので早速サンプルです。

/**
* 関数の概要説明
*
* @param[in] paramA 第一引数の説明
* @param[out] paramB 第一引数の説明
* @return int 戻り値の説明
*/
int funcA(const int paramA, int *paramB) {
…
}

@paramは引数の説明です。
@param[種別(in/out)] 引数名コメント文 の形式で指定します。
[in]は入力の引数、[out]は出力の引数(変更した値を呼び出し元でも使用する引数)です。
引数が存在する場合のみ記載します。

@returnは戻り値の説明です。
@return 戻り値の型コメント文 の形式で指定します。
戻り値が存在する場合のみ記載します(voidの場合は記載しません)。

2-4 変数・定数・構造体・enum

変数・定数のdoxygenコメントの書き方は共通です。

/** 変数の説明 */
int a = 0;

/** 定数の説明 */
constexpr int const_a = 0;

宣言箇所の真上に/** 〜*/形式でコメントを書けば自動的に変数・定数に対するdoxygenコメントとして扱われます。

続いて、構造体・enumのコメントです。
この二つの書き方も共通です。

/** 構造体の説明 */
struct structA {
int memberA; /**< memberAの説明 */
int memberB; /**< memberBの説明 */
};

/** enumの説明 */
enum enumA {
memberA = 10, /**< memberAの説明 */
memberB = 20, /**< memberBの説明 */
};

変数・定数と同様に、宣言箇所の真上に/** 〜*/形式でコメントを書けば自動的に構造体・enumに対するdoxygenコメントとして扱われます。

各メンバ・要素に対するコメントは省略しても問題ありません。
(出力されないだけです)

2-5 クラスのコメント

次は、クラスのコメントの書き方です。

まずはクラスそのものに対するコメントのサンプルです。

/** クラスの概要説明 */
class ClassA {
public:
…
private:
…
};

クラスに対するコメントも、クラスの宣言の真上に記載すると、自動的にクラスのコメントとして扱われます。

次に、コンストラクタ・デストラクタに対するコメントです。

/**
* コンストラクタの概要説明
*
* @param[in] str 引数の説明
*/
ClassA(const std::string &str) : str_(str) {};

コンストラクタ・デストラクタに対するコメントは関数に対するコメントに近いです。
コンストラクタ・デストラクタの真上に記載することで自動的にコンストラクタ・デストラクタとして扱われます。

次に、メンバ関数・メンバ変数です。

public:
/**
* メソッドの概要説明
*
* @return std::string 戻り値の説明
*/
std::string GetStr();

private:
/** メンバ変数の概要説明 */
std::string str_;

メンバ関数は通常の関数と、メンバ変数は通常の変数と同じ記述方法で書くことができます。

public, privateと言ったスコープは自動的に判定されるのでdoxygenコメント記載時は気にする必要はないです。
(デフォルトではpublicメンバのみドキュメントに出力されます)

2-6 名前空間のコメント

namespaceの上にdoxygenスタイルのコメントを記載すると自動的に名前空間のドキュメントとして扱われます。

/** NameSpaceAの概要説明 */
namespace NameSpaceA {
}

ファイルのコメントと異なり、名前空間のコメントは記載しなくても特に問題は起こりません。

３．doxygenインストール

3-1 ダウンロード

公式ページからバイナリをダウンロードします。
http://www.doxygen.nl/download.html

少し分かりにくいのですが、↑のサイトの中盤にSources and Binariesという項目があり、その項にダウンロード用のソースとバイナリが用意されています。

Mac(dmg形式)、Windows(exe形式)、Linux(バイナリのtarball)が用意されていたので、通常はコンパイル等は不要なはずです。

今回はmac(Catalina 10.15.4)で試したのでmacOS向けのバイナリをダウンロードしました。
(Doxygen-1.8.17.dmg)

3-2 インストール

ダウンロードしたdmgファイルを開くと以下のような画面になります。

Doxygen.appをアプリケーションにドラッグして追加します。

そして、追加したアプリケーションを開こうとすると、以下のエラーが表示されて開けないかと思います。

"Doxygen.app"は、開発元を検証できないため開けません。

その場合は、アイコンを右クリックし、[開く]を選択します。
すると、以下の画面が表示されるので、もう一度[開く]を選択します。

Doxygen.appを右クリックで開いた際に表示される画面 — もちろん自己責任ですが

これで、以下のようなdoxygenのGUIのトップ画面が開くはずです。

doxygenのインストールはこれで完了です。

次回以降は普通にクリックして開くことができます。

４．ドキュメント出力方法(HTML形式)

次は実際にドキュメントを出力していきます。

説明は、doxygenのウィザードに沿って進めていきます。

4-1 プロジェクト設定

doxygenを立ち上げると以下の画面になると思うので、まずは、プロジェクトの設定を行います。

★の項目は必須項目なので全て入力してください。

「★doxygenの作業ディレクトリ」にはソースコードのルートディレクトリを指定します。
大抵の場合は「★生成対象のコードのディレクトリ」と同じになるかと思います。

「★ドキュメント出力先ディレクトリ」に設定するパスは権限さえあればどこでも良いです。
指定したディレクトリの下に”html”や”tex”のディレクトリが作成されます。

必要箇所を入力したら[next]をクリックします。

4-2 モードの設定

次にモードの設定を行います。

基本的にはデフォルトでOKかと思いますが、一応触れておきます。

“All Entities“を選択すると、ドキュメントを作成していないファイル・関数等についても自動的にドキュメントが出力されます。
(一覧に表示されるレベルですが)

“Include cross-referenced source code in the output“を有効化すると、参照されているコードのリンクが貼られるようになります。
(例えば、hoge.hxxで宣言してhoge.cxxで定義した関数など)

その下の”Select programming〜“は言語の選択です。
今回はC++なのでデフォルトのままでOKです。

そして、[next]をクリック。

4-3 出力の設定(HTML)

次は出力の設定を行います。
※ここの設定は見た目だけ問題ですので、趣味の範囲でどうぞ。

今回はHTML形式のドキュメントを出力したいのでHTMLにチェックを入れます。

HTMLの出力形式がいくつかありますが、ドキュメントの左側に目次が表示される”with navigation panel“が個人的には見易かったです。

また、Change color…でドキュメントの色を変更できます。

ドキュメントの出力形式を決めたら[next]を選択します。

4-4 ダイアグラム(クラス図)の出力設定

最後にダイアグラムの設定を行います。

No diagrams
Use built-in class diagram generator
Use dot tool from the GraphViz package

の三択です。

No diagramsはグラフを出力しません。

Use built-in class diagram generatorはplant-umlの図を出力してるっぽいです。
関連するクラスが２つ以上ないと図は出力されません。

Use dot tool from the GraphViz packageは公式マニュアルでは“if you use the binary packages for MacOSX this tool is already included”となっていたのですが、私の環境では動作しませんでした。

グラフを出力するかどうかが決まれば、[next]をクリックします。

4-5 HTML出力実行

下図の[Run doxygen]をクリックするとドキュメント出力が実行されます。

出力されたHTMLは以下の感じになります。

トップページ

クラス図

HTML出力は以上になります。

５．その他

個人的なメモなど。

5-1 コメントをヘッダに記載するか否か

C++の場合、宣言箇所と定義箇所が分かれて、どちらにdoxygen形式のコメントを記載するべきか迷うかもしれません。

doxygenの動作としては、両方に記載した場合は、両方の内容が出力されてしまいます。
特別な理由がない場合はどちらかに記載するべきです。

doxygenの動作上、どちらに書いても動作するので、悩みどころではありますが、個人的には.cxxではなく.hxxのファイルに書くべきだと思います。

基本的にドキュメントを後から見るのはコードを知らない人間(もしくは未来の自分)になると思います。

コードを知らない時はヘッダファイルから読んでいくことが多いと思うんですよね。

なので、後からの見やすさとして、ヘッダーに書いておくべきではないかと思います。