document.pi is Pi source.(ShiftJIS)

Ruby Module Document の書きかた

はじめに

『ソースがドキュメントだ』と言っても，使う側にしてみれば母国語で書かれた解説書ほどありがたいものはない。

ソフトウェアプログラミングにおけるドキュメントについて一般的に論じたいと思うが，特に Ruby を素材にするつもりである。

オブジェクト指向の場合，メソッドはクラスでまとめられているから，文書にする場合でも， 1 クラスに 1 ファイルというスタイルが自然である。

document と source を同じファイルに記述すべきかどうかは意見の分かれるところである。

同じにする利点は，ある source についての document がほしくなったときに探し回る必要がない，ということに尽きる。書き手にとっては， source と document を相互参照しながら記述を進められる利点がある。配布するときには， source と document が別ファイルになっていると両方の在処を明記するか， tar で固めるかしないといけなくなるが，同じファイルに記述した場合は，この心配はない。

こう書くと， source と document は同じファイルにすべきだと思われるだろうから反論してみよう。

同じファイルに source と document を書くとファイルが大きくなる。小さな source なら問題ないだろうが，ある程度の規模になると document が source を読みにくくする。 source を分割すればよいが，それもまた可読性を欠く要因になるだろう。まあ，使いやすいエディタを使えば問題にならないかもしれない。

同じファイルに source と document を書くと document の書きかたが規則に縛られることになる。しかし，これもそれで統一性が生まれていいのかも。

ああ，反論できない。

しかし， document の内容と source の内容は食い違っていることがよくある。それは， document が間違っているのかもしれないし， source が間違っているのかもしれない。

何に対して間違っているのかについても注意を払う必要があるだろう。たとえ source による挙動と document の記述が一致していても，仕様書に対して間違っていては何にもならない。また，利用者の要求に対して間違っていれば，普及は望めないだろう。

source を書いてから document を書く，もしくは document を書いてから source を書く，これらの手法についてはのちほど述べたいと思うが，ここでは source と document を同時に書くことはできない点に注意されたい。それをするには source から document へ自動的に翻訳する仕掛けが必要になるが，現状では困難である。

つまり， source に書かれた内容を説明するのが document なのであるが， document は source の自然言語への翻訳と捉えることができるのである。

結局，『ソースがドキュメントだ』は唯一問題のない解決策なのだ。ただ，誰も納得してくれないのが弱点である。

RD

RD は Ruby 界の標準となりつつあるドキュメント機構である。 source 内部に document を持つ。 document を記述する際に Ruby の埋め込みドキュメントの仕組みを利用する。これは POD(Plain old documentation) として知られる。この手法は Perl によって広まったようだ。 perlpod(1) 参照のこと。

javadoc

javadoc は Java のドキュメント機構である。 source 内部に document を持つ。 texinfo そっくりなエスケープ記法を用いる。 javadoc は Java source file から comment を抜きだして HTML を生成する。