青木です。

@param と @return について決心がつきました。

== @param について

引数がある場合、@param は必須とします。どんなに冗長に思え 
ても
@param は書いてください。結果として本文の繰り返しになっても
構いません。

同時に、@param を単に「引数の説明」と言っていましたが、もう
少し役割を明確化します。@param では引数の意味と制約条件を
書いてください。例えば String#index(pattern, pos = 0) の  
pos なら
「意味」とは「検索を開始する位置」であり、制約条件は「整数」
です。制約条件は「型」とほぼ同じです。

例に挙げられた FalseClass#& にしても、例えば仕様によっては
false & "string" がエラーになる可能性もあるわけです。しかし現在
の Ruby ではエラーになりません。それなら、任意のオブジェクト
が受け付けられるのだということを明示的に書くべきです。

類似の例としては、"string" == [1] が昔はエラーになってたけど
いまはエラーにならない、なんてのも挙げられます。そういう場合、
任意のオブジェクトが受けつけられるのだということを明示的に
記述してください。

== @return について

@return は、第一段落で十分に返り値の意味を記述できなかった
ときに補助として使ってください。@return は省略可能とします。

ただし、返り値の制約条件 (型) は必須とします。前の 
メールで述
べた「->」の記法を使って、メソッドシグネチャと同じ行に記述
してください。


つまり、引数は意味と制約条件を両方 @param で書くのに対して、
返り値は意味を @return で、型を -> で記述するという 
ことです。
そして型は省略してはいけないので @param は省略できないが、
@return は省略してもよい、ということです。

こちらでもこれから実装してみます。

--
青木峰郎


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