青木です。すみません、返信するの忘れてました。

On 2007/03/04, at 10:55, sheepman wrote:

> こんばんは、 sheepman です。
>
> 返り値のための @return みたいなのは、導入しないのでしょ 
> うか。
> あんまり多くすると繁雑になってしまいますが。

@return を導入することは想定してませんでした。
なぜかというと、

   1. 返り値に意味があるメソッドの場合 (function 的なメ 
ソッドの場合)、
     メソッドの意味とはつまりselfと引数と返り値の関係のこ 
とであり、
     当然、最初の一文で返り値について書くはずである。

   2. 返り値に本質的な意味がない場合 (procedure 的なメソッ 
ドの場合)、
     返り値を積極的に書く意義がない。

と考えるからです。

function的な例：String#sub → 変更後の文字列を返す
procedure的な例：Array#each → 返り値なんて知らねー

しかしそれでは procedure 的メソッドのときの返り値はどこに
書けばいいかと考えると、@return があってもいいのかなあという
気もします。

もっとも、@return がなければ返り値を書けないわけではないの
で、問題は「@returnで返り値を書くか」「普通に文章で書くか」
ですね。それから、

   1. 型を書くのか
   2. 複数の型や意味がある場合、一つの @return で書くか複 
数に分けるか

を決めればいいかな。

んでまあこういうのはコンセプトから議論してもたぶん収拾が
つかないので、とりあえずわたしの趣味に走った具体案を一つ
出します。

   * 返り値の型をシグネチャ行に「->」で記述する
         * (要検討) procedure 的メソッドには記述しない？
   * function 的なメソッドでは要約で必ず返り値に触れる (完 
全でなくてよい)
   * @return は使わない
   * それ以外に特に説明が必要なときは本文で、第二段落以降に書く

[例]

   --- map {|item| ... } -> [object]

   各要素を順番にブロックに渡し、
   その評価結果をすべて含む配列を返します。

   --- map -> [object]

   ブロックを省略した場合は obj.map {|item| item} の結果を 
返します。
   [[m:Enumerable#to_a]] と同じです。

   --- each_with_index {|item, index| .... } -> self

   要素とそのインデックスを両方ブロックに与えて繰り返します。

   --- find([ifnone]) {|item| ... } -> object
   --- detect([ifnone]) {|item| ... } -> object

   要素に対してブロックを評価した値が真になった最初の要素を返し 
ます。
   真になる要素がひとつも見つからなかったときは nil を返し 
ます。
   またそのとき、Proc オブジェクト ifnone が指定され 
ていたら
   その Proc を呼び出します。

[返り値の記述方法]

   * 任意の型の場合、「object」
   * x の配列は [x]
   * インデックスによって型が違う配列は [x, y, z]
   * x から y のへのハッシュは {x => y}
   * true, false, nil, self を返すときはそのまま
   * 真偽値を返す場合は「bool」
   * 多値も配列扱い
   * 複数の型の値を返すときは原則としてシグネチャを分ける
   * それでうまくいかないときは "|" を使って記述
      例：  CGI#[](name) -> String | [String]
   * ただし x オブジェクトと nil で成功・失敗を表す 
場合は「x | nil」を使う
     例：String#index(略) -> Integer | nil
   * 以上のルールで記述できない場合は「object」と書いて文 
章で説明

[返り値の型の記述の例]

--- Enumerable#all? {...} -> bool
--- Enumerable#any? {...} -> bool
--- Enumerable#map {...} -> [object]
--- Enumerable#each_with_index {...} -> self
--- Enumerable#detect {...} -> object
--- Enumerable#select {...} -> [object]
--- Enumerable#grep -> [object]
--- Enumerable#inject(...) {...} -> object
--- String#+(...) -> String
--- String#capitalize! -> self | nil
--- String#casecmp -> Integer
--- String#center -> String
--- String#count -> Integer
--- String#to_f -> Float
--- Array#size -> Integer
--- Array#pop -> object
--- Array#join -> String
--- Array#flatten -> [object]

どうでしょう？ これで書けそうか、あるいはこんな問題がある、
俺の案を使え、などの意見を募集します。

# いまさら気付いたんですが、@paramとか @return って
# インスタンス変数とめちゃくちゃ衝突しますねえ……。
# まあ、メソッドのドキュメントでインスタンス変数に触れる
# ことも少ないか。既存のドキュメントで行頭から @ を
# 書いてるものはないみたいだし。

--
青木峰郎


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