人気ブログランキング | 話題のタグを見る

[perl] perl だって Doxygen が使いたい!

前投稿に引き続いて、自動的にperlソースからドキュメントを作ろう企画。

これは何ですか?


Doxygen は強力なドキュメンテーションツールです。
プログラム中に書かれた定義とかコメントとかを解析して、
美しい HTML にしてくれます。
これがあれば、詳細設計書はばっちり。
(設計書って作る前に書くんじゃ?という話はナシ)

しかし、オリジナルの Doxygen は Perl には対応していません。
その代わり、perldoc とか Pdoc とかを使っていたわけですが、
なんつーか、イマヒトツな感が否めません。
そんな Perl に対応してくんないかなーと思っているアナタのために、
エライ人が filter を作ってくれました。

Doxygen
Perl Doxygen Filter

インストール


Doxygen すらインストールされていなかったので、まずインストール。
RedHat EL ES 4 なので、rpm で入れました。
CD 同梱のヤツはバージョンが 1.3.9 と古いので、以下のを入れました。
Fedora Core 3 用ですが、ちゃんと動作しました。
http://cvs.planetsaphire.com/rpms/doxygen/i386/1.5.1/1.5.1-3/

次に、Perl Doxygen Filter のインストール。
前述のリンク先には、素晴らしいことに rpm が用意されています。
これをダウンロードしてインストール。
root# rpm -i doxygenfilter-1.01-1.noarch.rpm

はいおしまい。

使ってみる


  1. 設定ファイルを作成
    設定ファイル(configuration file)ってのを作るらしいよ。
    $ doxygen -g

    カレントに Doxyfile というのが作られます。

  2. Perl用設定を加える
    上記で作られた Doxyfile に設定を加えます。
    ↓これは既存のキーに設定。
    FILE_PATTERNS = *.pm *pl

    ↓これはキーがないので、新規作成。
    INPUT_FILTER = doxygenfilter

    ↓必要があれば、出力先も設定しとく。
    ディレクトリは先に作っておいたら良いと思うよ。
    OUTPUT_DIRECTORY = /home/myname/public_html/doxygen

    日本語で出る。
    OUTPUT_LANGUAGE = Japanese

    HTMLがフレーム対応になるらしい。
    GENERATE_TREEVIEW = YES


    コンソールが使えるなら、
    doxywozard という便利ツールもあるらしい。

  3. 実行
    これでOK。
    Doxyfile はデフォルトのファイル名なので、指定しなくても良い。
    $ doxygen Doxyfile



ソース中のコメントの書き方とかコツとか


POD 形式ではなくて、javadoc みたいに書くのね。
サンプルは
/usr/share/doc/doxygenfilter/examples/
以下にインストールされるので、それを見ながら書く。

私はこんな感じに書いてみた。
## @method bool select ( scalar sql, arrayref res_array )
# SELECT 文を実行し、結果を配列に格納する。
#
# @param sql    : [in] select SQL 文
# @param res_array : [out] DBからの結果を格納する配列のリファレンス
# @return 成否の真偽値
#
# エラー内容は $self->{'DBH'}->error で参照可能。

# 未定義値が返れば成功。
sub select ($$) {
...


★ 関数定義の行の $sql は scalar sql と変換してくれるんだけど、
\@res_array は arrayref とは変換してくれない。
@res_array だと list res_array にしてくれるんだけどね
(list よりは array にして欲しいんだが)。
じゃリファレンスを戻した形なら良いのかと、
@$res_array なんて書くと、 list_or_scalar array になります。
全然違っうっちゅーねん!!!
なわけで、自分でゴリゴリ書くのが良さそう。
一見、perlっぽくないコメント。
@INC/Doxygen/PerlFilter.pm の munge_parameters 関数に
手を入れると、対応できそうなんだけどね。
(実は結局手を入れてしまったwww)

★コメント中は HTML タグも効くので、
pre タグや br タグを使うと見やすいです。

★関数の定義と、出力される分類の対比はこんな感じ。
(ドキュメントがないから、ソース読んじゃったよ…)
## @method -> Public Object Methods
## @cmethod -> Public Class Methods

この method とかの後に、private をつけると、
Private なメソッドとして出力される。
protected とかもOK。
例えば、こんな感じ。
## @method private -> Private Object Methods


★この行頭 ## 2個ってのがミソみたい。
# 1個だけだと、なんか違う動きになる。

★同じディレクトリに、別の実行ファイルがある場合、
実行ファイルの中をクラス化してなかったりすると、
同じ名前の関数があれば、片方が無視されてしまうみたい。
1つのディレクトリ中に、複数の実行ファイルができるって、
よくあることだと思うんだけどなぁ。
exec_01.pl と exec_02.pl を作って、
その中に main て関数を作ったんだけど、
クラス化していなかったので、片方がエラーになっちゃって、
exec_01.pl の main しか、ドキュメントに反映されなかったのね。
エラーメッセージを出す設定にしてあれば、
こんなメッセージが出ます。
exec_02.pl:32: Warning: member main belongs to two different groups.
The second one found here will be ignored.

↓こんな風に、最初にパッケージ宣言すると大丈夫っぽい。
パッケージ宣言したら、ちゃんと ## @class を入れておきましょう。
## @class
# exec_01 class
package exec_01 ;
&main() ;
sub main {
 ...
}
## @class
# exec_02 class
package exec_02 ;
main() ;
sub main {
 ...
}


★マークアップの指定方法が @hogehoge なんだが、
これがまた perl のリスト変数とかぶるんだよねぇ。
コメント中に \@hoge のようにリストのリファレンスなんか書くと、
doxygen 実行時に waring が出る。
この @ をエスケープするには、@@ のように2つ重ねると良いみたい。
だから、表示上 \@hoge を出したい場合は、
\\@@hoge と書かなくてはいけない。
doxygen の表示上はいいけど、ソースを見ると一瞬「?」となる。

感想


Pdoc よりは良いかなぁ。
javadoc みたいな記述方法なので、
馴染みがあって、書いていて気持ち良いし、
ソース中のコメントが、自分にも見やすい。

以下の2つも後から入れておくと、
include (use) のツリーの絵が出て楽しいよー!
  graphviz-2.12.tar.gz
  global-5.4.tar.gz
インストール後は、doxygen を再インストール(再make)した方が吉かも。
最初から入れる場合は、doxygen は最後に。

perldoc、Pdoc、Doxygen と使ってみたけど、
どれも帯に短しって感じ。
まぁタダだから、文句は言えないか。
一番キレイなのは、この Doxygen かな。
by xiaoxia | 2007-03-14 21:23 | プログラム言語
<< 今年のマカロン [perl] Pdoc を使ってみる >>