作者: dune
日時: 2003/12/16(21:58)
極悪です。

ねこ丸 さんの [TSperl:291] Pdoc 発見 から
>  まだ全然中見てないんですけど、こんなもの見つけました。
>  http://pdoc.sourceforge.net/

ダウンロードしてみたけど使い方がさっぱりわからん。
このモジュールを使って自分でツールを作れってことなのでしょう
か（ぎゃふん）。

昨晩、DOXYGEN という C/C++ 用のドキュメント作成ツールを見つ
けて使ってみました。引数リストのすぐ右側に説明が書けたりして
なかなか良さげだったのですが、数時間使ったところで飽きました
（※）。つまらないことですが、! や <, @ といった記号（約束
事）が妙に目立って C++ のソースが perl みたいになってしまっ
たから。

こういうツールを意識してコメントを入れるのって苦手です。
POD もやはりそうで、何かルールがあるとそれに従って書くのが苦
痛ですぐ飽きてしまいます。

こんな調子なので、僕はソースやスクリプトに定型のコメントって
あまり要れません。Perl モジュールの Math::Project3D のコメ
ントの入れ方は好きなので、これくらい書ければいいかなとは思い
ますが、最後の POD セクションはやはり邪魔に感じます
（hoge.pm とは別に例えば hoge.pod というファイルを作って分
けたほうが楽ちゃうん？ と思う）。

そういえば会社でひきついだ C++ のソースも、役に立たないコメ
ントにムカついて、それ用の perl スクリプトを書いて片っ端から
コメントを削除＆整形しました。

ということで、スクリプトやソースを理解するための簡単なインラ
インコメント以上の、DOXYGEN や POD に渡してドキュメントを作
るためのコメントを入れるのって苦痛ではないですか？

DOXYGEN は比較的コーディング作業と相性が良いと思いますが、
Perl の POD の場合は書く気になりませんです（自分向けにインラ
インで簡単なコメントを書くのは好きですけど）。



※ ）DOXYGEN のルールに合わせてコメントを入れるのは苦痛なの
で飽きましたが、一方でこのツールが出力する HTML は凄いです。
メソッドやオブジェクトの一覧は出るし、関数のセクションでは呼
び出し元を探してリンクも貼ってくれる、GraphViz で依存関係の
グラフも描いてくれる。頭の中にしかなかった自分のコードの設計
図が、図入りの便利なハイパーテキストとして具象化するのは感動
です。
-- 
FZH01112 at nifty.com
http://hpcgi1.nifty.com/dune/gwiki.pl?