Bug #2219: Rubyで使われる記号の意味
http://redmine.ruby-lang.org/issues/show/2219

起票者: 5 5
ステータス: Open, 優先度: Low
カテゴリ: doc
reporter: 5.5, ruby_version: 1.8, 1.9

「Rubyで使われる記号の意味」へのバグ報告・追加提案です。

■ #

◇ shebang だけでなく，マジックコメントも入れたほうが良いと思います（Ruby 1.9 版）

◇ Range#each

説明が，
 説明文の中でのみ使われます。Ruby言語の要素ではありません。クラスのインスタンスメソッドであることを簡単に表示するための表記法です。クラスメソッドは「Range.new」のように「.」でつなぎます。
となっています。

この最後の文「クラスメソッドは…」を削除するか，直前に「一方、」をつけたほうがよいと思います。

■ %

◇ 10 % 3

説明文の「余剰」は「剰余」でしょう。

◇ %r{/etc/httpd/logs$} や %w[foo bar baz] ・・ %<文字><区切り文字><文字列><区切り文字>

区切り文字が括弧類の場合は対応する括弧を，そうでない場合は同じ文字を使うことを書いてもいいかと思います。
（例：%r!foo/bar!）

◇ フォーマット指定子についても書くとよいと思います。

■ &

◇ def xxx(&yyy) 

メソッド定義の場合だけでなく，メソッド呼び出しの場合（Proc オブジェクトをブロックとして与えたい場合）も書くべきだと思います。
参考ページは「メソッド呼び出し」で。

◇ xxx && yyy

実行例に，
 3=>true , 5=>true なので右の値を返す。
と説明が付いていますが，3=>true などという表現は変ではないでしょうか。

3 と true の間に，〈いずれも真を表す〉という以上の関係は無いと思います。

ここは
 3 も 5 も真なので右の値を返す。
とかで如何でしょうか。

■ |

◇ a ||= xxx

「a が nil か false なら」は正しくは「a が偽か未定義なら」ではないでしょうか。

◇ 3 | 5

説明に，
 二進数で 0011 | 01010 => 0111
とありますが，5 の 2 進数表記は 01010 でなく 0101 です。

◇ 3 || 5
「true || true なので」はおかしいと思います。
「3 が真なので」で如何でしょうか。

■ -

◇ 3 * (-5)
説明に，
 負数を表す、単項演算子-。
とありますが，このマイナスあくまで演算子であって，負数を表すものではありません。

以下の例を見れば，得られたオブジェクトが必ずしも負数を表現していないことが分かります。
 a=-3
 p -a # => 3

同様に，単項演算子の「+」も，「正の数を表す」とは限りません。

なお，「混乱を避けるため適時()でくくるとよい。」の「適時」は「適宜」でしょうか。

■ *

◇ def xxx(*yy)

メソッド定義の場合だけでなく，メソッド呼び出しでも展開できることを書くべきだと思います。

◇ /xx*/

説明に，
 正規表現の、直前の表現の 0 回以上の繰り返し。できるだけ
長くマッチしようとする。
とありますが，ここでは「〜の 0 回以上の繰り返し。」まででいいと思います。

できるだけ長くマッチしようとするかどうかは，後ろの「?」の有無によって異なるので。

■ :

◇ ハッシュの JSON 風表記 {a: 3, b: 4} に使われる「:」も書くとよいと思います（Ruby 1.9 版）。

■ .
◇ Range.new
説明が，
    オブジェクトのメソッドだが、説明文の中では特にクラスのクラスメソッド／モジュールのモジュールメソッドを示すことに使われます。インスタンスメソッドは「Range#each」のように「#」でつなぎます。
となっています。
最後の文「インスタンスメソ…」は削除するか，直前に「一方、」を付けたほうがよいと思います。

◇ モジュール関数を表す「Kernel.#require」といった表記についても書いたほうがよいと思います。

■ ,

◇ 以下のものについても書くとよいと思います。

* メソッド引数の区切り
* ハッシュリテラルの要素の区切り
* ブロックパラメーターの区切り
* 多重代入の右辺

■ <

◇ 3 << 1

説明に
 シフト演算子。または類似のメソッド。
とありますが，Array#<< はシフト演算子や類似のメソッドではなく，末尾に追加するメソッドなので，それを追加すると良いと思います。

■ >

◇ Ruby 1.9 で導入された「->」も入れてほしいです。

■ =

◇ xxx.a = 12

「=」もメソッド名の一部であることを追記するとよいと思います。（「def xx=」には書いていますが）

◇ def xx=

説明が，
 この場合の「=」はメソッド名の一部分です。このタイプの名前のメソッドを定義すると、同時に「=」演算子を定義することになります。
となっていますが，後半は本当でしょうか？

■ ~

◇ '%04b %04b' % [3, ~ 3]) #=> "0011 1100"

閉じ括弧は不要では？

■ @

◇ def +@ または def -@

説明が
 単項演算子 +X や -X を再定義するときの表記法。
となっていますが，もともと無いものを定義してもよいので，「再定義するときの」ではなく「定義するときの」がよいと思います。

■ [ ]

◇ []= についても書くとよいと思います。

■ ( )

◇ (true and false)

旧リファレンスで，
 p((true and false)) #=> false
となっていたのが誤って
 (true and false)
になってしまったようです。
これにより，説明文の意味が分からなくなってしまっています。

■ _

◇ 一部の擬似変数（__FILE__，__method__ など）の名前に使われていることを書いてもいいと思います。

■ ;

◇ ブロックローカル変数の宣言についても書くべきだと思います（Ruby 1.9 版）


----------------------------------------
http://redmine.ruby-lang.org

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