RDoc と Pdoc

RDoc は Pdoc よりも素朴だ。

  • Pdoc は pod での記述を要求するが、
  • RDoc は # でコメントを書くだけでよい。一部 RD の記法も利用できる。

Pdoc は、

sub method

と同じ

=head1 method()?$

を要求する（余計な空白とか入っちゃだめ）が、

RDoc は、

#
# ここのドキュメント
#
def method

各定義前のドキュメントが自動的に method や class のドキュメントとして採用される

長いドキュメントをソース中に埋め込むには pod 形式を採用している Pdoc の方が向いていると思われる。Ruby にも RD があるからその方がよいのではないかと思うが、# を利用した方が使い始めの敷居が低いのは確かだ。

しかしうらめしいのは RDoc と RDTool を併用できないというところであろう。RDTool が Ruby のドキュメントツールの標準として確立されていなかった（事実上の標準だったかもしれないが）たために、せっかくの RD を活かしきれない形になってしまっているように感じる。LL な人たちはあの # を何行も何行も書くのって苦痛じゃないの？ # 形式って自然とコメント書くのが億劫になってよくないと思うのは自分だけなんだろうか？

RDoc の get

本家の sourceforge が Ruby core に取り込まれたので project を inactive にしてしまった。1.6系で RDoc を使いたい場合は

ruby-lang.org の CVSWEB から落とすしかない。

参考

RDoc を使うにはとりあえず

を読むとよい。

しかし

Ruby 1.8 に取り込まれて以降、RDoc は Ruby 1.8 に依存した機能もあるようで、RDoc 使うには 1.8 インストールが最もよい、という結論が出ました。

More