[ruby-list:10652] Re: Ruby Document Format

福嶋です。

Motoyuki Kasahara <[e-mail]> wrote:
> ところで、XML については、私は付け焼き刃以下の知識なのですが、rubyapi.
> dtd で、
> 
>     <!ELEMENT methods ((method|alias)+,desc*)>
>     <!ELEMENT method (usage*,alias*,desc*)>
> 
> のように、単数形と複数形の両方が定義してある element が幾つかあります
> が、これは一般的にこうするものなのでしょうか。なんとなく、(クラスによっ
> ては、一個しか定義しないかも知れないけれども) 複数形の element だけ用
> 意しておけば良さそうな気もするのですが。

私の書いた rubyapi.dtd では method, methods は両方とも class_methods,
instance_methods の中で使われる要素だと考えています。

XML の一般的な作法についてはよくわかりませんが、method と methods とい
う 2 つの書き方を作ったのは、現在の ruby の組み込みクラスのドキュメン
トの書き方に対応させるためです。

具体例で言うと

<class>
  <name>String</name>
  <instance_methods>
    <method>
      <usage>length</usage>
      <alias>size</alias>
      <desc>
        文字列の長さを返します．
      </desc>
    </method>
    <methods>
      <method><usage>chop</usage></method>
      <method><usage>chop!</usage></method>
      <desc>
        文字列の最後の文字を取り除きます。
      <desc>
    <methods>
  </instance_methods>
</class>

method は一つのメソッド(とそのメソッドの 0 個以上の別名)に対して説明
(desc) を付ける要素です。上の例の場合、length と size です。

methods は 2 つ以上のメソッドに対して、まとめて desc を付けるための要
素です。上の例の場合、chop と chop! です。

ここで私が考慮したのは chop と chop! の 2 つは別のメソッドだが、名前も
機能も似ているので記述が一つにまとめられている、ということです。それを
表すために methods という要素を定義しました。

はたして、こんな違いまで記述する必要があるのかどうかに確信はありません。

<methods> とドキュメント上の 「メソッド:」は実は対応していないのです。
「メソッド:」と対応しているのは <instance_methods> なのです。
ちょっとわかりにくいのですが、他に良いネーミングが思い付きませんでした。

---
福嶋正機