こんにちは。
okkez です。

07/08/12 に sheepman<sheepman@s...> さんは書きました:
> こんばんは、sheepman です。
>
> メソッドの説明中の例の位置に関してです。
>
> http://doc.loveruby.net/wiki/HowToWriteMethodEntry.html
>
> で、例は最後にまとめるということになっていることに最近気がつきました(笑)。
> これだと、例とそれを説明している文章が離れてしまいます。例の位置はもう少し
> 柔軟に対処しちゃいけないでしょうか。
>
> 現在の仕様は UNIX の man を踏襲したものだと思います。
> man の場合は、
>  * そもそも例の量が少ないので例と説明との対応を気にするほどではない
>  * C 言語だとひとつの例の行数が多くなってしまうために、文中に挿入することが難しい
> という理由があって、後ろにまとめているのだと思います。
>
> Ruby のリファレンスの場合は、例が割と多くて、個々の例の行数は短いので
> 説明の本文の間に入れてもおかしくないと思うのですが。どうでしょうか。

こんな感じにすると統一性も出ると思うのですがいかがでしょうか？

--- method_name(param_name) -> return_value
短い説明短い説明短い説明短い説明短い説明短い説明。
# 必須

必要なら詳しい説明。必要なら詳しい説明。必要なら詳しい説明。
必要なら詳しい説明。必要なら詳しい説明。必要なら詳しい説明。
必要なら詳しい説明。必要なら詳しい説明。必要なら詳しい説明。
# ここには例は書かない。省略可能。

@param param_name param_name の説明
# 必須

@return return_value の説明
# 省略可能

@raise StandardError こんなことをした場合に発生します。

例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。
例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。
例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。

  コード例。コード例。コード例。コード例。コード例。コード例。
  コード例。コード例。コード例。コード例。コード例。コード例。
  コード例。コード例。コード例。コード例。コード例。コード例。

例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。
例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。
例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。

  コード例。コード例。コード例。コード例。コード例。コード例。
  コード例。コード例。コード例。コード例。コード例。コード例。
  コード例。コード例。コード例。コード例。コード例。コード例。

例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。
例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。
例を伴う詳しい説明。例を伴う詳しい説明。例を伴う詳しい説明。

  コード例。コード例。コード例。コード例。コード例。コード例。
  コード例。コード例。コード例。コード例。コード例。コード例。
  コード例。コード例。コード例。コード例。コード例。コード例。

-----

もしくは「(省略可能な)詳しい説明」と @param などの順番を入れ換えてもいいかなぁと思います。
サンプルコードとその説明が離れるのが嬉しくないのは同意です。
Module なんかだとサンプルコードとその説明の対応を気にしないと読みづらいはずなので
どうにかしたいな、とは思います。

-- 
okkez
okkez000@g...

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