Enhanced RDoc for Enumerable (#4808)

#to_a
    #to_h
    #inject

enum.c

@@ -700,16 +700,13 @@ enum_flat_map(VALUE obj)
 
 /*
  *  call-seq:
- *     enum.to_a(*args)      -> array
+ *    to_a -> array
- *     enum.entries(*args)   -> array
  *
- *  Returns an array containing the items in <i>enum</i>.
+ *  Returns an array containing the items in +self+:
  *
- *     (1..7).to_a                       #=> [1, 2, 3, 4, 5, 6, 7]
+ *    (0..4).to_a # => [0, 1, 2, 3, 4]
- *     { 'a'=>1, 'b'=>2, 'c'=>3 }.to_a   #=> [["a", 1], ["b", 2], ["c", 3]]
  *
- *     require 'prime'
+ *  Enumerable#entries is an alias for Enumerable#to_a.
- *     Prime.entries 10                  #=> [2, 3, 5, 7]
  */
 static VALUE
 enum_to_a(int argc, VALUE *argv, VALUE obj)
@@ -749,20 +746,23 @@ enum_to_h_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash))
 
 /*
  *  call-seq:
- *     enum.to_h(*args)        -> hash
+ *    to_h -> hash
- *     enum.to_h(*args) {...}  -> hash
+ *    to_h {|element| ... }  -> hash
  *
- *  Returns the result of interpreting <i>enum</i> as a list of
+ *  When +self+ consists of 2-element arrays,
- *  <tt>[key, value]</tt> pairs.
+ *  returns a hash each of whose entries is the key-value pair
+ *  formed from one of those arrays:
  *
- *     %i[hello world].each_with_index.to_h
+ *    [[:foo, 0], [:bar, 1], [:baz, 2]].to_h # => {:foo=>0, :bar=>1, :baz=>2}
- *       # => {:hello => 0, :world => 1}
  *
- *  If a block is given, the results of the block on each element of
+ *  When a block is given, the block is called with each element of +self+;
- *  the enum will be used as pairs.
+ *  the block should return a 2-element array which becomes a key-value pair
+ *  in the returned hash:
  *
- *     (1..5).to_h {|x| [x, x ** 2]}
+ *    (0..3).to_h {|i| [i, i ** 2]} # => {0=>0, 1=>1, 2=>4, 3=>9}
- *       #=> {1=>1, 2=>4, 3=>9, 4=>16, 5=>25}
+ *
+ *  Raises an exception if an element of +self+ is not a 2-element array,
+ *  and a block is not passed.
  */
 
 static VALUE
@@ -871,14 +871,10 @@ ary_inject_op(VALUE ary, VALUE init, VALUE op)
 
 /*
  *  call-seq:
- *     enum.inject(initial, sym) -> obj
+ *     inject(symbol) -> obj
- *     enum.inject(sym)          -> obj
+ *     inject(initial_operand, symbol) -> obj
- *     enum.inject(initial) { |memo, obj| block }  -> obj
+ *     inject {|memo, element| ... } -> obj
- *     enum.inject          { |memo, obj| block }  -> obj
+ *     inject(initial_operand) {|memo, element| ... } -> obj
- *     enum.reduce(initial, sym) -> obj
- *     enum.reduce(sym)          -> obj
- *     enum.reduce(initial) { |memo, obj| block }  -> obj
- *     enum.reduce          { |memo, obj| block }  -> obj
  *
  *  Combines all elements of <i>enum</i> by applying a binary
  *  operation, specified by a block or a symbol that names a
@@ -913,7 +909,6 @@ ary_inject_op(VALUE ary, VALUE init, VALUE op)
  *        memo.length > word.length ? memo : word
  *     end
  *     longest                                        #=> "sheep"
- *
  */
 static VALUE
 enum_inject(int argc, VALUE *argv, VALUE obj)