[ruby-list:12094] Re: Documentation

いがらし＠早大です。
＃卒論が終り、数カ月ぶりにRuby三昧の日々を送っています。

「[ruby-list:12088] Re: Documentation」で 、
Masaki Fukushima <[e-mail]>さんは書きました：

> > http://www.goto.info.waseda.ac.jp/~fukusima/ruby/xml/
> > 
> > ↑これでいいんじゃないかと思います。あるいは、このDTDで書いたXMLを
> > 元にして、SmartDocに変換するとか。
> 
> 実はこれは最近全然いじっていません。
> 自分の書いたライブラリのドキュメントを書くのには使っているのです
> が、公開できるレベルには至っていません。
> 
> ソースもかなり汚いので。
> # そもそも XML::SimpleTree::Visitor の使い方を良く理解していない。

私も使い方をよく理解しないまま書きはじめたところなのですが、
http://www.ueda.info.waseda.ac.jp/~igarashi/ruby/rubyapi2.rb
見ての通り汚いプログラムになっております。
いわゆるVisitorパターンだというのは分かっているのですが……

> 最近は Ruby のドキュメントを書くのに XML を使うのは大袈裟かな、と
> 思ったりもします。XML はこの目的には汎用的過ぎるかと。

確かにソースプログラム(Rubyスクリプト・拡張モジュールのCソース)や
リフレクションで得られる情報をもとに自動的に生成できるなら、
わざわざXMLを介さなくてもいいと思います。

> 特に Ruby の場合、スクリプトからクラスのメソッド一覧を見たりでき
> るので、どうせやるならそういうメタレベルの機能を利用した方が良い
> のかもしれませんね。

引数の個数など、現状のリフレクションAPIでは調べられないけど
欲しい情報もあるんですよね。かんださん作のgtkbrows.rbも、
あと引数の個数(と各引数の意味が連想できるような引数名)が
見えるようになると、もっと便利になるかと思います。
もっとも、Cで書かれたり def f(*args) みたいなメソッドは
どうするか、という問題もありますが。

javadocのように、ソースプログラムをちゃんと解析して
埋め込みドキュメントをもとに生成した方がいいのでしょうか。
拡張モジュールの方は、Cのソースプログラムにドキュメントを
埋め込むようにしたり。

> XML の需要があるとしたら多国語のドキュメントを一つのファイルで書
> けるところでしょうか。ソースに日本語のドキュメントを含めたくない
> と思う人も多いと思うので。

ソースに日本語等を含めないようにと考えると、
埋め込みドキュメントには英語で最低限の情報だけを
入れるのがいいんでしょうね。で、詳しい(あるいは多国語の)
ドキュメントは、XMLか何らかの形式で別に用意すると。

----
五十嵐  宏  (Hiroshi IGARASHI)