Doxygen with doxygenfilter for perl

Perlでも Doxygen が使いたいものよのぅ記録。
正直、PODって書きにくい読みにくいじゃないか? と思う今日この頃。別に CPAN Module 書くわけじゃないから、もっと書きやすく読みやすい記法でリッチなテキストをはいてくれるようにしたかったんだ。と言うことで、Doxygen がいいなあ、と。
DoxygenC/C++ 系の言語向けのドキュメント生成ツールなので当然 Perl には対応していないのだけど、Perldoxygen 用コメント書いて、doxygen 用のコードを生成させる doxygenfilter がある。でもこれあまり使っている人がいないのか、そんなに情報がないんだよね。

くらいだ。しかもプラットフォームを Windows とかにするとなおさら。


まあ、インストールするだけなんだけど。

その後は 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
    • graphviz で図を生成する。いまの環境だと、Windowsgraphviz をインストールして、dot.exe とかがコマンドラインから使えるように PATH を通してあるので他ない特に設定がいらないが、PATH 通していないのであれば、バイナリパスをどこかで指定する必要があるはず。
  • [CALL|CALLER]_GRAPH = YES

くらいかなあ。ENCODING はちゃんと合わせないと文字化けるので注意。doxygenfilter の動きに物申したいこともないわけではないが…。Cygwin でインストールしてみたら単なる Perl スクリプトなので、適当に編集してカスタマイズしてしまえばよさそうではある。ただ、Doxyfile の Inputfilter には "perl doxygenfilter" みたいなかき方はできない(複数のパラメータを置けない)みたいなので、Windowsdoxygen でやる場合は bat に埋めるとか小細工をしないといけないのかもしれない。