前投稿に引き続いて、自動的に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 はいおしまい。 使ってみる
ソース中のコメントの書き方とかコツとかPOD 形式ではなくて、javadoc みたいに書くのね。 サンプルは /usr/share/doc/doxygenfilter/examples/ 以下にインストールされるので、それを見ながら書く。 私はこんな感じに書いてみた。 ## @method bool select ( scalar sql, arrayref res_array ) ★ 関数定義の行の $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 この 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. ↓こんな風に、最初にパッケージ宣言すると大丈夫っぽい。 パッケージ宣言したら、ちゃんと ## @class を入れておきましょう。 ## @class ★マークアップの指定方法が @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
| プログラム言語
|
カテゴリ
以前の記事
2022年 12月 2021年 05月 2019年 12月 2018年 12月 2018年 05月 2018年 03月 2017年 03月 2017年 02月 2016年 08月 2016年 04月 more... 最新の記事
最新のトラックバック
ライフログ
今読んでる
その他のジャンル
記事ランキング
ブログジャンル
|
ファン申請 |
||