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 をインストールする。手順はいたって簡単。
% tar xzvf doxygen-1.2.17.src.tar.gz% cd doxygen-1.2.17configure を実行する:
% ./configure --prefix /usr/localまた、私は不要なので指定しなかったが、Qt-2.1.x をインストールしている人で GUI なフロントエンドを使いたい場合は、 --with-doxywizard オプションを指定するとよいらしい。
% make% make docs% su# make install# make install_docs
これで終わりである。何も難しいことはない。 (まあ、ソースからビルドすると、若干時間はかかるが)
次は、graphviz のインストール。これは、上にも書いたように、 クラスの継承関係やファイルのインクルード関係を図示するには必須のツールなので、 是非ともインストールしてほしい。私の場合、手順は次のとおり。
% tar xzvf graphviz-1.8.9.tar.gz% cd graphviz-1.8.9/configure を実行する:
% ./configure% make% su# make install以上である。
doxygen は、独自の設定ファイルを読み込み、その設定内容にしたがって、 ソースコードからドキュメントを生成する。
設定ファイルは、doxygen 自身が、そのテンプレートを作成してくれる。
% doxygen -g [<設定ファイル名>]
たとえば、doxygen -g doxygen.conf を実行すると、
"doxygen.conf" という名前の設定ファイルが作成される。
<設定ファイル名> を省略すると、"Doxyfile" という名前の設定ファイルが作成される。
生成された設定ファイルには、設定項目が山ほど書かれているのだが、大半は、 デフォルトのまま使用しても大丈夫であろう。私が変更したのは、次のような項目である。
以下、項目名を示して説明する。
PROJECT_NAMEプロジェクトの名前を設定する。サンプルでは、 File IO Wrapperにした。PROJECT_NUMBERリビジョン番号などを設定する。サンプルでは、 1.0になっている。OUTPUT_LANGUAGE生成するドキュメントの記述言語を設定する。言語といってもプログラム言語のことではなく、 英語や日本語など、どの自然言語を使うか、という設定である。サンプルでは、 Japaneseになっている。EXTRACT_ALLコメントの付いていないようなエンティティも含めて、すべて、ドキュメント化するか 否かの設定。デフォルトは NOだが、 サンプルではYESに設定した。JAVADOC_AUTOBRIEFYESに設定すると、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通りの方法がある。
INPUT_FILTER を使って、
ソースファイルをコード変換する
まず 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日