福嶋です。

Hiroshi Igarashi <igarashi / ueda.info.waseda.ac.jp> wrote:
> >   o  <usage>each([rs]) {|line|...}</usage>
> > 
> >     と書くだけで、each がメソッド名、rs は引数名、line はブロックへの
> >     引数だと自動的に判断してほしい。これをわざわざドキュメント作成者が
(略)
> タグ内のテキストをさらに解析するのはXML的にはちょっと
> 反則っぽい気がします(勉強不足ではっきりしたことは言えませんが)。

そうですよね。やっぱり。 (^_^;)

あえてこうしたのには一応理由があって、XML としての正当さを追求するあま
りに、ツールとして使いにくいもになってしまうのは避けたかったのです。テ
キストからでも読み取れる情報は読み取って欲しいと。

で、現状の ruby の組み込みクラスのドキュメントを見る限りでは、個々の引
数についての説明は (メソッド自体の説明に含まれているものを除くと) 無く
てもよさそうなので、<usage>〜</usage> という形にしてしまいまいした。

> それに説明文中の引数名もvarタグで囲みたいと思っても、
> そちらまで自動でやるのは難しそうです。

これはそうですね。特に英語の説明文中では偶然引数名と同じ単語が出てくる
ことも考えられるので、自動的にタグを付けるのはやめた方が良いと思います。
私の方でも、これはやっていません。

> >   o  <r>$/</r>
> >      <r>Fixnum</r>
> > 
> >     とか書いたら、HTML に変換する時には自動的に variable.html#slash や
> >     Fixnum.html にリンクを張って欲しい。
> 
> XSLなどでは各要素の処理規則中にスクリプトが書けるので、
> そこでそれなりの処理をすればできるのでは？

なるほど。

> 出力形式に依存したXSLやXML Treeのvisitorを書く必要は
> ありますが、ライブラリやツールは汎用のもので
> 実現できるのではないでしょうか。

一つ気になるのは、こういったツールは Java が多いですよね。ruby のドキュ
メントを書くツールなのだから ruby で書きたい、と思うのは私だけでしょう
か?
これを気にしなければ、確かに利用できるツールはたくさんありそうなのです
が...

> 必要に駆られて始めたものの付け焼き刃的な知識しかないので、
> こうすべきだという提案ができなくてすみません。

いえいえ。私も付け焼き刃ですから。
XML に詳しい方がいれば、ぜひ意見を聞かせてください。

---
福嶋正機