Doxygenメモ

Doxygenはソースコードからリファレンスマニュアルを作成してくれるドキュメント自動生成ツールである。C/C++はもちろん、（今、気がついたのだが）Objective-Cにも対応とある。ちょっと試してみることにした。

準備するもの

Doxygen本体の他、PDF書類を作成するためにはLaTeXが必要。Graphvizはドキュメント内に埋め込まれる図を作成するために使われるツール、Doxygen内にも必要最低限の部分は含まれているので、わざわざ別に用意しなくてもよいがついで（と言っては失礼かな）に集めておく。全てバイナリパッケージで配布されておりソースからビルドする必要がないのは手間が省けてありがたい。

• Doxygen-1.5.1.dmg
• ptex_package_2005v2.1.dmg
• graphviz-1.13-v16.dmg

DoxygenとGraphvizはMac OS Xのアプリケーションになっているので、アプリケーションフォルダにでもコピーする。pTeXはインストーラーでインストール。アプリケーションバンドル内にパスを通しておく（.bash_profileなんかに、PATH=$PATH:/usr/local/bin: /Applications/Graphviz.app/Contents/MacOS: /Applications/Doxygen.app/Contents/Resourcesを追加、空白は取り除いてね）。

使い方

Doxygenアプリケーションを起動して設定ファイル(Doxyfile)を作成し、それをdoxygenコマンドに処理させるという流れだ。私の環境では、何がお気に召さないのかDoxygen GUI frontendの[Start]ボタンを押してもdoxygenコマンドを起動してくれないのでターミナルから、

$ doxygen

としてCommand Line Utilityを直接呼び出している。

特に面倒なこともなく、ソースコードのコメントも英文だけで書いている英語に堪能なヒトは、これだけできれいにまとまったドキュメントが出力される。

日本語を使う場合

日本語のドキュメントを作成するにあたっては、テキストエンコーディングの問題が出てくる。Doxygenは日本語コードがEUC-JPであることを前提としている。今回使用した桐木さんが配布なさっているpTeXパッケージはSJIS版*1。そして、私はMac OS X用のプログラムソースをUTF-8で書いている*2。文字コードがバラバラなので各所で変換が必要となる。

まずは、Doxyfileのカスタマイズポイントを挙げる。

• OUTPUT_LANGUAGE = Japanese
• INPUT_FILTER = "/usr/bin/iconv -c -f UTF8 -t EUCJP"*3
• FILTER_SOURCE_FILES = YES
• LATEX_CMD_NAME = platex

HTMLドキュメント生成だけならこれでOK。PDF書類を作りたい場合は、doxygenが生成するTeXファイルをShift JISに変換してやらねばならない。Rubyで変換スクリプトeuc2sjis.rbを書いてみた。Doxyfileで設定したLATEX_OUTPUTフォルダがlatexであるとして、次のようにする。

$ cd latex
$ euc2sjis.rb *.tex *.sty
$ make pdf

スクリプトeuc2sjis.rbは次の通り。

#!/usr/bin/ruby

require 'kconv'

while filename = ARGV.shift
  src = File.open(filename).read
  dst = src.kconv(Kconv::SJIS, Kconv::EUC)
  File.open(filename, 'w').write(dst)
end

紙の書類が大好き

こうして作成したPDF書類を印刷・簡易製本すれば、すばらしく体裁の整った納品物のできあがり。誰も読まない紙の書類の厚みで仕事を評価するようなITゼネコン＝お役所仕事な電脳公共事業にもバッチリ対応できる──じゃなくて、明日の自分や他の人に使ってもらうための見やすいドキュメントの作成に使うのが本来の姿なのは言うまでもない。

(2006-11-24)

コメントの付け方

javadoc形式で書くことにする（JAVADOC_AUTOBRIEFをYESに設定しておく）。javadocでは /** で始まって */ で終わる部分がドキュメントコメントとみなされる。細かいルールはいっぱいあるが、まず次の３つのパターンを実践。

クラスの説明＝宣言部の直前に書く。最初の一文（'.'で終了）でクラスについて簡潔に要約する。

/** クラスについて要約.
 * クラスの説明
 */

関数の説明＝実装部の直前に書く。宣言部には書かない。関数の機能および引数と戻り値を解説する。最初の一文で関数について簡潔に要約する。

/** 関数について要約.
 * 関数の説明
 * @param 引数名 説明
 * @return 戻り値 説明
 * @throws 例外クラス名 説明
 */

変数の説明＝直後に一行で書く。

/**< 変数の説明 */

とりあえず、これだけ書いとけばそれなりに分かるんじゃないだろうか。余裕があれば@seeも入れるといいかな。真面目にやりたい人はSUNによるjavadocの解説でも読めばいい。

当たり前のことだが、Doxygen用のコメントはドキュメンテーションを意図したコメントであるから、インプリメンテーションに関する情報を書いてはいけない。

(2007-04-07)

---

• *1 過去Mac OSで作成された書類の多くがSJISだからだろう。
• *2 最初からソースをEUC-JPで書いちゃえばいいのだが、Mac OS XのターミナルのデフォルトはUTF-8だし。そもそもソースに日本語リテラルなんか埋めちゃだめだって(^^;。
• *3 Doxygen 1.5.2ではデフォルトエンコーディングがUTF-8になっているようなので、INPUT_FILTER, FILTER_SOURCE_FILES指定はいらない。んだけど、PDFの生成がうまくいかない（TeX用の出力でエンコーディングがおかしいファイルができる場合がある？）。

©2006 "TAKAHASHI Ryoji" @zone0.net
Last updated: 2013-12-02