From: Motoyuki Kasahara <m-kasahr@...>
Date: 1998-10-09T11:17:08+09:00
Subject: [ruby-list:9909] Re: comments on manual (Re: man-1.1/Marshal.html)

SRA の笠原です。

* From: matz@netlab.co.jp (Yukihiro Matsumoto)
* Date: Thu, 8 Oct 1998 18:53:58 +0900

> |ところで、マニュアルに関するこの類いの話は、このメーリングリストで積極
> |的に行って良いでしょうか。マニュアルに関しては、他にもいくつか気付いた
> |ことはあるのですが、このメーリングリストは、なんとなくプログミング寄り
> |の話が主なようですので。
> 
> 遠慮なくどうぞ．ruby-listはrubyに関すること全般を取扱います．
> ただし，rubyそのものの実装などやや難しめの話題はruby-devに行
> くというルールだけがあります．

ええと、では、いくつか気付いたことを書いてみました。
何も貢献せずに指摘だけするように聞こえたら、ごめんない。

* IO クラスの `read [length]' メソッドの説明 (IO.html) ですが、「EOF
  を読み込んだときは nil を返す」という記述が抜けています。

* 組み込みクラスのマニュアル全体に言えることですが、期待した動作が失敗
  した場合、何が起こるのか、例外が起こるとしたらどういう例外なのか、の
  記述がないようです。

  たとえば、File クラスで open に失敗したらどうなるか、Array で範囲外
  の要素をアクセスしたらどうなるのか……こうしたことは試してみればすぐ
  に分かりますが、逆に言えば試さないと分かりませんでした。これらのこと
  はマニュアルに書いてあった方が良いと思うのですが、いかがでしょうか。

* 指摘というわけではないのですが、添付ライブラリのドキュメントは、今後
  整備されていく予定はあるのでしょうか?  `$(libdir)/ruby' の下に、いろ
  いろと *.rb ファイルがあるのですが、どうもドキュメントが無いものが少
  なくないようです。添付ライブラリと比較すると寂しいです。
______________________________________________________________________
                                          笠原 基之(かさはら もとゆき)