ぱぱんだ日記

2002/08/28 :ALL: :WINDOWS: :LINUX: doxygenでドキュメント生成 Prev

_ 特にBSD系のコミュニティでは「ハッカーはドキュメントかかない」などと申しますが、そういうセリフは超絶スーパーマソが言えることであって、わしのようなヘタレ3歳プログラマはドキュメント書かなきゃワヤクチャになる訳でありまつ。

_ で、愚痴たれてたら、掲示版でとおりすがりさんと、にもりさんに doxygen がお薦めということを聞きました。で、インストールしてみました。件のページにはWindows用バイナリもありますが、とりあえずソースtar玉で。コンパイルはつつがなく。

_ 後、グラフ類(ヘッダの呼び出し関係とかクラス依存関係とか)をグラフィックで書くために graphviz も同時にインストール。こっちは、私の使っているDist.がVineLinuxなので Tcl/Tk周辺が8.0jp止まりでコンパイルできなかったので、 tar玉でtcl8.3.4.tar.Z,tk8.3.4.tar.Zを入れました。標準で/usr/localにまとまるのでRPMと重ならなくていい感じです。

_ で。doxygenとはどういうソフトかというと、小人さんがワラワラと現われてドキュメントを書いてくれる魔法のツール.....ではなく(^^;、宣言等の先頭にコメントを書いておくと、それを抜きだしてHTMLやLaTeXのソースにまとめてくれるものです。Javaを良く知っている人ならJavaDocと言えば通りが良いかと。実際、コメントの形式はJavaDocタグで書けます。これ便利。

_ doxygenは汎用なので、普通のC, C++ソースにも適用できます。使い方は、 Doxygenを使おうというページがマニュアル付きで良くまとまっています。素晴らしげ。

_ 使い方自体はさほど難しくない。ドキュメント作りたいディレクトリで、doxygen -gでDoxyfileという設定ファイルを作り、これをviとかで編集して、ディレクトリ設定等のパラメータ(非常に多い)を編集してやって、もう一度doxygenを実行すれば終り。私の場合は、

PROJECT_NAME           = 自分のライブラリ名
PROJECT_NUMBER         = 0.1
OUTPUT_LANGUAGE        = Japanese
EXTRACT_ALL            = YES (コメントなしのソースでもドキュメント化)
INPUT                  =  ../ (ソースのあるディレクトリ)
FILE_PATTERNS          =  *.c *.h (拾わせたいファイル)
RECURSIVE              = NO
HTML_HEADER            = header.html

_ くらいかな。編集したのは。あとheader.htmlをDoxyfileのあるディレクトリに用意したくらい。

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <head> <meta http-equiv="Content-Type" content="text/html;charset=euc-jp"> 
    <link href="doxygen.css" rel="stylesheet" type="text/css">
  </head>
  <body bgcolor="#ffffff">

_ 基本的に動作を知りたいだけということであれば、 EXTRACET_ALL=YES, RECURSVE=YESにして、INPUTディレクトリさえ指定すれば、だいたいどんんなCソースでもドキュメント化してくれるようです。

_ で、使ってみた感じ。

コレダ━━━━(゜∀゜)━━━━ッ！！

_ という感じの。ジャストナイスバッチグー(←絶死語)。ヘッダとかはこんな感じで呼び出し図にしてくれますヨ。その他、関数の解説等は、JavaDocと似た振舞いをするようです。要するに

int hoge(int v);

_ というプロトタイプ宣言があったら、ここにJavaDocタグでコメントを、

/**
 * vをナニする関数。
 * @return ナニしちゃった結果。
 * @param v ヘヘヘ。
 */
int hoge(int v);

_ と書いておけば勝手に整形されます。JavaDocと比較して優れている(と思われる)点は、ソースコード自体のビューもあるということかな。Javaの思想から言うとインタフェースだけ既知であれば使えなければおかしいわけですが、Cの場合はそう綺麗事だけでは済まないかもしれないので、まあ現状に則しているのではないかと (うちの社内でも、寿命がえらい長い割に、あまりメンテされてないソースがある訳でして)。

_ 一方で劣っている(と思われる点)は、JavaDocのようにオブジェクトシンボルの情報を利用している訳ではない(文字列の自力パースのみ)ので、時々間違えること。

typedef hogeatom *Hoge;
(中略)

/**
 * Hogeインスタンスを生成する。
 */
Hoge CreateHoge();

_ という、どう見ても間違えそうにない関数プロトタイプ宣言が、 Doxygenでは変数解説の欄にペーストされてしまい 少し困っています(^^;。しかも、なる時とならない時があって法則性がわからん～。

_ 後、同様の問題でプリプロセッサを利用していない関係上、1ファイル上で定義がダブッている場合、

#ifdef OS_UNIX

/**
 * Hoge生成(UNIX)。
 */ 
#define CREATE_HOGE(a) ....

#else
 /**
 * Hoge生成(WIN32)。
 */ 
#define CREATE_HOGE(a) ....

#endif

となっていると、常に後ろの方を参照してしまうようです。まあこれはしょうがないかな。Doxyfileには沢山死ぬ程オプションがあるし、知らないタグがあるだけかもしれないので、ちょぼちょぼ調べてみます。

_ いや、しかし。1からMS-Wordとかで書くのに比べたらメチャクチャ便利だわ。紹介してくださった方ありがとうございます。作っている方はもっとありがとうございます。