青木です。

On 2007/02/20, at 22:35, Ken Date wrote:

> 伊達です。

> なるほど。てっきり現行の RWiki のリファレンスをベースに 
> 加筆訂正していくのかと思っていましたが、新たに書き起こすのです 
> ね。

あ、いえいえ、もちろん既存のリファレンスは使います。
上記の話はもともとドキュメントが存在しなかった場合や、
書いてあったとしても動作を確認するときの話です。

また、@arg とか @raise を導入するのは、書くべきこと
をすべて書いているかツールで確認しやすくするためと、
できるかぎり形式を統一するためです。

>>    @raise ArgumentError 上記以外の引数を渡し、
>>    かつそのオブジェクトが to_s メソッドを持たないときに発
>> 生します。
>>          ← メソッドの選択が悪かったのでかなり無理無理 
>> な条
>> 件になってしまった
>
> これは明示的に raise しているのだけ書けばいいでしょうか。
> 発生しうる例外を網羅的に書くのはかなり辛そうです
> （特に Ruby で書かれた拡張ライブラリ）。

はい。リファレンスの方針を決めるときの規準は常に
「その情報が役立つかどうか」です。で、ドキュメント
に例外を書くのはなぜかと言うと、その例外を rescue
したい場合があるからでしょう。ですから、一般的に
考えて rescue する価値のない例外を書く必要はありま
せん。

例えば NoMemoryError はけっこういろんなところで
発生するんですが、これは rescue する価値がほとんど
ないので無視して構いません。バグに起因する例外も
書く必要はありません。

一方、書いたほうがいい例外は例えば Timeout の
TimeoutError とか、Net::HTTP の Net::HTTPServerError
とかです。Hash#fetch の KeyError も書くべきです。

ArgumentError, TypeError は微妙。@arg で引数の条件
がちゃんと書いてあれば、こいつらはたぶん書く必要
ないと思います。

書いたほうがよいが、すごく大変な例としては SystemCallError
のサブクラスが挙げられます。これはできれば書きたい
ですが、OS によって例外が違ったりしますし、このへん
の洗い出しに時間をかけるよりはドキュメントのないライ
ブラリを書くほうを優先してください。

--
青木峰郎


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