* array.c: rdoc patch. merged patch from Johan Holmberg

  <holmberg@iar.se> [ruby-core:3170]


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

1 files changed, 113 insertions, 111 deletions

diff --git a/array.c b/array.c
index 48652fef58..b55c7389f2 100644
--- a/array.c
+++ b/array.c
@@ -79,7 +79,7 @@ rb_ary_freeze(ary)
 
 /*
  * call-seq:
- *   array.frozen?  => true or false
+ *   array.frozen?  -> true or false
  *
  * Return <code>true</code> if this array is frozen (or temporarily frozen
  * while being sorted).
@@ -226,7 +226,7 @@ static VALUE rb_ary_replace _((VALUE, VALUE));
  * call-seq:
  *       Array.new(size=0, obj=nil)
  *       Array.new(array)
- *       Array.new(size) {|i| ...}
+ *       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_
@@ -386,7 +386,7 @@ rb_ary_store(ary, idx, val)
 
 /* 
  * call-seq:
- *   array << obj            => array
+ *   array << obj            -> array
  *  
  *   Append---Pushes the given object on to the end of this array. This
  *   expression returns the array itself, so several appends
@@ -408,7 +408,7 @@ rb_ary_push(ary, item)
 
 /* 
  * call-seq:
- *   array.push(obj, ... )   => array
+ *   array.push(obj, ... )   -> array
  *  
  *   Append---Pushes the given object(s) on to the end of this array. This
  *   expression returns the array itself, so several appends
@@ -433,7 +433,7 @@ rb_ary_push_m(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.pop  => obj or nil
+ *     array.pop  -> obj or nil
  *  
  *  Removes the last element from <i>self</i> and returns it, or
  *  <code>nil</code> if the array is empty.
@@ -476,7 +476,7 @@ ary_make_shared(ary)
 
 /*
  *  call-seq:
- *     array.shift   =>   obj or nil
+ *     array.shift   ->   obj or nil
  *  
  *  Returns the first element of <i>self</i> and removes it (shifting all
  *  other elements down by one). Returns <code>nil</code> if the array
@@ -528,7 +528,7 @@ rb_ary_unshift(ary, item)
 
 /*
  *  call-seq:
- *     array.unshift(obj, ...)  => array
+ *     array.unshift(obj, ...)  -> array
  *  
  *  Prepends objects to the front of <i>array</i>.
  *  other elements up one.
@@ -608,15 +608,15 @@ rb_ary_subseq(ary, beg, len)
 
 /* 
  * call-seq:
- *       array[int]                  => obj      or nil
- *       array[start, length]        => an_array or nil
- *       array[range]                => an_array or nil
- *       array.slice(int)            => obj      or nil
- *       array.slice(start, length)  => an_array or nil
- *       array.slice(range)          => an_array or nil
+ *       array[index]                -> obj      or nil
+ *       array[start, length]        -> an_array or nil
+ *       array[range]                -> an_array or nil
+ *       array.slice(index)          -> obj      or nil
+ *       array.slice(start, length)  -> an_array or nil
+ *       array.slice(range)          -> an_array or nil
  *
- * Element Reference---Returns the element at index _int_,
- * or returns a subarray starting at index _start_ and
+ * Element Reference---Returns the element at _index_,
+ * or returns a subarray starting at _start_ and
  * continuing for _length_ elements, or returns a subarray
  * specified by _range_.
  * Negative indices count backward from the end of the
@@ -685,13 +685,13 @@ rb_ary_aref(argc, argv, ary)
 
 /* 
  * call-seq:
- *      array.at(int)   #=>   obj  or nil
+ *      array.at(index)   ->   obj  or nil
  *
- *   Returns the element at index int. A
+ *   Returns the element at _index_. A
  *   negative index counts from the end of _self_.  Returns +nil+
- *   if the index is out of range. See also Array.[].
- *   (Array.at is slightly faster than Array.[], as it
- *   does not accept ranges and so on.)
+ *   if the index is out of range. See also <code>Array#[]</code>.
+ *   (<code>Array#at</code> is slightly faster than <code>Array#[]</code>,
+ *   as it does not accept ranges and so on.)
  *
  *     a = [ "a", "b", "c", "d", "e" ]
  *     a.at(0)     #=> "a"
@@ -707,7 +707,7 @@ rb_ary_at(ary, pos)
 
 /*
  *  call-seq:
- *     array.first   =>   obj or nil
+ *     array.first   ->   obj or nil
  *  
  *  Returns the first element of the array. If the array is empty,
  *  returns <code>nil</code>.
@@ -743,8 +743,8 @@ rb_ary_first(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.last     =>  obj or nil
- *     array.last(n)  =>  an_array
+ *     array.last     ->  obj or nil
+ *     array.last(n)  ->  an_array
  *  
  *  Returns the last element(s) of <i>self</i>. If the array is empty,
  *  the first form returns <code>nil</code>.
@@ -779,9 +779,9 @@ rb_ary_last(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.fetch(index)                => obj
- *     array.fetch(index, default )      => obj
- *     array.fetch(index) {|i| block }   => obj
+ *     array.fetch(index)                    -> obj
+ *     array.fetch(index, default )          -> obj
+ *     array.fetch(index) {|index| block }   -> obj
  *  
  *  Tries to return the element at position <i>index</i>. If the index
  *  lies outside the array, the first form throws an
@@ -829,7 +829,7 @@ rb_ary_fetch(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.index(obj)   =>  int or nil
+ *     array.index(obj)   ->  int or nil
  *  
  *  Returns the index of the first object in <i>self</i> such that is 
  *  <code>==</code> to <i>obj</i>. Returns <code>nil</code> if
@@ -856,9 +856,9 @@ rb_ary_index(ary, val)
 
 /*
  *  call-seq:
- *     array.rindex(obj)    =>  int or nil
+ *     array.rindex(obj)    ->  int or nil
  *  
- *  Returns the index of the last object in <i>arr</i> 
+ *  Returns the index of the last object in <i>array</i> 
  *  <code>==</code> to <i>obj</i>. Returns <code>nil</code> if
  *  no match is found.
  *     
@@ -883,8 +883,8 @@ rb_ary_rindex(ary, val)
 
 /*
  *  call-seq:
- *     array.indexes( i1, i2, ... iN )   => an_array
- *     array.indices( i1, i2, ... iN )   => an_array
+ *     array.indexes( i1, i2, ... iN )   -> an_array
+ *     array.indices( i1, i2, ... iN )   -> an_array
  *  
  *  Deprecated; use <code>Array#select</code>.
  */
@@ -987,30 +987,30 @@ rb_ary_update(ary, beg, len, rpl)
 
 /* 
  * call-seq:
- *    array[int] = obj                  =>  obj
- *    array[start, length] = an_array   =>  an_array
- *    array[range] = an_array           =>  an_array
+ *    array[index]         = obj                     ->  obj
+ *    array[start, length] = obj or an_array or nil  ->  obj or an_array or nil
+ *    array[range]         = obj or an_array or nil  ->  obj or an_array or nil
  *
- *   Element Assignment---Sets the element at index _int_,
- *   or replaces a subarray starting at index _start_ and
+ *   Element Assignment---Sets the element at _index_,
+ *   or replaces a subarray starting at _start_ and
  *   continuing for _length_ elements, or replaces a subarray
- *   specified by _range_.  If _int_ is greater than
+ *   specified by _range_.  If indices are greater than
  *   the current capacity of the array, the array grows
- *   automatically. A negative _int_ will count backward
+ *   automatically. A negative indices will count backward
  *   from the end of the array. Inserts elements if _length_ is
- *   zero. If _an_array is +nil+, deletes elements from _self_.
- *   An +IndexError+ is raised if a
+ *   zero. If +nil+ is used in the second and third form,
+ *   deletes elements from _self_. An +IndexError+ is raised if a
  *   negative index points past the beginning of the array. See also
- *   Array.push, and Array.unshift.
+ *   <code>Array#push</code>, and <code>Array#unshift</code>.
  * 
  *     a = Array.new
- *     a[4] = "4";                
- *     a[0, 3] = [ 'a', 'b', 'c' ]
- *     a[1..2] = [ 1, 2 ];        
- *     a[0, 2] = "?";             
- *     a[0..2] = "A";             
- *     a[-1]   = "Z";              
- *     a[1..-1] = nil;             
+ *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
+ *     a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
+ *     a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
+ *     a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
+ *     a[0..2] = "A"               #=> ["A", "4"]
+ *     a[-1]   = "Z"               #=> ["A", "Z"]
+ *     a[1..-1] = nil              #=> ["A"]
  */
 
 static VALUE
@@ -1055,7 +1055,7 @@ fixnum:
 
 /*
  *  call-seq:
- *     array.insert(index, obj...)  => array
+ *     array.insert(index, obj...)  -> array
  *  
  *  Inserts the given values before the element with the given index
  *  (which may be negative).
@@ -1091,7 +1091,7 @@ rb_ary_insert(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.each {|item| block }   =>   array
+ *     array.each {|item| block }   ->   array
  *  
  *  Calls <i>block</i> once for each element in <i>self</i>, passing that
  *  element as a parameter.
@@ -1118,7 +1118,7 @@ rb_ary_each(ary)
 
 /*
  *  call-seq:
- *     array.each_index {|index| block }  =>  array
+ *     array.each_index {|index| block }  ->  array
  *  
  *  Same as <code>Array#each</code>, but passes the index of the element
  *  instead of the element itself.
@@ -1191,7 +1191,7 @@ rb_ary_length(ary)
 
 /*
  *  call-seq:
- *     array.empty?   => true or false
+ *     array.empty?   -> true or false
  *  
  *  Returns <code>true</code> if <i>self</i> array contains no elements.
  *     
@@ -1281,7 +1281,7 @@ rb_ary_join(ary, sep)
 
 /*
  *  call-seq:
- *     array.join(sep=$,)    => str
+ *     array.join(sep=$,)    -> str
  *  
  *  Returns a string created by converting each element of the array to
  *  a string, separated by <i>sep</i>.
@@ -1427,7 +1427,7 @@ inspect_ary(ary)
 
 /*
  * call-seq:
- *   array.inspect  => string
+ *   array.inspect  -> string
  *
  * Create a printable version of <i>array</i>.
  */
@@ -1443,7 +1443,7 @@ rb_ary_inspect(ary)
 
 /*
  *  call-seq:
- *     array.to_a     => array
+ *     array.to_a     -> array
  *  
  *  Returns _self_. If called on a subclass of Array, converts
  *  the receiver to an Array object.
@@ -1498,7 +1498,7 @@ rb_ary_reverse(ary)
 
 /*
  *  call-seq:
- *     array.reverse!   => array 
+ *     array.reverse!   -> array 
  *  
  *  Reverses _self_ in place.
  *     
@@ -1578,8 +1578,8 @@ sort_unlock(ary)
 
 /*
  *  call-seq:
- *     array.sort!                   => array
- *     array.sort! {| a,b | block }  => array 
+ *     array.sort!                   -> array
+ *     array.sort! {| a,b | block }  -> array 
  *  
  *  Sorts _self_. Comparisons for
  *  the sort will be done using the <code><=></code> operator or using
@@ -1606,8 +1606,8 @@ rb_ary_sort_bang(ary)
 
 /*
  *  call-seq:
- *     array.sort                   => an_array 
- *     array.sort {| a,b | block }  => an_array 
+ *     array.sort                   -> an_array 
+ *     array.sort {| a,b | block }  -> an_array 
  *  
  *  Returns a new array created by sorting <i>self</i>. Comparisons for
  *  the sort will be done using the <code><=></code> operator or using
@@ -1631,8 +1631,8 @@ rb_ary_sort(ary)
 
 /*
  *  call-seq:
- *     array.collect {|obj| block }  -> an_array
- *     array.map     {|obj| block }  -> an_array
+ *     array.collect {|item| block }  -> an_array
+ *     array.map     {|item| block }  -> an_array
  *  
  *  Invokes <i>block</i> once for each element of <i>self</i>. Creates a 
  *  new array containing the values returned by the block.
@@ -1663,12 +1663,12 @@ rb_ary_collect(ary)
 
 /* 
  * call-seq:
- *    array.collect! {|obj} ...}   =>   array
- *    array.map!     {|obj} ...}   =>   array
+ *    array.collect! {|item| block }   ->   array
+ *    array.map!     {|item| block }   ->   array
  *
- *   Invokes the block once for each element of _self_self, replacing the
+ *   Invokes the block once for each element of _self_, replacing the
  *   element with the value returned by _block_.
- *   See also Enumerable.collect.
+ *   See also <code>Enumerable#collect</code>.
  *   
  *     a = [ "a", "b", "c", "d" ]
  *     a.collect! {|x| x + "!" }
@@ -1723,12 +1723,12 @@ rb_values_at(obj, olen, argc, argv, func)
 
 /* 
  * call-seq:
- *   array.values_at(selector,... )  => an_array
+ *   array.values_at(selector,... )  -> an_array
  *
  *   Returns an array containing the elements in
  *   _self_ corresponding to the given selector(s). The selectors
  *   may be either integer indices or ranges. 
- *   See also <code>.select</code>.
+ *   See also <code>Array#select</code>.
  * 
  *      a = %w{ a b c d e f }
  *      a.values_at(1, 3, 5)
@@ -1748,9 +1748,9 @@ rb_ary_values_at(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.select {|i| block } -> an_array
+ *     array.select {|item| block } -> an_array
  *  
- *  Invokes the block passing in successive elements from <i>arr</i>,
+ *  Invokes the block passing in successive elements from <i>array</i>,
  *  returning an array containing those elements for which the block
  *  returns a true value (equivalent to <code>Enumerable#select</code>).
  *     
@@ -1781,8 +1781,8 @@ rb_ary_select(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.delete(obj)               => obj or nil 
- *     array.delete(obj) {| | block }  => obj or nil
+ *     array.delete(obj)            -> obj or nil 
+ *     array.delete(obj) { block }  -> obj or nil
  *  
  *  Deletes items from <i>self</i> that are equal to <i>obj</i>. If
  *  the item is not found, returns <code>nil</code>. If the optional
@@ -1875,9 +1875,9 @@ rb_ary_delete_at_m(ary, pos)
 
 /*
  *  call-seq:
- *     array.slice!(int)           => obj or nil
- *     array.slice!(start, length) => sub_array or nil
- *     array.slice!(range)         => sub_array or nil 
+ *     array.slice!(index)         -> obj or nil
+ *     array.slice!(start, length) -> sub_array or nil
+ *     array.slice!(range)         -> sub_array or nil 
  *  
  *  Deletes the element(s) given by an index (optionally with a length)
  *  or by a range. Returns the deleted object, subarray, or
@@ -1929,7 +1929,7 @@ rb_ary_slice_bang(argc, argv, ary)
 
 /*
  *  call-seq:
- *     array.reject! {| | block }  -> array or nil
+ *     array.reject! {|item| block }  -> array or nil
  *  
  *  Equivalent to <code>Array#delete_if</code>, deleting elements from
  *  _self_ for which the block evaluates to true, but returns
@@ -1959,7 +1959,7 @@ rb_ary_reject_bang(ary)
 
 /*
  *  call-seq:
- *     arr.reject {|item| block }  -> an_array
+ *     array.reject {|item| block }  -> an_array
  *  
  *  Returns a new array containing the items in _self_
  *  for which the block is not true.
@@ -2000,9 +2000,9 @@ rb_ary_delete_if(ary)
  *  
  *  Converts any arguments to arrays, then merges elements of
  *  <i>self</i> with corresponding elements from each argument. This
- *  generates a sequence of <code>self#size</code> <em>n</em>-element
+ *  generates a sequence of <code>self.size</code> <em>n</em>-element
  *  arrays, where <em>n</em> is one more that the count of arguments. If
- *  the size of any argument is less than <code>enumObj#size</code>,
+ *  the size of any argument is less than <code>enumObj.size</code>,
  *  <code>nil</code> values are supplied. If a block given, it is
  *  invoked for each output array, otherwise an array of arrays is
  *  returned.
@@ -2096,7 +2096,7 @@ rb_ary_transpose(ary)
 
 /*
  *  call-seq:
- *     array.replace(other_array)  => array
+ *     array.replace(other_array)  -> array
  *  
  *  Replaces the contents of <i>self</i> with the contents of
  *  <i>other_array</i>, truncating or expanding if necessary.
@@ -2125,9 +2125,10 @@ rb_ary_replace(copy, orig)
 }
 
 /* 
- * call-seq:
- *     array.clear    =>  array
- *   Removes all elements from _self_.
+ *  call-seq:
+ *     array.clear    ->  array
+ *
+ *  Removes all elements from _self_.
  *
  *     a = [ "a", "b", "c", "d", "e" ]
  *     a.clear    #=> [ ]
@@ -2148,17 +2149,17 @@ rb_ary_clear(ary)
 
 /*
  *  call-seq:
- *     array.fill(obj) -> array
- *     array.fill(obj, start [, length])          => array
- *     array.fill(obj, range )                    => array
- *     array.fill {|i| block }                    => array
- *     array.fill(start [, length] ) {|i| block } => array
- *     array.fill(range) {|i| block }             => array
+ *     array.fill(obj)                                -> array
+ *     array.fill(obj, start [, length])              -> array
+ *     array.fill(obj, range )                        -> array
+ *     array.fill {|index| block }                    -> array
+ *     array.fill(start [, length] ) {|index| block } -> array
+ *     array.fill(range) {|index| block }             -> array
  *  
  *  The first three forms set the selected elements of <i>self</i> (which
  *  may be the entire array) to <i>obj</i>. A <i>start</i> of
  *  <code>nil</code> is equivalent to zero. A <i>length</i> of
- *  <code>nil</code> is equivalent to <i>arr</i>.length. The last three
+ *  <code>nil</code> is equivalent to <i>self.length</i>. The last three
  *  forms fill the array with the value of the block. The block is
  *  passed the absolute index of each element to be filled.
  *     
@@ -2243,7 +2244,7 @@ rb_ary_fill(argc, argv, ary)
 
 /* 
  * call-seq:
- *    array + other_array   => an_array
+ *    array + other_array   -> an_array
  *
  *   Concatenation---Returns a new array built by concatenating the
  *   two arrays together to produce a third array.
@@ -2269,7 +2270,7 @@ rb_ary_plus(x, y)
 
 /* 
  * call-seq:
- *   self.concat(other_array)   =>  array
+ *   array.concat(other_array)   ->  array
  *
  *  Appends the elements in other_array to _self_.
  *  
@@ -2291,8 +2292,8 @@ rb_ary_concat(x, y)
 
 /* 
  * call-seq:
- *     array * int     =>    an_array
- *     array * str     =>    a_string
+ *     array * int     ->    an_array
+ *     array * str     ->    a_string
  *
  *   Repetition---With a String argument, equivalent to
  *   self.join(str). Otherwise, returns a new array
@@ -2300,6 +2301,7 @@ rb_ary_concat(x, y)
  *
  *
  *     [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
+ *     [ 1, 2, 3 ] * ","  #=> "1,2,3"
  *
  */
 
@@ -2338,7 +2340,7 @@ rb_ary_times(ary, times)
 
 /* 
  *   call-seq:
- *     array.assoc(obj)   =>  an_array  or  nil
+ *     array.assoc(obj)   ->  an_array  or  nil
  *
  *   Searches through an array whose elements are also arrays
  *   comparing _obj_ with the first element of each contained array
@@ -2346,7 +2348,7 @@ rb_ary_times(ary, times)
  *   Returns the first contained array that matches (that
  *   is, the first associated array),
  *   or +nil+ if no match is found.
- *   See also Array.rassoc.
+ *   See also <code>Array#rassoc</code>.
  *
  *     s1 = [ "colors", "red", "blue", "green" ]
  *     s2 = [ "letters", "a", "b", "c" ]
@@ -2410,7 +2412,7 @@ rb_ary_rassoc(ary, value)
 
 /* 
  * call-seq:
- *   array == other_array   =>   bool
+ *   array == other_array   ->   bool
  *
  *   Equality---Two arrays are equal if they contain the same number
  *   of elements and if each element is equal to (according to
@@ -2445,7 +2447,7 @@ rb_ary_equal(ary1, ary2)
 
 /*
  * call-seq:
- *   array.eql?(other)  => true or false
+ *   array.eql?(other)  -> true or false
  *
  * Returns <code>true</code> if _array_ and _other_ are the same object,
  * or are both arrays with the same content.
@@ -2469,7 +2471,7 @@ rb_ary_eql(ary1, ary2)
 
 /*
  * call-seq:
- *   array.hash   => fixnum
+ *   array.hash   -> fixnum
  *
  * Compute a hash-code for this array. Two arrays with the same content
  * will have the same hash code (and will compare using <code>eql?</code>).
@@ -2493,7 +2495,7 @@ rb_ary_hash(ary)
 
 /*
  *  call-seq:
- *     array.include?(obj)   => true or false
+ *     array.include?(obj)   -> true or false
  *  
  *  Returns <code>true</code> if the given object is present in
  *  <i>self</i> (that is, if any object <code>==</code> <i>anObject</i>),
@@ -2522,7 +2524,7 @@ rb_ary_includes(ary, item)
 
 /* 
  * call-seq:
- *   array <=> other_array   =>  -1, 0, +1
+ *   array <=> other_array   ->  -1, 0, +1
  *
  *   Comparison---Returns an integer (-1, 0,
  *   or +1) if this array is less than, equal to, or greater than
@@ -2531,7 +2533,7 @@ rb_ary_includes(ary, item)
  *   equal, then that inequality is the return value. If all the
  *   values found are equal, then the return is based on a
  *   comparison of the array lengths.  Thus, two arrays are
- *   ``equal'' according to Array.<=> if and only if they have
+ *   ``equal'' according to <code>Array#<=></code> if and only if they have
  *   the same length and the value of each element is equal to the
  *   value of the corresponding element in the other array.
  *  
@@ -2583,7 +2585,7 @@ ary_make_hash(ary1, ary2)
 
 /* 
  * call-seq:
- *     array - other_array    => an_array
+ *     array - other_array    -> an_array
  *
  *   Array Difference---Returns a new array that is a copy of
  *   the original array, removing any items that also appear in
@@ -2645,7 +2647,7 @@ rb_ary_and(ary1, ary2)
 
 /* 
  * call-seq:
- *    array | other_array     =>  an_array
+ *    array | other_array     ->  an_array
  *
  *  Set Union---Returns a new array by joining this array with
  *  other_array, removing duplicates.
@@ -2683,7 +2685,7 @@ rb_ary_or(ary1, ary2)
 
 /*
  *  call-seq:
- *     array.uniq! => array or nil
+ *     array.uniq! -> array or nil
  *  
  *  Removes duplicate elements from _self_.
  *  Returns <code>nil</code> if no changes are made (that is, no
@@ -2725,7 +2727,7 @@ rb_ary_uniq_bang(ary)
 
 /*
  *  call-seq:
- *     array.uniq   => an_array
+ *     array.uniq   -> an_array
  *  
  *  Returns a new array by removing duplicate values in <i>self</i>.
  *     
@@ -2744,10 +2746,10 @@ rb_ary_uniq(ary)
 
 /* 
  * call-seq:
- *      array.compact!    =>   array  or  nil
+ *      array.compact!    ->   array  or  nil
  *
  *  Removes +nil+ elements from array.
- *  Returns +niL+ if no changes were made.
+ *  Returns +nil+ if no changes were made.
  *     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
  *     [ "a", "b", "c" ].compact!           #=> nil
  */
@@ -2777,7 +2779,7 @@ rb_ary_compact_bang(ary)
 
 /* 
  * call-seq:
- *    array.compact     =>  an_array
+ *    array.compact     ->  an_array
  *
  * Returns a copy of _self_ with all +nil+ elements removed.
  *   
@@ -2851,11 +2853,11 @@ flatten(ary, idx, ary2, memo)
 
 /*
  *  call-seq:
- *     arr.flatten! -> arr or nil
+ *     array.flatten! -> array or nil
  *  
  *  Flattens _self_ in place.
  *  Returns <code>nil</code> if no modifications were made (i.e.,
- *  <i>arr</i> contains no subarrays.)
+ *  <i>array</i> contains no subarrays.)
  *     
  *     a = [ 1, 2, [3, [4, 5] ] ]
  *     a.flatten!   #=> [1, 2, 3, 4, 5]