Enhanced Rdoc for Array#fetch and Array#index (#3202)

* Enhanced Rdoc for Array#fetch and Array#index
* Couple of tweaks (per review) in Rdoc for Hash

2 files changed, 100 insertions, 46 deletions

diff --git a/array.c b/array.c
index 8f06c3caf5..45891370cf 100644
--- a/array.c
+++ b/array.c
@@ -1033,9 +1033,9 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary)
  *  or a single argument +0+,
  *  ignores the block and returns a new empty \Array:
  *
- *    a = Array.new(0) { |n| fail 'Cannot happen' }
+ *    a = Array.new(0) { |n| raise 'Cannot happen' }
  *    a # => []
- *    a = Array.new { |n| fail 'Cannot happen' }
+ *    a = Array.new { |n| raise 'Cannot happen' }
  *    a # => []
  *
  *  With a block and arguments +size+ and +default_value+,
@@ -1991,26 +1991,56 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary)
 
 /*
  *  call-seq:
- *     ary.fetch(index)                    -> obj
- *     ary.fetch(index, default)           -> obj
- *     ary.fetch(index) {|index| block}    -> obj
- *
- *  Tries to return the element at position +index+, but throws an IndexError
- *  exception if the referenced +index+ lies outside of the array bounds.  This
- *  error can be prevented by supplying a second argument, which will act as a
- *  +default+ value.
- *
- *  Alternatively, if a block is given it will only be executed when an
- *  invalid +index+ is referenced.
- *
- *  Negative values of +index+ count from the end of the array.
- *
- *     a = [ 11, 22, 33, 44 ]
- *     a.fetch(1)               #=> 22
- *     a.fetch(-1)              #=> 44
- *     a.fetch(4, 'cat')        #=> "cat"
- *     a.fetch(100) {|i| puts "#{i} is out of bounds"}
- *                              #=> "100 is out of bounds"
+ *    array.fetch(index) -> element
+ *    array.fetch(index, default_value) -> element
+ *    array.fetch(index) {|index| ... } -> element
+ *
+ *  Returns the element at offset  +index+.
+ *
+ *  Argument +index+ must be an
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]
+ *
+ *  ---
+ *
+ *  With the single argument +index+, returns the element at offset +index+:
+ *    a = [:foo, 'bar', baz = 2]
+ *    a.fetch(1) # => "bar"
+ *
+ *  If +index+ is negative, counts from the end of the array:
+ *    a = [:foo, 'bar', baz = 2]
+ *    a.fetch(-1) # => 2
+ *    a.fetch(-2) # => "bar"
+ *
+ *  ---
+ *
+ *  With arguments +index+ and +default_value+,
+ *  returns the element at offset +index+ if index is in range,
+ *  otherwise returns +default_value+:
+ *    a = [:foo, 'bar', baz = 2]
+ *    a.fetch(1, nil) # => "bar"
+ *    a.fetch(50, nil) # => nil
+ *
+ *  ---
+ *
+ *  With argument +index+ and a block,
+ *  returns the element at offset +index+ if index is in range
+ *  (and the block is not called); otherwise calls the block with index and returns its return value:
+ *
+ *    a = [:foo, 'bar', baz = 2]
+ *    a.fetch(1) { |index| raise 'Cannot happen' } # => "bar"
+ *    a.fetch(50) { |index| "Value for #{index}" } # => "Value for 50"
+ *
+ *  ---
+ *
+ *  Raises an exception if +index+ is not an \Integer-convertible object.
+ *    a = [:foo, 'bar', baz = 2]
+ *    # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    a.fetch(:foo)
+ *
+ *  Raises an exception if +index+ is out of range and neither default_value nor a block given:
+ *    a = [:foo, 'bar', baz = 2]
+ *    # Raises IndexError (index 50 outside of array bounds: -3...3):
+ *    a.fetch(50)
  */
 
 static VALUE
@@ -2043,30 +2073,54 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
 
 /*
  *  call-seq:
- *     ary.find_index(obj)             ->  int or nil
- *     ary.find_index {|item| block}  ->  int or nil
- *     ary.find_index                  ->  Enumerator
- *     ary.index(obj)             ->  int or nil
- *     ary.index {|item| block}   ->  int or nil
- *     ary.index                  ->  Enumerator
+ *    array.index(object) -> integer or nil
+ *    array.index {|element| ... } -> integer or nil
+ *    array.index -> new_enumerator
+ *    array.find_index(object) -> integer or nil
+ *    array.find_index {|element| ... } -> integer or nil
+ *    array.find_index -> new_enumerator
  *
- *  Returns the _index_ of the first object in +ary+ such that the object is
- *  <code>==</code> to +obj+.
+ *  Array#index is an alias for Array#find_index.
  *
- *  If a block is given instead of an argument, returns the _index_ of the
- *  first object for which the block returns +true+.  Returns +nil+ if no
- *  match is found.
+ *  ---
  *
- *  See also Array#rindex.
+ *  When argument +object+ is given but no block,
+ *  returns the index of the first element +element+
+ *  for which <tt>object == element</tt>:
+ *    a = [:foo, 'bar', baz = 2, 'bar']
+ *    a.index('bar') # => 1
  *
- *  An Enumerator is returned if neither a block nor argument is given.
+ *  Returns +nil+ if no such element found:
+ *    a = [:foo, 'bar', baz = 2]
+ *    a.index(:nosuch) # => nil
  *
- *     a = [ "a", "b", "c" ]
- *     a.index("b")              #=> 1
- *     a.index("z")              #=> nil
- *     a.index {|x| x == "b"}    #=> 1
+ *  ---
  *
- *  Array#index is an alias for Array#find_index.
+ *  When both argument +object+ and a block are given,
+ *  calls the block with each successive element;
+ *  returns the index of the first element for which the block returns a truthy value:
+ *    a = [:foo, 'bar', baz = 2, 'bar']
+ *    a.index { |element| element == 'bar' } # => 1
+ *
+ *  Returns +nil+ if the block never returns a truthy value:
+ *    a = [:foo, 'bar', baz = 2]
+ *    a.index { |element| element == :X } # => nil
+ *
+ *  ---
+ *
+ *  When neither an argument nor a block is given, returns a new Enumerator:
+ *    a = [:foo, 'bar', baz = 2]
+ *    e = a.index
+ *    e # => #<Enumerator: [:foo, "bar", 2]:index>
+ *    e.each { |element| element == 'bar' } # => 1
+ *
+ *  ---
+ *
+ *  When both an argument and a block given, gives a warning (warning: given block not used)
+ *  and ignores the block:
+ *    a = [:foo, 'bar', baz = 2, 'bar']
+ *    index = a.index('bar') { raise 'Cannot happen' }
+ *    index # => 1
  */
 
 static VALUE
diff --git a/hash.c b/hash.c
index 139b82279c..93fe10ea35 100644
--- a/hash.c
+++ b/hash.c
@@ -2226,7 +2226,7 @@ rb_hash_lookup(VALUE hash, VALUE key)
  *  * If +key+ is found, returns its associated value.
  *  * Otherwise, calls the block with +key+, and returns the block's return value.
  *      h = {foo: 0, bar: 1, baz: 2}
- *      h.fetch(:bar) { |key| fail 'Ignored'} # => 1
+ *      h.fetch(:bar) { |key| raise 'Ignored'} # => 1
  *      h.fetch(:nosuch) { |key| "Value for #{key}"} # => "Value for nosuch"
  *
  *  When both +default+ and a block are given:
@@ -2234,7 +2234,7 @@ rb_hash_lookup(VALUE hash, VALUE key)
  *  * If +key+ is found, returns its associated value.
  *  * Otherwise, calls the block with +key+, and returns the block's return value.
  *      h = {foo: 0, bar: 1, baz: 2}
- *      h.fetch(:bar, :default) { |key| fail 'Ignored'} # => 1
+ *      h.fetch(:bar, :default) { |key| raise 'Ignored'} # => 1
  *      h.fetch(:nosuch, :default) { |key| "Value for #{key}"} # => "Value for nosuch"
  *
  *  ---
@@ -2526,7 +2526,7 @@ rb_hash_delete(VALUE hash, VALUE key)
  *  If a block is given and +key+ is found, ignores the block,
  *  deletes the entry, and returns the associated value:
  *    h = {foo: 0, bar: 1, baz: 2}
- *    h.delete(:baz) { |key| fail 'Will never happen'} # => 2
+ *    h.delete(:baz) { |key| raise 'Will never happen'} # => 2
  *    h # => {:foo=>0, :bar=>1}
  *
  *  If a block is given and +key+ is not found,
@@ -4397,7 +4397,7 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash)
  *  Example:
  *    h = {foo: 0, bar: 1, baz: 2}
  *    h.merge # => {:foo=>0, :bar=>1, :baz=>2}
- *    h1 = h.merge! { |key, old_value, new_value| fail 'Cannot happen' }
+ *    h1 = h.merge! { |key, old_value, new_value| raise 'Cannot happen' }
  *    h1 # => {:foo=>0, :bar=>1, :baz=>2}
  *    h1.equal?(h) # => true # Identity check
  *
@@ -4547,7 +4547,7 @@ rb_hash_update_by(VALUE hash1, VALUE hash2, rb_hash_update_func *func)
  *    h1 = h.merge
  *    h1 # => {:foo=>0, :bar=>1, :baz=>2}
  *    h1.equal?(h) # => false # Identity check
- *    h2 = h.merge { |key, old_value, new_value| fail 'Cannot happen' }
+ *    h2 = h.merge { |key, old_value, new_value| raise 'Cannot happen' }
  *    h2 # => {:foo=>0, :bar=>1, :baz=>2}
  *    h2.equal?(h) # => false # Identity check
  *
@@ -5553,7 +5553,7 @@ env_delete(VALUE name)
  * If a block given and the environment variable exists,
  * deletes the environment variable and returns its value (ignoring the block):
  *   ENV['foo'] = '0'
- *   ENV.delete('foo') { |name| fail 'ignored' } # => "0"
+ *   ENV.delete('foo') { |name| raise 'ignored' } # => "0"
  * Raises an exception if +name+ is invalid.
  * See {Invalid Names and Values}[#class-ENV-label-Invalid+Names+and+Values].
  */