ホーム  |  更新  |  惑々  |  C++  |  doxygen  |  技術  |  Libs  |  リンク

Doxygen を使おう

2002-10-13 「ちょっとしたヒント」を修正

はじめに
サンプル
ダウンロード
インストール
前準備
実行
ちょっとしたヒント
日本語の扱い
日本語マニュアル
謝辞

はじめに

プログラマには、ドキュメント、とくにプログラムの内部仕様書を書くのが苦手、 という人が多い。 その理由は明らかであって、そもそも、ソースコードに (バグも含めて)*1 すべての仕様が子細もらさず書かれているのに、なぜ、さらにそれと独立した仕様書が必要なのかと、 (半ば本気で) 思ってしまうからである。 ソースコードと独立にメンテナンスをしなければならないような仕様書は、 いずれソースコードと整合性が取れなくなって、無意味ならまだしも、 かえって害をなす存在となり果てることもある、ということを、 彼らは経験的に理解しているのである。

(*1)
Ruby の作者である、まつもとゆきひろ氏は、 その著者『オブジェクト指向スクリプト言語 Ruby』の中の「付録C Ruby 用語集」で、 次のように書いている:
ドキュメント
まつもとの苦手なもの。彼は普段から「ソースがドキュメントだ。 バグも完全に記述されている」と主張しているが、誰も受け入れない。 当り前だ。

プログラマがみな、ドキュメントを書くのを嫌っているか、というと、 そんなことはない。フリーで出まわっているソフトなどには、商用ソフトでも お目にかかれないほど、非常に丁寧で分かりやすく書かれている使用説明書が 添付されていたりする。それらは、無駄がなく、シンプルでありながら、 必要なことはきちんと説明してある。そう、プログラマは、無駄なことが嫌い なのだ。ソースコードと独立に仕様書をメンテナンスするなどということは、 それこそ無駄の極致と言えよう。

というわけで、「無駄の嫌いな」プログラマにお勧めしたいのが、 本稿の主題である doxygen を始めとする、 自動ドキュメント化ツールである。 doxygen 以外にも、KDOC や DOC++ といったツールが存在する (ようだ)。 私は、KDOC については使用経験がない。DOC++ は、『達人プログラマー』でも 紹介されていたツールである。一応、インストールして使ってみたものの、 結果がいまひとつだったのと、既にメンテナンスが終了している雰囲気も あって、使うのをやめてしまった。その後、いろいろ検索した結果、 たどり着いたのが、doxygen というわけである。

doxygen は、ソースコードに記述されたコメントから、 自動的にドキュメントを生成するツールである。コメントの全くないソースからも、 一応、それらしいモノを生成してはくれるが、それは、外見だけ整えたものであって、 内容は無きに等しい (それでも、クラス間の依存関係の解析には役に立つが)。 ソースコードから「プログラムの意図」を読み取って、 ドキュメントにしてくれるんではないか、などという甘い期待はいだかないように。


サンプル

doxygen が生成するドキュメントの感じを知っていただくために、ちょっとした サンプル を用意した。これは、C標準ライブラリの fxxxx シリーズの関数をラップするための 簡単なクラス群のドキュメントである。

生成のもとになったソースファイルは、次の2つ。

この2つのファイルに対して、doxygen を実行すると、この サンプル のような HTML で記述されたドキュメントが出来上がる、という寸法である。

ことに、後述する graphvis というツールを併用すると、以下のように、 クラスの派生関係やファイルの依存関係などをグラフ化してくれるので、 見た目にも気持ちがよい。


クラスの派生関係
ファイルのインクルード関係

ダウンロード

doxygen の公式サイトは、www.doxygen.org である。 ここから、リンクをたどってダウンロードページに飛ぶ。

ダウンロードできるブツの種類にはいくつかあるが、私は、ソースコードの tarball 「doxygen-1.2.17.src.tar.gz (2206K)」を選んだ。 リビジョンは、2002年9月18日現在のものである。

もう一つ、graphvis もダウンロードしておこう。こちらのサイトは、 www.research.att.com/sw/tools/graphviz/ である。リンクをたどってダウンロードページに飛ぶ。こちらも、様々な形態および プラットフォーム向けのパッケージが用意されているので、適切なものを選んでほしい。 私は、Source Code 「graphviz-1.8.9 source tarball」を選んだ。

以下の説明では、プラットフォームとして Linux box を使用しているが、 両ツールとも、Windows 用のバイナリも用意されているので、 Windows ユーザも安心して上記ページを訪れていただきたい。


インストール

まずは、doxygen をインストールする。手順はいたって簡単。

  1. 適当な場所で、tarball を展開する:
    % tar xzvf doxygen-1.2.17.src.tar.gz
  2. 作成されたディレクトリに移る:
    % cd doxygen-1.2.17
  3. configure を実行する:
    % ./configure --prefix /usr/local
    デフォルトでは /usr の下にインストールされるが、私はいつものように /usr/local の下にインストールしてほしかったので、 --prefix オプションを使ってインストール先を指定した。 (--preifx の後ろは、= ではなくスペースである点に注意)

    また、私は不要なので指定しなかったが、Qt-2.1.x をインストールしている人で GUI なフロントエンドを使いたい場合は、 --with-doxywizard オプションを指定するとよいらしい。

  4. make を使ってツール類をビルドする:
    % make
  5. 同様にドキュメント類をビルドする:
    % make docs
  6. su して、インストールを実行する:
    % su
    # make install
    # make install_docs

これで終わりである。何も難しいことはない。 (まあ、ソースからビルドすると、若干時間はかかるが)

次は、graphviz のインストール。これは、上にも書いたように、 クラスの継承関係やファイルのインクルード関係を図示するには必須のツールなので、 是非ともインストールしてほしい。私の場合、手順は次のとおり。

  1. 適当な場所で tarball を展開する:
    % tar xzvf graphviz-1.8.9.tar.gz
  2. 作成されたディレクトリに移る:
    % cd graphviz-1.8.9/
  3. configure を実行する:
    % ./configure
    デフォルトでは /usr/local の下にインストールされる。 それ以外のディレクトリの下にインストールしたい場合は --prefix=install-dir オプションを使ってインストール先を指定すること。 (--preifx の後ろは、スペースではなく = である点に注意)
  4. make を使ってビルドする:
    % make
  5. su して、インストールを実行する:
    % su
    # make install

以上である。


前準備

doxygen は、独自の設定ファイルを読み込み、その設定内容にしたがって、 ソースコードからドキュメントを生成する。

設定ファイルは、doxygen 自身が、そのテンプレートを作成してくれる。

  % doxygen -g [<設定ファイル名>]

たとえば、doxygen -g doxygen.conf を実行すると、 "doxygen.conf" という名前の設定ファイルが作成される。 <設定ファイル名> を省略すると、"Doxyfile" という名前の設定ファイルが作成される。

生成された設定ファイルには、設定項目が山ほど書かれているのだが、大半は、 デフォルトのまま使用しても大丈夫であろう。私が変更したのは、次のような項目である。

以下、項目名を示して説明する。

PROJECT_NAME プロジェクトの名前を設定する。サンプルでは、 File &nbsp; IO &nbsp; Wrapper にした。
PROJECT_NUMBER リビジョン番号などを設定する。サンプルでは、1.0 になっている。
OUTPUT_LANGUAGE 生成するドキュメントの記述言語を設定する。言語といってもプログラム言語のことではなく、 英語や日本語など、どの自然言語を使うか、という設定である。サンプルでは、 Japanese になっている。
EXTRACT_ALL コメントの付いていないようなエンティティも含めて、すべて、ドキュメント化するか 否かの設定。デフォルトは NO だが、 サンプルでは YES に設定した。
JAVADOC_AUTOBRIEF YES に設定すると、JavaDoc スタイルの簡易説明、すなわち、 コメントの一行目から最初のドット (.) までを簡易説明として扱うというスタイルが採用される。 デフォルトでは、明示的に @brief を記述する、Qt スタイルである。 サンプルでは YES に設定した。
WARN_FORMAT 警告を表示する場合のフォーマットを設定する。サンプルでは、 "$file:$line: $text" になっている。
INPUT 入力となるソースファイル(群)の名前、または、 それらが存在するディレクトリ(群)の名前を設定する。 サンプルでは、単に . (カレントディレクトリ) になっている。
FILE_PATTERNS 前項の INPUT にディレクトリの指定がある場合、 doxygen への入力として使用するファイルをフィルタリングするための ファイル名パターンを設定する。サンプルでは、*.cpp *.h になっている。
INPUT_FILTER ファイルを処理する前に通すフィルタープログラムを指定する。 Unix-like な環境で Shift_JIS なファイルを処理したい場合は、 ここに nkf などを指定すればよい。 (後述の「日本語の扱い」を参照)
GENERATE_LATEX ドキュメントの形式として、LaTeX 形式での出力をするか否かを設定する。 デフォルトは YES だが、サンプルでは NO になっている。 他にも、HTML (YES)、RTF (NO)、man ページ (NO) の各形式による出力を指定できる (カッコ内はデフォルトの設定)。
HAVE_DOT グラフ表示ツールキット graphviz に含まれる dot というツールを使うかどうかを設定する。YES にした場合は、 path の通った場所に、dot ツールが存在しなければならない。 デフォルト設定は NO。サンプルでは YES になっている。

変更後の設定ファイル: doxygen.conf

デフォルトからの変更点だけを集めた設定ファイル: Doxyfile


実行

実行の仕方は、非常に単純。次のように設定ファイル名を引数として doxygen を起動するだけである。設定ファイル名を省略すると、 "Doxyfile" という名前の設定ファイルが読み込まれる。

  % doxygen [<設定ファイル名>]

サンプルの設定ファイルでは、HTML形式のドキュメントが、html という名前のディレクトリの下に生成される。 この "html" というディレクトリ名は、設定ファイルの HTML_OUTPUT 項目で変更することもできる。

さあ、手持ちのブラウザで、 作成されたドキュメント をブラウジングしてみよう!


ちょっとしたヒント

はじめて doxygen を使った人がおそらくいだくであろう感想は、 「この真っ白なインデックスページは、何とかならないの?」 ということだろう。

上のサンプルドキュメントを見てもらえればわかるが、もちろん、何とかなる。 使うのは、lei_fileutil.h の頭のほうにある \mainpage というコマンドだ。 このコマンドに続くドキュメントブロックがインデックスページに表示される。

\mainpage コマンドを使うと、Doxyfile で指定した PROJECT_NAME および PROJECT_NUMBER がタイトルとして使われる (あるいは、\mainpage コマンドの後ろに明示的にタイトルを指定することもできる)。

また、ファイルを見てもらうと分かるが、クラス名や関数名を書くだけで、 そこから説明ページへのリンクが張られる。 名前空間を使っているときは、ちゃんと限定してやらないとならないのがちと面倒ではあるものの、 サンプルのようにクラスや関数の一覧を作るときには便利である。

あとの基本的な使い方は、サンプルファイルや後述する日本語マニュアルのはじめの 3つくらいを読んでもらえればだいたい理解できると思う。


日本語の扱い

doxygen を使ってみて最初に驚いたのは、ドキュメントの記述言語として、 日本語もサポートされていたことである*2

(*2)
これは、マニュアルの Acknowledgements に 載っている Kenji Nagamatsu 氏による貢献だと思われる。惜しむらくは、バージョン 1.2.5 以降、新しく追加されたドキュメント項目については、 まだ日本語化がなされていないようだ。

追記 (2002-09-18)
バージョン 1.2.17 現在、Ryunosuke Sato 氏が日本語関係のメンテナンスを やっているようである。新しいドキュメント項目も日本語になっている。 また、以下に述べるように、Windows版では Shift_JIS が使えるようになっている。

この日本語によるドキュメントは、ソース上は euc-jp でエンコードされている。 Unix-like なプラットフォームにおいてはそのまま euc-jp でドキュメントが出力されるが、 Windows プラットフォームにおいては euc-jp から Shift_JIS への変換がなされ、 生成されるドキュメントは Shift_JIS になる。

ただ、Unix-like プラットフォーム上で Shift_JIS を使って仕事をしている人も多いことだろう。 そのような人が doxygen を使ってうまく日本語ドキュメントを生成するためには、 次の 2通りの方法がある。

  1. 設定ファイルの INPUT_FILTER を使って、 ソースファイルをコード変換する
    コメントが Shift_JIS で書かれているようなファイルに対しては、 この方法が有効。
  2. ドキュメントの記述言語をデフォルトの英語にする
    英語といっても、項目名とかその程度なので、むしろ、 日本語よりもメリハリが利いて読みやすいかも。

まず a であるが、設定項目 INPUT_FILTER に、 nkf -e などを指定すればよい。 そうすると、doxygen は、ソースファイルの解析に先立ち、このフィルターを通して、 その標準出力された結果を入力として使用する。 フィルターとして nkf -e を指定した場合は、 Shift_JIS などで書かれたソースファイルが euc-jp に変換されることになる。

追記 (2002-09-20)
Doxyfile に
INPUT_FILTER = nkf -e
と書いて、実際に試してみたところ、
sh: nkf-e: command not found 
なるエラーになってしまった。 /usr/bin/nkf -e のようにフルパスで指定したり、 nkf '-e' のように引数をクォートしてみたりしてもダメ。 結局、nkf-e という名前で、次のような内容の 1行スクリプトを作成してしまった。
#!/usr/bin/nkf -e
本当はどうやるのが正解なんでしょうね?

追記 (2002-09-21)
"nkf -e" のように、ダブルクォートで囲むべし、 という情報を中川氏よりいただいた。 たしかにその通りで、ちゃんと nkf -e が動く。 私は 'nkf -e' のようにシングルクォートで囲むところまでは試したのだが、 「ふつう、シングルクォートで囲んでだめなら、ダブルクォートもだめだろ」 と勝手に想像して、それ以上試さなかったのでした。何事も先入観はいけません。

次に b であるが、記述言語として English を指定した場合、 生成される HTML ファイルの 先頭部分は、

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body bgcolor="#ffffff">
<!-- Generated by Doxygen 1.2.8.1 -->
………

のようになっている。太字の部分を見るとわかるとおり、このままでは、 やはり日本語が化けてしまう。 これを防ぐには、HTMLファイルの先頭部分を置換する、自前のヘッダー部を用意すればよい。 生成されたHTMLファイルを見ると分かるが、doxygen が作成するドキュメント本体部は、

  <!-- Generated by Doxygen 1.2.8.1 -->

という行から以降であり、その前の部分は、ユーザが用意したファイルで置換することが できるのである。たとえば、次のような内容のファイル my-header.html を用意し、 設定ファイルの項目 HTML_HEADER で指定すればよい。

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

日本語マニュアル

google などで検索してみたが、 doxygen の日本語マニュアルというのは存在していないようなので、 とりあえず、ちょっとだけ、翻訳してみた。

(2002-09-18)
本マニュアルはすでに古くなってしまっていると思われる。 参照される場合は、最新の原マニュアルも手元においておかれたい。 時間ができたら、最新版と付き合わせをやりたいのだが…… というか、後を継いでやろう! という方がいらっしゃれば、 ぜひご連絡ください。

「インデックス」 を開いて、 日本語のセクション名の付いているものが、翻訳済みのセクションである。 2001年10月17日現在、バージョン 1.2.11.1 の、

の 10個のセクションが翻訳されている。 doxygen-html-jp.tar.gz をダウンロードして展開した後、 /usr/local/doc/doxygen/html/ あたりにコピーされると良いかと思う。 記述内容については、全てを確認しながら翻訳したわけではないので、 誤りも数多く含まれているかと思うが、参考にしていただければ幸いである。 また、誤りや訳の脱落などがあれば、遠慮なく指摘していただきたい。

さて、大物のセクションが片づいたので、後は、インデックスの上のほうから一つずつ、 つぶしていくことにしたい。 また、毎度のことだが、無駄な努力はしたくないので、どこかに日本語マニュアルが存在しているなら、 教えてくださいな。


謝辞

本稿の記述に際しては、以下のページを参考にさせていただいた。

初出: 2001年6月10日


ホームページへ / Last modified: 2003-02-02 10:37:54 JST
Created by OKA Toshiyuki < oka-t@fides.dti.ne.jp >