merge revisions r33453, r37542:

    * array.c: rdoc fix and improvements

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_9_3@37544 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 67 insertions, 41 deletions

diff --git a/array.c b/array.c
index 64647c3044..e427cb3320 100644
--- a/array.c
+++ b/array.c
@@ -478,10 +478,9 @@ rb_check_array_type(VALUE ary)
  *  call-seq:
  *     Array.try_convert(obj) -> array or nil
  *
- *  Try to convert <i>obj</i> into an array, using +to_ary+ method.
- *  Returns converted array or +nil+ if <i>obj</i> cannot be converted
- *  for any reason. This method can be used to check if an argument is an
- *  array.
+ *  Tries to convert +obj+ into an array, using +to_ary+ method.  Returns the
+ *  converted array or +nil+ if +obj+ cannot be converted for any reason.
+ *  This method can be used to check if an argument is an array.
  *
  *     Array.try_convert([1])   #=> [1]
  *     Array.try_convert("1")   #=> nil
@@ -506,36 +505,54 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary)
  *     Array.new(array)
  *     Array.new(size) {|index| block }
  *
- *  Returns a new array. In the first form, the new array is
- *  empty. In the second it is created with _size_ copies of _obj_
- *  (that is, _size_ references to the same
- *  _obj_). The third form creates a copy of the array
- *  passed as a parameter (the array is generated by calling
- *  to_ary  on the parameter). In the last form, an array
- *  of the given size is created. Each element in this array is
- *  calculated by passing the element's index to the given block and
- *  storing the return value.
- *
- *     Array.new
- *     Array.new(2)
- *     Array.new(5, "A")
- *
- *     # only one copy of the object is created
+ *  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 +obj+ are sent, an array is created with
+ *  +size+ copies of +obj+.  Take notice that all elements will reference the
+ *  same object +obj+.
+ *
+ *  The second form creates a copy of the array passed as a parameter (the
+ *  array is generated by calling to_ary on the parameter).
+ *
+ *    first_array = ["Matz", "Guido"]
+ *
+ *    second_array = Array.new(first_array) #=> ["Matz", "Guido"]
+ *
+ *    first_array.equal? second_array       #=> false
+ *
+ *  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.
+ *
+ *    Array.new(3){ |index| index ** 2 }
+ *    # => [0, 1, 4]
+ *
+ *  == Common gotchas
+ *
+ *  When sending the second parameter, the same object will be used as the
+ *  value for all the array elements:
+ *
  *     a = Array.new(2, Hash.new)
+ *     # => [{}, {}]
+ *
  *     a[0]['cat'] = 'feline'
- *     a
+ *     a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]
+ *
  *     a[1]['cat'] = 'Felix'
- *     a
+ *     a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]
+ *
+ *  Since all the Array elements store the same hash, changes to one of them
+ *  will affect them all.
+ *
+ *  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:
  *
- *     # here multiple copies are created
  *     a = Array.new(2) { Hash.new }
  *     a[0]['cat'] = 'feline'
- *     a
- *
- *     squares = Array.new(5) {|i| i*i}
- *     squares
+ *     a # => [{"cat"=>"feline"}, {}]
  *
- *     copy = Array.new(squares)
  */
 
 static VALUE
@@ -1208,9 +1225,9 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary)
  *  If neither block nor argument is given, an enumerator is returned instead.
  *
  *     a = [ "a", "b", "b", "b", "c" ]
- *     a.rindex("b")        #=> 3
- *     a.rindex("z")        #=> nil
- *     a.rindex{|x|x=="b"}  #=> 3
+ *     a.rindex("b")             #=> 3
+ *     a.rindex("z")             #=> nil
+ *     a.rindex { |x| x == "b" } #=> 3
  */
 
 static VALUE
@@ -3496,18 +3513,23 @@ push_value(st_data_t key, st_data_t val, st_data_t ary)
 
 /*
  *  call-seq:
- *     ary.uniq! -> ary or nil
+ *     ary.uniq!                -> ary or nil
+ *     ary.uniq! { |item| ... } -> ary or nil
  *
- *  Removes duplicate elements from +self+.
+ *  Removes duplicate elements from +self+. If a block is given,
+ *  it will use the return value of the block for comparison.
  *  Returns <code>nil</code> if no changes are made (that is, no
  *  duplicates are found).
  *
  *     a = [ "a", "a", "b", "b", "c" ]
- *     a.uniq!   #=> ["a", "b", "c"]
+ *     a.uniq!   # => ["a", "b", "c"]
+ *
  *     b = [ "a", "b", "c" ]
- *     b.uniq!   #=> nil
- *     c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
- *     c.uniq! {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]
+ *     b.uniq!   # => nil
+ *
+ *     c = [["student","sam"], ["student","george"], ["teacher","matz"]]
+ *     c.uniq! { |s| s.first } # => [["student", "sam"], ["teacher", "matz"]]
+ *
  */
 
 static VALUE
@@ -3552,14 +3574,18 @@ rb_ary_uniq_bang(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.uniq   -> new_ary
+ *     ary.uniq                -> new_ary
+ *     ary.uniq { |item| ... } -> new_ary
  *
- *  Returns a new array by removing duplicate values in +self+.
+ *  Returns a new array by removing duplicate values in +self+. If a block
+ *  is given, it will use the return value of the block for comparison.
  *
  *     a = [ "a", "a", "b", "b", "c" ]
- *     a.uniq   #=> ["a", "b", "c"]
- *     c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
- *     c.uniq {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]
+ *     a.uniq   # => ["a", "b", "c"]
+ *
+ *     b = [["student","sam"], ["student","george"], ["teacher","matz"]]
+ *     b.uniq { |s| s.first } # => [["student", "sam"], ["teacher", "matz"]]
+ *
  */
 
 static VALUE