[ci skip] Rdoc enhancements for Array (#3063)

* Per @nobu review

* Rdoc enhancements for Array

* Responses to review

1 files changed, 191 insertions, 83 deletions

diff --git a/array.c b/array.c
index dbb40db508..262d5213af 100644
--- a/array.c
+++ b/array.c
@@ -935,21 +935,26 @@ rb_check_to_array(VALUE ary)
 
 /*
  *  call-seq:
- *     Array.try_convert(obj) -> array or nil
+ *    Array.try_convert(obj) -> new_array or nil
  *
- *  Tries to convert +obj+ into an array, using the +to_ary+ method.  Returns
- *  the converted array or +nil+ if +obj+ cannot be converted.
- *  This method can be used to check if an argument is an array.
+ *  Tries to convert +obj+ to an \Array.
  *
- *     Array.try_convert([1])   #=> [1]
- *     Array.try_convert("1")   #=> nil
+ *  When +obj+ is an
+ *  {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]
+ *  (implements +to_ary+),
+ *  returns the \Array object created by converting it:
  *
- *     if tmp = Array.try_convert(arg)
- *       # the argument is an array
- *     elsif tmp = String.try_convert(arg)
- *       # the argument is a string
- *     end
+ *    class ToAryReturnsArray < Set
+ *      def to_ary
+ *        self.to_a
+ *      end
+ *    end
+ *    as = ToAryReturnsArray.new([:foo, :bar, :baz])
+ *    Array.try_convert(as) # => [:foo, :bar, :baz]
  *
+ *  Returns +nil+ if +obj+ is not \Array-convertible:
+ *
+ *    Array.try_convert(:foo) # => nil
  */
 
 static VALUE
@@ -960,58 +965,96 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary)
 
 /*
  *  call-seq:
- *     Array.new(size=0, default=nil)
- *     Array.new(array)
- *     Array.new(size) {|index| block }
+ *    Array.new -> new_empty_array
+ *    Array.new(array) -> new_array
+ *    Array.new(size) -> new_array
+ *    Array.new(size, default_value) -> new_array
+ *    Array.new(size) {|index| ... } -> new_array
+ *
+ *  Returns a new \Array.
+ *
+ *  Argument +array+, if given, must be an
+ *  {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]
+ *  (implements +to_ary+).
+ *
+ *  Argument +size+, if given must be an
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]
+ *  (implements +to_int+).
+ *
+ *  Argument +default_value+ may be any object.
  *
- *  Returns a new array.
+ *  ---
  *
- *  In the first form, if no arguments are sent, the new array will be empty.
- *  When a +size+ and an optional +default+ are sent, an array is created with
- *  +size+ copies of +default+.  Take notice that all elements will reference the
- *  same object +default+.
+ *  With no block and no arguments, returns a new empty \Array object:
  *
- *  The second form creates a copy of the array passed as a parameter (the
- *  array is generated by calling to_ary on the parameter).
+ *    a = Array.new
+ *    a # => []
  *
- *    first_array = ["Matz", "Guido"]
+ *  With no block and a single argument +array+,
+ *  returns a new \Array formed from +array+:
  *
- *    second_array = Array.new(first_array) #=> ["Matz", "Guido"]
+ *    a = Array.new([:foo, 'bar', 2])
+ *    a.class # => Array
+ *    a # => [:foo, "bar", 2]
  *
- *    first_array.equal? second_array       #=> false
+ *  With no block and a single argument +size+,
+ *  returns a new \Array of the given size
+ *  whose elements are all +nil+:
  *
- *  In the last form, an array of the given size is created.  Each element in
- *  this array is created by passing the element's index to the given block
- *  and storing the return value.
+ *    a = Array.new(0)
+ *    a # => []
+ *    a = Array.new(3)
+ *    a # => [nil, nil, nil]
  *
- *    Array.new(3) {|index| index ** 2}
- *    # => [0, 1, 4]
+ *  With no block and arguments +size+ and  +default_value+,
+ *  returns an \Array of the given size;
+ *  each element is that same +default_value+:
  *
- *  == Common gotchas
+ *    a = Array.new(3, 'x')
+ *    a # => ['x', 'x', 'x']
+ *    a[1].equal?(a[0]) # => true # Identity check.
+ *    a[2].equal?(a[0]) # => true # Identity check.
  *
- *  When sending the second parameter, the same object will be used as the
- *  value for all the array elements:
+ *  With a block and argument +size+,
+ *  returns an \Array of the given size;
+ *  the block is called with each successive integer +index+;
+ *  the element for that +index+ is the return value from the block:
  *
- *     a = Array.new(2, Hash.new)
- *     # => [{}, {}]
+ *    a = Array.new(3) { |index| "Element #{index}" }
+ *    a # => ["Element 0", "Element 1", "Element 2"]
  *
- *     a[0]['cat'] = 'feline'
- *     a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]
+ *  With a block and no argument,
+ *  or a single argument +0+,
+ *  ignores the block and returns a new empty \Array:
  *
- *     a[1]['cat'] = 'Felix'
- *     a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]
+ *    a = Array.new(0) { |n| fail 'Cannot happen' }
+ *    a # => []
+ *    a = Array.new { |n| fail 'Cannot happen' }
+ *    a # => []
  *
- *  Since all the Array elements store the same hash, changes to one of them
- *  will affect them all.
+ *  With a block and arguments +size+ and +default_value+,
+ *  gives a warning message
+ *  ('warning: block supersedes default value argument'),
+ *  and assigns elements from the block's return values:
  *
- *  If multiple copies are what you want, you should use the block
- *  version which uses the result of that block each time an element
- *  of the array needs to be initialized:
+ *    Array.new(4, :default) {} # => [nil, nil, nil, nil]
  *
- *     a = Array.new(2) {Hash.new}
- *     a[0]['cat'] = 'feline'
- *     a # => [{"cat"=>"feline"}, {}]
+ *  ---
  *
+ *  Raises an exception if +size+ is a negative integer:
+ *
+ *    # Raises ArgumentError (negative array size):
+ *    Array.new(-1)
+ *    # Raises ArgumentError (negative array size):
+ *    Array.new(-1, :default)
+ *    # Raises ArgumentError (negative array size):
+ *    Array.new(-1) { |n| }
+ *
+ *  Raises an exception if the single argument is neither \Array-convertible
+ *  nor \Integer-convertible.
+ *
+ *    # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    Array.new(:foo)
  */
 
 static VALUE
@@ -1193,18 +1236,20 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos
 
 /*
  *  call-seq:
- *     ary << obj            -> ary
+ *    ary << obj -> self
  *
- *  Append---Pushes the given object on to the end of this array. This
- *  expression returns the array itself, so several appends
- *  may be chained together.
+ *  Appends +obj+ to +ary+; returns +self+:
  *
- *     a = [ 1, 2 ]
- *     a << "c" << "d" << [ 3, 4 ]
- *             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
- *     a
- *             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a << :baz
+ *    a1 # => [:foo, "bar", 2, :baz]
+ *    a1.equal?(a) # => true
  *
+ *  Appends +obj+ as one element, even if it is another \Array:
+ *
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a << [3, 4] # =>
+ *    a1 # => [:foo, "bar", 2, [3, 4]]
  */
 
 VALUE
@@ -1232,19 +1277,21 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len)
 
 /*
  *  call-seq:
- *     ary.push(obj, ...)    -> ary
- *     ary.append(obj, ...)  -> ary
+ *    ary.push(*objects)    -> self
+ *    ary.append(*objects)  -> self
  *
- *  Append --- Pushes the given object(s) on to the end of this array. This
- *  expression returns the array itself, so several appends
- *  may be chained together. See also Array#pop for the opposite
- *  effect.
+ *  Appends each argument in +objects+ to the array;  returns +self+:
  *
- *     a = [ "a", "b", "c" ]
- *     a.push("d", "e", "f")
- *             #=> ["a", "b", "c", "d", "e", "f"]
- *     [1, 2, 3].push(4).push(5)
- *             #=> [1, 2, 3, 4, 5]
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.push(:baz, :bat)
+ *    a1 # => [:foo, "bar", 2, :baz, :bat]
+ *    a1.equal?(a) # => true
+ *
+ *  Appends each argument as one element, even if it is another \Array:
+ *
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.push([:baz, :bat], [:bam, :bad])
+ *    a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
  */
 
 static VALUE
@@ -1274,20 +1321,62 @@ rb_ary_pop(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.pop    -> obj or nil
- *     ary.pop(n) -> new_ary
+ *    ary.pop -> obj or nil
+ *    ary.pop(n) -> new_array
  *
- *  Removes the last element from +self+ and returns it, or
- *  +nil+ if the array is empty.
+ *  Removes and returns trailing elements from the array.
  *
- *  If a number +n+ is given, returns an array of the last +n+ elements
- *  (or less) just like <code>array.slice!(-n, n)</code> does. See also
- *  Array#push for the opposite effect.
+ *  Argument +n+, if given, must be an
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]
+ *  (implements +to_int+).
  *
- *     a = [ "a", "b", "c", "d" ]
- *     a.pop     #=> "d"
- *     a.pop(2)  #=> ["b", "c"]
- *     a         #=> ["a"]
+ *  ---
+ *
+ *  When no argument is given and the array is not empty,
+ *  removes and returns the last element in the array:
+ *
+ *    a = [:foo, 'bar', 2]
+ *    a.pop # => 2
+ *    a # => [:foo, "bar"]
+ *
+ *  Returns +nil+ if the array is empty:
+ *
+ *    a = []
+ *    a.pop # => nil
+ *
+ *  ---
+ *
+ *  When argument +n+ is given and is non-negative and in range,
+ *  removes and returns the last +n+ elements in a new \Array:
+ *
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.pop(2)
+ *    a1 # => ["bar", 2]
+ *    a # => [:foo]
+ *    a.pop(0) # => []
+ *
+ *  If +n+ is positive and out of range,
+ *  removes and returns all elements:
+ *
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.pop(50)
+ *    a1 # => [:foo, "bar", 2]
+ *    a # => []
+ *    a.pop(1) # => []
+ *
+ *  ---
+ *
+ *  Raises an exception if +n+ is negative:
+ *
+ *    a = [:foo, 'bar', 2]
+ *    # Raises ArgumentError (negative array size):
+ *    a1 = a.pop(-1)
+ *
+ *  Raises an exception if +n+ is not \Integer-convertible (implements +to_int+).
+ *
+ *    a = [:foo, 'bar', 2]
+ *    # Raises TypeError (no implicit conversion of String into Integer):
+ *    a1 = a.pop('x')
  */
 
 static VALUE
@@ -6621,12 +6710,32 @@ rb_ary_deconstruct(VALUE ary)
 }
 
 /*
- *  Arrays are ordered, integer-indexed collections of any object.
+ *  An \Array is an ordered, integer-indexed collection of objects,
+ *  called _elements_.  Any object may be an \Array element.
+ *
+ *  == \Array Indexes
+ *
+ *  \Array indexing starts at 0, as in C or Java.
  *
- *  Array indexing starts at 0, as in C or Java.  A negative index is assumed
- *  to be relative to the end of the array---that is, an index of -1 indicates
- *  the last element of the array, -2 is the next to last element in the
- *  array, and so on.
+ *  A positive index is an offset from the first element:
+ *  - Index 0 indicates the first element.
+ *  - Index 1 indicates the second element.
+ *  - ...
+ *
+ *  A negative index is an offset, backwards, from the end of the array:
+ *  - Index -1 indicates the last element.
+ *  - Index -2 indicates the next-to-last element.
+ *  - ...
+ *
+ *  A non-negative index is <i>in range</i> if it is smaller than
+ *  the size of the array.  For a 3-element array:
+ *  - Indexes 0 through 2 are in range.
+ *  - Index 3 is out of range.
+ *
+ *  A negative index is <i>in range</i> if its absolute value is
+ *  not larger than the size of the array.  For a 3-element array:
+ *  - Indexes -1 through -3 are in range.
+ *  - Index -4 is out of range.
  *
  *  == Creating Arrays
  *
@@ -6855,7 +6964,6 @@ rb_ary_deconstruct(VALUE ary)
  *     arr = [1, 2, 3, 4, 5, 6]
  *     arr.keep_if {|a| a < 4}   #=> [1, 2, 3]
  *     arr                       #=> [1, 2, 3]
- *
  */
 
 void