新トップページへ | Tip

ソースコードからドキュメントをDoxygenで生成する

LastUpdate : 13/01/02

JavaDoc的なことをC++でもやろう、という話です。
正直、JavaDocで生成したHTMLを見て役に立ったことがあまり有りませんが、コメントを書く際の統一的な書式としては役に立つと思います。

もくじ

はじめに
Doxygenのインストール
コメントの書式
ドキュメントを生成する

はじめに

詳細はこちら(http://www.doxygen.jp/)を参照。
日本語サイトがあるので、非常に便利です(すごい!)。また、非常に多機能。

実際、使えるようなドキュメントにするかしないかはコメントを書く人次第だが・・・。
このページでは、コメントの基本的な書き方をサンプルとしてあげる程度に留める。

また、Doxygenは、コメントの書式がいくつかのタイプから選べるが(その中にJavaDocみたいにする選択肢がある)、JavaDocライクに使えることを目指す。

バージョンは1.8.3を使用します(13/01/02時点で最新版)。


Doxygenのインストール

ここ(http://www.stack.nl/~dimitri/doxygen/download.html)から、ダウンロードを行う。
ソースからビルドする手順もあるみたいだが、面倒。windowsの場合はバイナリを使うのが早いかと。

インストールウィザードが始まるので、それに従いインストール。
インストール後、インストールディレクトリのbin\doxywizard.exeを起動する。GUIで操作可能です。


コメントの書式

サンプルを以下に示します。
JavaDoc形式でコメントを記述しました。コメントの中にHTMLを記述することが可能です。

main.cpp
/**
 * @file main.cpp
 * @brief main関数を定義しています。<br>
 *        にゃんにゃん。
 *
 *        プログラムのエントリポイントを定義しています。<br>
 *        前後に空白行をいれて、詳細を記述します。
 * @par   これで1つのパラグラフを定義できます、
 *        詳細をわーーーーーーーーーーーーーーーーーーーーーー<br>
 *        っとここに記述します。
 * @par   複数定義できます。
 *        うひぃwwwwwwwwwwwwwwwwwwww<br>
 *        わんわんお♪
 * @date  2013/01/02 新規作成!
 * @date  同日 作成完了(dateだからといって日付を書く必要はない。)
 * @author 作者の名前を書きます
 */
#include "Doc.h"

/**
 * メイン処理.
 * @param argc 引数の数
 * @param argv 引数の値の配列
 * @return リターンコード
 */
int main(int argc, char** argv) {

        // 処理を実行する
        myNamespace::Doc obj(10);
        obj.doWork();

}


Doc.h
/**
 * @file Doc.h
 * @brief ここに要約文を記述します。<br>
 *        むにゃむにゃむにゃむにゃむにゃむにゃ。
 * @author 作者の名前を書きます
 * @date 年が明けた日<br>
 *       作成着手
 * @date 次の日<br>
 *       完成したYO!
 */

namespace myNamespace {
        /**
         * クラス説明の要約をここに書く。<br>
         * むにゃむにゃむにゃ.
         */
        class Doc {
        public:
                /** デフォルトコンストラクタ. */
                Doc() {}
                /**
                 * コンストラクタ.
                 * @param num 回数を指定する(引数の説明)
                 */
                Doc(int num) { 
                        this->num = num;
                }
                /**
                 * コピーコンストラクタ.
                 * @param doc コピー元オブジェクト
                 */
                Doc(Doc& doc) {
                        setNum(doc.getNum());
                }
                /** ディストラクタ. */
                virtual ~Doc() {}

                /** ANIMALの説明だよん */
                enum ANIMAL {
                        /** 猫. */
                        CAT,
                        /** 犬. */
                        DOG,
                        /** 鳥. */
                        BIRD
                };

                /**
                 * メンバ関数のコメント.
                 * @return ループ処理を行った回数(戻り値の説明)
                 */
                int doWork();

                /** @return 内部で保持している番号 **/
                int getNum() const { return num; }
                /** @param num 番号 */
                void setNum(int num) { this->num = num; }
        private:
                /** 内部で保持している番号(メンバ変数へのコメント) */
                int num;
        };
}


Doc.cpp
/**
 * @file Doc.cpp
 * @brief Docクラスの実装
 * @author 作者の名前を書きます
 */

#include <iostream>
#include "Doc.h"

namespace myNamespace {
        /*
         * 仕事をします!.
         * @return 戻り値だお!
         */
        int Doc::doWork() {
                // 猫の鳴き声を出力
                int i;
                for (i=0; i<getNum(); i++) {
                        std::cout << "にゃん\n";
                }

                return i+1;
        }
}

若干JavaDocと異なるところがありますが(ファイルヘッダの部分とか)、おおかたJavaDoc感覚で記述できます。
注意したいのが、クラスのメンバ関数の宣言と定義が分かれている場合です(inlineにしたい以外は分かれると思いますが。。。)。両方に/**で始まるコメントをつけてしまうと、同じものが2個出力されてしまう様子です。そのため、Doc.cppでは/**ではなく、/*でコメントを始めています(/*の場合はドキュメントに出力されない)

以下に、出力されたドキュメントのキャプチャを載せておきます。生成時のオプションの設定で若干出力される項目に違いがあります。

まず、ファイルの一覧。概要部分だけが出力されます。

Doc.cppのドキュメント。Doc.cppにはメンバ関数の定義しかかいてない。すると、ドキュメントは以下のものしか出ないみたい。

Doc.hのドキュメント

main.cppのドキュメント

クラス一覧。ネームスペース毎に表示されるらしい。


ドキュメントを生成する

インストールディレクトリの「bin」ディレクトリの中にある「doxywizard.exe」を起動します。
操作手順のキャプチャをぺたぺた張っていきます。

※ 操作手順の中で文字コードの設定をしているが、これは元のソースの文字コードがCP932だから、設定をすべてCP932にしています。