doxygenの使い方 - ksworks.org

うちでは doxygen を導入して、そこそこに満足してます（成果はあがったのかよっ（ｗ

ということで、簡単に、うちでの使い方を紹介してみようかなと。

インストール

Windows環境の方は、バイナリの setup.exe を拾って来れば簡単にインストール可能です

僕は、Linux でやっているんで、アーカイブファイルを拾ってきて、make かけます。

2002/07/01 現在の最新バージョン

www.doxygen.org→ メニューのSource → The source distribution で最新のソースを落とします。

1.2.16(2002/5/20)
ftp://ftp.stack.nl/pub/users/dimitri/doxygen-1.2.16.src.tar.gz

ダウンロードして展開したら、その後はとりあえず簡単にやれば万事OK。

$ tar zxvf doxygen-1.2.16.src.tar.gz
$ cd doxygen-1.2.16/
$ ./configure
$ make
$ sudo make install

doxygen は Graphviz というツール（に含まれる dot というコマンド）を使うとパワーアップするので、併せて入れます。

http://www.research.att.com/sw/tools/graphviz/ → download でダウンロード。

1.8.5(????)
http://www.graphviz.org/pub/graphviz/ARCHIVE/graphviz-1.8.5.tar.gz

僕は好みで、tarball を落としてきて、コンパイルかけてますが・・・

RPMがいい、という方はそれでも構わないと思います＾＾；


$ tar zxvf graphviz-1.8.5.tar.gz
$ cd graphviz-1.8.5/
$ ./configure
$ make
$ sudo make install

これで、準備完了です。

以下、doxygen や dot は既にパスの通っているところにある物として説明します。

＃Win環境の方などは、適時設定をしてください。

設定

まずは、doxygen の設定ファイルを作ります。

doxygen は、実行時に、プロジェクト毎に作成する設定ファイルを読み込むのですが、ぶっちゃけた話、プロジェクトが変わる毎に毎回毎回作成するのは面倒なので（ぉ

僕は適当に設定を弄ったファイルを元ファイルとして利用してますｗ

ドキュメント書きを楽したいのに、変なところで悩むのもいやですしね＾＾；

$ doxygen -g Doxyfile.org
$ grep -v \# Doxyfile.org | awk 'NF > 0' > Doxyfile

doxygen が作成してくれる Doxyfile は、コメントが多くて見辛いので、思い切って削除しますｗ

以後、Doxyfile.org に書いてある説明（や、Webで説明サイトを検索したり）を見ながら設定を変更していきます。

（当然、こうまでばっさり行くと、後で訳がわからなくなるのでセクション名程度の説明は追加します）

とりあえず、大まかに設定を行います。

重要そうなのは・・・

PROJECT_NAME: プロジェクト名
OUTPUT_LANGUAGE: 日本人なので、’Japanese’ を選択します:p
GENERATE_HTML: とりあえず、HTMLファイルを生成してほしいのでYES(Default)
GENERATE_LATEX: 興味ないからNOに変更
HAVE_DOT: せっかくインストールしたので、YES に変更
DOT_PATH: PATHの通っているところにあるんですけど、一応設定

細かい設定内容ははしょります（ぉ

このページの一番下の、「ネタ元」辺りでも見て、勉強してください＾＾；

一応、参考に・・・・僕の使ってる Doxyfile (2002/07/01)

僕は、このファイルの ‘PROJECTNAME’, ‘PROJECTNUMBER’ だけ変えて使い回してます。

コメントのdoxygen化

とりあえず、ここでは家のコメントの付け方を紹介します。

これを見て、自分のやりたいようにコメント付けをするのが良いと思います。

ファイルコメント

/******************************************************************************/
/*! @file
    @brief  ファイルの説明

        briefだけで足りない場合はここにも説明

    @author ksworks
    @date   日付

    $ Id : $
 ******************************************************************************/

必要最低限の情報以外はいらないと思ってます。

＃逆に言えば、これくらいは最低限度必要かなと。

クラスコメント

/*----------------------------------------------------------------------------*/
/*    クラス名                                                                */
/*----------------------------------------------------------------------------*/
/*! @brief  てきとーなクラス

    何の為に使うかとか、何が必要かとかそういう詳しい情報を書く。

    @todo   てきとーすぎる。
    @bug    あらゆる面でバグい。

 */
class
hoge
{
private:
    //! メンバの説明
    int     foo;
protected:
    //! ここも説明
    int     bar;
public:
    //! クラスコンストラクタ
    hoge  ();
    //! クラスデストラクタ
    ~hoge ();

    //! 何かを取得する
    bool get ( int nget );
};

クラス名まで doxygen で拾う必要は無いけど、あった方が何となく格好よく見えるのでｗ

メンバ変数の説明は、必要があれば簡易・詳細両方書きます。

メンバ関数の説明は、詳細は関数前に書きます。

関数コメント

/*----------------------------------------------------------------------------*/
/*    hoge::get                                                               */
/*----------------------------------------------------------------------------*/
/*! ほげほげな入力を取得します。

    @param nget     入力する数の指定とか？

    @retval true    入力ができた
    @retval false   入力ができなかった
 */
bool
hoge::get ( int nget )
{
    ...;
}

関数の詳細と引数・返値（boolは上の様に分けますが、enum 等の場合は単に @return にしたりします。

ネームスペース

/*! @namespace hoge
        @brief  ほげな名前空間

    ほげほげうにゅうにゅ
 */

ネームスペースは、関連ファイルに分割されることが多い（少なくとも僕の場合）ので、関連ファイルが共通に見るファイルで上の様に定義します。

実際に使っている部分でもコメントは書きますが、doxygen で拾わないようにしてます。

因みに、自分自身の名誉の為に書きますが、本物のソースはちゃんとコメント書いてますｗ