青木です。

  In mail "[ruby-reference-manual:73] Re: 作業マニュアル #1 (フォーマット変換)"
  SASADA Koichi <ko1@a...> wrote:

> 　ささだです。

> >> ・ドキュメントの構造
> >> 　http://www.typemiss.net/blog/kounoike/20060120-54
> >> 　この辺で出ている話。

> 　各クラスに Summary とか要らないのかな、とかが元の質問の意図でした。

理想としてはあるべきだと思いますが、やはり手間の問題は無視
できません。また、やるにしても、全ライブラリをカバーして
さえいない現状でそんな贅沢言ってどーすんだって気がします。

# 文章の品質に関しても思うところはありますが、
# まだその段階ではないと考えて触れないようにしています。

まあ、現状で考えるべきことがあるとすれば、システム側の制約で
理想の形を不可能にしてしまわないようにすることくらいでしょうか。
ですが、問題のページを見る限り、システム的で特別に問題がある
とは思いません。

上記のページで挙げられているのは以下の 8 つです。

   1. NAME
   2. VERSION
   3. SYNOPSIS
   4. DESCRIPTION
   5. （メソッドor関数の詳細など）
   6. SEE ALSO
   7. AUTHOR
   8. COPYRIGHT 

このうち 1. name, 4. description, 5. detail はすでにあります。

2. version は標準添付ライブラリには関係なし。強いて言えば全部
Ruby と同じバージョンと考えるべきでしょう。で、そのバージョンは
データベースのプロパティとして保存されています。

3. synopsis は人間ががんばって書くという話だと思うのでシステム
には関係なし。

残った 6, 7, 8 は require と同じようにライブラリのメタデータ
として追加できるようにすればよいでしょう。


> 　net/http.rb だったら、現在はライブラリごとに1つのページ（Net::HTTP、
> class Net::HTTPRequest、class Net::HTTPResponse が1つのページ）ですが、
> webrick.rb は各クラスごとに複数ページに分離されています。
> 
> 　意図としては include で1つのページにまとめることを狙っていると思うので
> すが、WEBrick や optparse は長大になりそうです。

まず、用語が混乱してきたので整理します。

: ページ
    出力された HTML のページ。
: ライブラリ
    論理的な、クラスの集合。
: ライブラリのページ
    ライブラリ単独のドキュメントを表示するページ。http://..../library/NAME
: ライブラリの目次
    ライブラリの一覧を表示するページ  http://..../library/
: ライブラリのドキュメント
    ライブラリのドキュメントを収めた物理的なファイル。*.rd
: ライブラリのソースコード
    ライブラリのソースコードを収めた物理的なファイル。*.rb

net/http という論理的なライブラリは一つのソースコード
ファイルでできています。webrick ライブラリは複数のソース
コードファイルでできてします。

で、ライブラリのドキュメント *.rd が同じように分割される
べきかと言うと、わたしはそうは思っていません。ドキュメントが
表現したいのはソースコードの構造そのものではなく、ユーザから
どう見えるかです。ユーザから見たときのライブラリとは、require
する名前と、クラスとメソッドの集合と考えられます。ソースコード
が複数あろうとも、もし仮に require するのが webrick 一つだけ
であれば、論理的に一つのライブラリと考えるべきです。したがって、
ドキュメント上も一つのライブラリと表現すべきです。

また、新しい形式にはメタ情報として require 関係が与えられて
いるので、require を芋蔓式にたどって表示することも可能です。
それではメソッド数が増えすぎるというのであれば、クラスを折り
たたんで表示するなどの方法もあるでしょう。

# require に関して細かいことを言うと、require をたどるのは
# 同じライブラリ間だけにすべきかもしれません。例えば webrick
# から stringio を require していても無視するとか。


> >> ・パラメータ（引数）、返り値の型はどう表現する？
> > 
> > いまのとこ型をメタデータとして保持することは考えていません。
> > しかし、TMail とかのリファレンスでは型もぜんぶ書いてるので、
> > その仕組みをもってくれば実装は可能です。あとは「やるか、
> > やらないか」ですね。個人的にはやりたいですけど、手間がどうかな。
> 
> 　悩ましいですね。to_str を持つオブジェクト、なんてどう表現するんだか。

うん、そうなんですよね。まあ例外にぜんぶ気を遣ってもしょうが
ないですから、とりあえず Object にしておき、説明で補う、
などの手段もありえます。

また、最終的にはドキュメントを出力するのが目的ですから、
ようするに引数にどういう条件があるのかがわかればよいわけです。
そう考えると、別に型をクラスで指定する必要はなく、文章でも
構わないのではないかとも思えます。

例えば String#to_i ならば、

  --- to_i(base)
  :type:base: class(Integer) | have(#to_i)

とかテキトーにメタ情報を加えてやることもできるかなあと思います。

--
青木峰郎

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/