Doxygen with doxygenfilter for perl
Perlでも Doxygen が使いたいものよのぅ記録。
正直、PODって書きにくい読みにくいじゃないか? と思う今日この頃。別に CPAN Module 書くわけじゃないから、もっと書きやすく読みやすい記法でリッチなテキストをはいてくれるようにしたかったんだ。と言うことで、Doxygen がいいなあ、と。
Doxygen は C/C++ 系の言語向けのドキュメント生成ツールなので当然 Perl には対応していないのだけど、Perl に doxygen 用コメント書いて、doxygen 用のコードを生成させる doxygenfilter がある。でもこれあまり使っている人がいないのか、そんなに情報がないんだよね。
くらいだ。しかもプラットフォームを Windows とかにするとなおさら。
まあ、インストールするだけなんだけど。
- graphviz
- 既にインストールしていたので今回はパス。
- doxygen
- Doxygen本家とDoxygen_jp…和訳ドキュメントがありがたい。
- 今回は doxygen-1.5.7.1-setup.exe で。
- doxygenfilter
- About Perl Doxygen Filter
- このサイト、どこに何があるんだかわかりにくい。ダウンロードがどこにあるのかすら良くわからんかった。
- ダウンロードはここから 今回はWindows版バイナリ doxygenfilter-1.01.NTbin.zip で。
その後は doxywizard から doxyfile 作って実行するだけだ。項目としては以下のものを変更する。
- DOXYFILE_ENCODING
- デフォルトは UTF-8 になっている。SHIFT-JISとかにしておく。
- PROJECT_NAME
- お好みで。
- PROJECT_NUMBER
- お好みで。
- OUTPUT_LANGUAGE
- デフォルトはEnglishだけど、Japanese-en に変更。Japanese はちょっと動作が怪しげ。
- EXTRACT_[ALL|PRIVATE|STATIC|ANON_NAMESPACE] = YES
- HIDE_UNDOC_MEMBERS|CLASSES] = YES
- INPUT_ENCODING
- デフォルトは UTF-8 になっている。元ファイルに合わせる。
- CASE_SENSE_NAMES = YES
- SHOW_DIRECTORIES = YES
- FILE_PATTERNS = *.pl *.pm
- 必須。
- RECURSIVE = YES
- 対象ファイルがサブディレクトリ下とかにある場合は必須。
- INPUT_FILTER = /path/to/doxygenfilter.exe
- 必須。
- SOURCE_BROWSER = YES
- 元のコードをドキュメントに含めるかどうか。入れておいていい。普通に *.pl/pm ファイルがドキュメントに含まれる。
- GENERATE_LATEX
- お好みだけどいまは作らない。
- HIDE_UNDOC_RELATIONS = NO
- YESにしておくと、ドキュメント定義のない継承関係は図が生成されない。CPAN モジュールを継承して自前のモジュールを作っている場合なんかはここは NO にすべし。
- HAVE_DOT = YES
- [CALL|CALLER]_GRAPH = YES
くらいかなあ。ENCODING はちゃんと合わせないと文字化けるので注意。doxygenfilter の動きに物申したいこともないわけではないが…。Cygwin でインストールしてみたら単なる Perl スクリプトなので、適当に編集してカスタマイズしてしまえばよさそうではある。ただ、Doxyfile の Inputfilter には "perl doxygenfilter" みたいなかき方はできない(複数のパラメータを置けない)みたいなので、Windows 版 doxygen でやる場合は bat に埋めるとか小細工をしないといけないのかもしれない。