Enhanced RDoc for Array (#3372)

Merged-By: marcandre <github@marc-andre.ca>

array.c

@@ -6706,31 +6706,41 @@ push_value(st_data_t key, st_data_t val, st_data_t ary)
 
 /*
  *  call-seq:
- *     ary.uniq!                -> ary or nil
+ *    array.uniq! -> self or nil
- *     ary.uniq! {|item| ...}   -> ary or nil
+ *    array.uniq! {|element| ... } -> self or nil
  *
- *  Removes duplicate elements from +self+.
+ *  Removes duplicate elements from +self+, the first occurrence always being retained;
+ *  returns +self+ if any elements removed, +nil+ otherwise.
  *
- *  If a block is given, it will use the return value of the block for
+ *  ---
- *  comparison.
  *
- *  It compares values using their #hash and #eql? methods for efficiency.
+ *  With no block given, identifies and removes elements using method <tt>eql?</tt>
+ *  to compare.
  *
- *  +self+ is traversed in order, and the first occurrence is kept.
+ *  Returns +self+ if any elements removed:
+ *    a = [0, 0, 1, 1, 2, 2]
+ *    a1 = a.uniq!
+ *    a1 # => [0, 1, 2]
+ *    a1.equal?(a) # => true # Returned self
  *
- *  Returns +nil+ if no changes are made (that is, no duplicates are found).
+ *  Returns +nil+ if no elements removed:
+ *    [0, 1, 2].uniq! # => nil
  *
- *     a = [ "a", "a", "b", "b", "c" ]
+ *  ---
- *     a.uniq!   # => ["a", "b", "c"]
  *
- *     b = [ "a", "b", "c" ]
+ *  With a block given, calls the block for each element;
- *     b.uniq!   # => nil
+ *  identifies (using method <tt>eql?</tt>) and removes
+ *  elements for which the block returns duplicate values.
  *
- *     c = [["student","sam"], ["student","george"], ["teacher","matz"]]
+ *  Returns +self+ if any elements removed:
- *     c.uniq! {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]
+ *    a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
+ *    a1 = a.uniq! {|element| element.size }
+ *    a1 # => ['a', 'aa', 'aaa']
+ *    a1.equal?(a) # => true # Returned self
  *
+ *  Returns +nil+ if no elements removed:
+ *    a.uniq! {|element| element.size } # => nil
  */
-
 static VALUE
 rb_ary_uniq_bang(VALUE ary)
 {
@@ -6764,23 +6774,22 @@ rb_ary_uniq_bang(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.uniq                -> new_ary
+ *    array.uniq -> new_array
- *     ary.uniq {|item| ...}   -> new_ary
+ *    array.uniq {|element| ... } -> new_array
  *
- *  Returns a new array by removing duplicate values in +self+.
+ *  Returns a new \Array containing those elements from +self+ that are not duplicates,
+ *  the first occurrence always being retained.
  *
- *  If a block is given, it will use the return value of the block for comparison.
+ *  With no block given, identifies and omits duplicates using method <tt>eql?</tt>
- *
+ *  to compare.
- *  It compares values using their #hash and #eql? methods for efficiency.
+ *    a = [0, 0, 1, 1, 2, 2]
- *
+ *    a.uniq # => [0, 1, 2]
- *  +self+ is traversed in order, and the first occurrence is kept.
- *
- *     a = [ "a", "a", "b", "b", "c" ]
- *     a.uniq   # => ["a", "b", "c"]
- *
- *     b = [["student","sam"], ["student","george"], ["teacher","matz"]]
- *     b.uniq {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]
  *
+ *  With a block given, calls the block for each element;
+ *  identifies (using method <tt>eql?</tt>) and omits duplicate values,
+ *  that is, those elements for which the block returns the same value:
+ *    a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
+ *    a.uniq { |element| element.size } # => ["a", "aa", "aaa"]
  */
 
 static VALUE
@@ -6810,14 +6819,17 @@ rb_ary_uniq(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.compact!    -> ary  or  nil
+ *    array.compact! -> self or nil
  *
- *  Removes +nil+ elements from the array.
+ *  Removes all +nil+ elements from +self+.
  *
- *  Returns +nil+ if no changes were made, otherwise returns the array.
+ *  Returns +self+ if any elements removed:
+ *    a = [nil, 0, nil, 1, nil, 2, nil]
+ *    a1 = a.compact! # => [0, 1, 2]
+ *    a1.equal?(a) # => true # Returned self
  *
- *     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
+ *  Returns +nil+ if no elements removed:
- *     [ "a", "b", "c" ].compact!           #=> nil
+ *    [0, 1, 2].compact! # => nil
  */
 
 static VALUE
@@ -6845,12 +6857,11 @@ rb_ary_compact_bang(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.compact     -> new_ary
+ *    array.compact -> new_array
  *
- *  Returns a copy of +self+ with all +nil+ elements removed.
+ *  Returns a new \Array containing all non-+nil+ elements from +self+:
- *
+ *    a = [nil, 0, nil, 1, nil, 2, nil]
- *     [ "a", nil, "b", nil, "c", nil ].compact
+ *    a.compact # => [0, 1, 2]
- *                       #=> [ "a", "b", "c" ]
  */
 
 static VALUE
@@ -6863,23 +6874,26 @@ rb_ary_compact(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.count                   -> int
+ *    array.count -> an_integer
- *     ary.count(obj)              -> int
+ *    array.count(obj) -> an_integer
- *     ary.count {|item| block}    -> int
+ *    array.count {|element| ... } -> an_integer
  *
- *  Returns the number of elements.
+ *  Returns a count of specified elements.
  *
- *  If an argument is given, counts the number of elements which equal +obj+
+ *  With no argument and no block, returns the count of all elements:
- *  using <code>==</code>.
+ *    [0, 1, 2].count # => 3
+ *    [].count # => 0
  *
- *  If a block is given, counts the number of elements for which the block
+ *  With argument +obj+, returns the count of elements <tt>eql?</tt> to +obj+:
- *  returns a true value.
+ *    [0, 1, 2, 0].count(0) # => 2
+ *    [0, 1, 2].count(3) # => 0
  *
- *     ary = [1, 2, 4, 2]
+ *  With no argument and a block given, calls the block with each element;
- *     ary.count                  #=> 4
+ *  returns the count of elements for which the block returns a truthy value:
- *     ary.count(2)               #=> 2
+ *    [0, 1, 2, 3].count {|element| element > 1} # => 2
- *     ary.count {|x| x%2 == 0}   #=> 3
  *
+ *  With argument +obj+ and a block given, issues a warning, ignores the block,
+ *  and returns the count of elements <tt>eql?</tt> to +obj+:
  */
 
 static VALUE
@@ -6998,22 +7012,47 @@ flatten(VALUE ary, int level)
 
 /*
  *  call-seq:
- *     ary.flatten!        -> ary or nil
+ *    array.flatten! -> self or nil
- *     ary.flatten!(level) -> ary or nil
+ *    array.flatten!(level) -> self or nil
  *
- *  Flattens +self+ in place.
+ *  Replaces each nested \Array in +self+ with the elements from that \Array;
+ *  returns +self+ if any changes, +nil+ otherwise.
  *
- *  Returns +nil+ if no modifications were made (i.e., the array contains no
+ *  Argument +level+, if given, must be an
- *  subarrays.)
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
  *
- *  The optional +level+ argument determines the level of recursion to flatten.
+ *  With non-negative argument +level+, flattens recursively through +level+ levels:
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a1 = a.flatten!(1)
+ *    a1 # => [0, 1, [2, 3], 4, 5]
+ *    a1.equal?(a) # => true # Returned self
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
+ *    [0, 1, 2].flatten!(1) # => nil
  *
- *     a = [ 1, 2, [3, [4, 5] ] ]
+ *  With no argument,  or with negative argument +level+, flattens all levels:
- *     a.flatten!   #=> [1, 2, 3, 4, 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
- *     a.flatten!   #=> nil
+ *    a.flatten! # => [0, 1, 2, 3, 4, 5]
- *     a            #=> [1, 2, 3, 4, 5]
+ *    [0, 1, 2].flatten! # => nil
- *     a = [ 1, 2, [3, [4, 5] ] ]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
- *     a.flatten!(1) #=> [1, 2, 3, [4, 5]]
+ *    a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
+ *    [0, 1, 2].flatten!(-1) # => nil
+ *
+ *  ---
+ *
+ *  Raises an exception if +level+ is not an Integer-convertible object:
+ *     # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    [].flatten!(:foo)
+ *
+ *  Raises an exception if +self+ contains a circular reference:
+ *    a = []
+ *    a.push([a, a])
+ *    # Raises ArgumentError (tried to flatten recursive array):
+ *    a.flatten!
  */
 
 static VALUE
@@ -7040,24 +7079,47 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
 
 /*
  *  call-seq:
- *     ary.flatten -> new_ary
+ *    array.flatten -> new_array
- *     ary.flatten(level) -> new_ary
+ *    array.flatten(level) -> new_array
  *
- *  Returns a new array that is a one-dimensional flattening of +self+
+ *  Returns a new \Array that is a recursive flattening of +self+:
- *  (recursively).
+ *  - Each non-Array element is unchanged.
+ *  - Each \Array is replaced by its individual elements.
  *
- *  That is, for every element that is an array, extract its elements into
+ *  Argument +level+, if given, must be
- *  the new array.
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
  *
- *  The optional +level+ argument determines the level of recursion to
+ *  With non-negative argument +level+, flattens recursively through +level+ levels:
- *  flatten.
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten(0) # => [0, [1, [2, 3], 4], 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten(1) # => [0, 1, [2, 3], 4, 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten(2) # => [0, 1, 2, 3, 4, 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten(3) # => [0, 1, 2, 3, 4, 5]
  *
- *     s = [ 1, 2, 3 ]           #=> [1, 2, 3]
+ *  With no argument, or with negative argument +level+, flattens all levels:
- *     t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
- *     a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
+ *    a.flatten # => [0, 1, 2, 3, 4, 5]
- *     a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ *    [0, 1, 2].flatten # => [0, 1, 2]
- *     a = [ 1, 2, [3, [4, 5] ] ]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
- *     a.flatten(1)              #=> [1, 2, 3, [4, 5]]
+ *    a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
+ *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+ *    a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
+ *    [0, 1, 2].flatten(-1) # => [0, 1, 2]
+ *
+ *  ---
+ *
+ *  Raises an exception if +level+ is not an Integer-convertible object:
+ *    # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    [].flatten(:foo)
+ *
+ *  Raises an exception if +self+ contains a circular reference:
+ *    a = []
+ *    a.push([a, a])
+ *    # Raises ArgumentError (tried to flatten recursive array):
+ *    a.flatten
  */
 
 static VALUE