* array.c: Use + for arguments described in documentation to allow

  rdoc -C2 to work better.  Remove <code> from method references to
  allow cross-references in HTML documentation.


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

1 files changed, 91 insertions, 96 deletions

diff --git a/array.c b/array.c
index 56b57b7b23..a416cc2ec5 100644
--- a/array.c
+++ b/array.c
@@ -478,8 +478,8 @@ 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
+ *  Try to convert +obj+ into an array, using +to_ary+ method.
+ *  Returns 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.
  *
@@ -506,14 +506,12 @@ 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, or it is created with _size_ copies of _obj_ (that is,
- *  _size_ references to the same _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). 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
+ *  Returns a new array.  In the first form, the new array is empty, or it is
+ *  created with +size+ copies of +obj+ (that is, +size+ references to the
+ *  same +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). 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                     # => [] (empty array)
@@ -787,7 +785,7 @@ rb_ary_pop(VALUE ary)
  *  Removes the last element from +self+ and returns it, or
  *  <code>nil</code> if the array is empty.
  *
- *  If a number _n_ is given, returns an array of the last n elements
+ *  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.
  *
  *     a = [ "a", "b", "c", "d" ]
@@ -848,7 +846,7 @@ rb_ary_shift(VALUE ary)
  *  other elements down by one). Returns <code>nil</code> if the array
  *  is empty.
  *
- *  If a number _n_ is given, returns an array of the first n elements
+ *  If a number +n+ is given, returns an array of the first n elements
  *  (or less) just like <code>array.slice!(0, n)</code> does.
  *
  *     args = [ "-m", "-q", "filename" ]
@@ -970,10 +968,10 @@ rb_ary_subseq(VALUE ary, long beg, long len)
  *     ary.slice(start, length)  -> new_ary or nil
  *     ary.slice(range)          -> new_ary or nil
  *
- *  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_.
+ *  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
  *  array (-1 is the last element). Returns +nil+ if the index
  *  (or starting index) are out of range.
@@ -1031,7 +1029,7 @@ rb_ary_aref(int argc, VALUE *argv, VALUE ary)
  *  call-seq:
  *     ary.at(index)   ->   obj  or nil
  *
- *  Returns the element at _index_. 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 <code>Array#[]</code>.
  *
@@ -1103,12 +1101,11 @@ rb_ary_last(int argc, VALUE *argv, VALUE ary)
  *     ary.fetch(index, default )          -> obj
  *     ary.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
- *  <code>IndexError</code> exception, the second form returns
- *  <i>default</i>, and the third form returns the value of invoking
- *  the block, passing in the index. Negative values of <i>index</i>
- *  count from the end of the array.
+ *  Tries to return the element at position +index+. If the index lies outside
+ *  the array, the first form throws an IndexError exception, the second form
+ *  returns +default+, and the third form returns the value of invoking the
+ *  block, passing in the index. Negative values of +index+ count from the end
+ *  of the array.
  *
  *     a = [ 11, 22, 33, 44 ]
  *     a.fetch(1)               #=> 22
@@ -1152,7 +1149,7 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
  *     ary.index                ->  an_enumerator
  *
  *  Returns the index of the first object in +self+ such that the object is
- *  <code>==</code> to <i>obj</i>. If a block is given instead of an
+ *  <code>==</code> to +obj+. If a block is given instead of an
  *  argument, returns index of first object for which <em>block</em> is true.
  *  Returns <code>nil</code> if no match is found.
  *  See also <code>Array#rindex</code>.
@@ -1199,11 +1196,11 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary)
  *     ary.rindex                ->  an_enumerator
  *
  *  Returns the index of the last object in +self+
- *  <code>==</code> to <i>obj</i>. If a block is given instead of an
+ *  <code>==</code> to +obj+. If a block is given instead of an
  *  argument, returns index of first object for which <em>block</em> is
  *  true, starting from the last object.
  *  Returns <code>nil</code> if no match is found.
- *  See also <code>Array#index</code>.
+ *  See also Array#index.
  *
  *  If neither block nor argument is given, an enumerator is returned instead.
  *
@@ -1377,16 +1374,16 @@ rb_ary_resize(VALUE ary, long len)
  *     ary[start, length] = obj or other_ary or nil  ->  obj or other_ary or nil
  *     ary[range]         = obj or other_ary or nil  ->  obj or other_ary or nil
  *
- *  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 indices are greater than
+ *  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 indices are greater than
  *  the current capacity of the array, the array grows
  *  automatically. A negative indices will count backward
- *  from the end of the array. Inserts elements if _length_ is
- *  zero. An +IndexError+ is raised if a negative index points
+ *  from the end of the array. Inserts elements if +length+ is
+ *  zero. An IndexError is raised if a negative index points
  *  past the beginning of the array. See also
- *  <code>Array#push</code>, and <code>Array#unshift</code>.
+ *  Array#push, and Array#unshift.
  *
  *     a = Array.new
  *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
@@ -1469,7 +1466,7 @@ rb_ary_insert(int argc, VALUE *argv, VALUE ary)
  *     ary.each {|item| block }   -> ary
  *     ary.each                   -> an_enumerator
  *
- *  Calls <i>block</i> once for each element in +self+, passing that
+ *  Calls +block+ once for each element in +self+, passing that
  *  element as a parameter.
  *
  *  If no block is given, an enumerator is returned instead.
@@ -1500,8 +1497,8 @@ rb_ary_each(VALUE array)
  *     ary.each_index {|index| block }  -> ary
  *     ary.each_index                   -> an_enumerator
  *
- *  Same as <code>Array#each</code>, but passes the index of the element
- *  instead of the element itself.
+ *  Same as Array#each, but passes the index of the element instead of the
+ *  element itself.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -1531,8 +1528,7 @@ rb_ary_each_index(VALUE ary)
  *     ary.reverse_each {|item| block }   -> ary
  *     ary.reverse_each                   -> an_enumerator
  *
- *  Same as <code>Array#each</code>, but traverses +self+ in reverse
- *  order.
+ *  Same as Array#each, but traverses +self+ in reverse order.
  *
  *     a = [ "a", "b", "c" ]
  *     a.reverse_each {|x| print x, " " }
@@ -1747,7 +1743,7 @@ rb_ary_join(VALUE ary, VALUE sep)
  *     ary.join(sep=$,)    -> str
  *
  *  Returns a string created by converting each element of the array to
- *  a string, separated by <i>sep</i>.
+ *  a string, separated by +sep+.
  *
  *     [ "a", "b", "c" ].join        #=> "abc"
  *     [ "a", "b", "c" ].join("-")   #=> "a-b-c"
@@ -2082,8 +2078,8 @@ sort_2(const void *ap, const void *bp, void *dummy)
  *  Sorts +self+. Comparisons for
  *  the sort will be done using the <code><=></code> operator or using
  *  an optional code block. The block implements a comparison between
- *  <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also
- *  <code>Enumerable#sort_by</code>.
+ *  +a+ and +b+, returning -1, 0, or +1. See also
+ *  Enumerable#sort_by.
  *
  *     a = [ "d", "a", "e", "c", "b" ]
  *     a.sort!                    #=> ["a", "b", "c", "d", "e"]
@@ -2158,8 +2154,8 @@ rb_ary_sort_bang(VALUE ary)
  *  Returns a new array created by sorting +self+. Comparisons for
  *  the sort will be done using the <code><=></code> operator or using
  *  an optional code block. The block implements a comparison between
- *  <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also
- *  <code>Enumerable#sort_by</code>.
+ *  +a+ and +b+, returning -1, 0, or +1. See also
+ *  Enumerable#sort_by.
  *
  *     a = [ "d", "a", "e", "c", "b" ]
  *     a.sort                    #=> ["a", "b", "c", "d", "e"]
@@ -2213,9 +2209,9 @@ rb_ary_sort_by_bang(VALUE ary)
  *     ary.collect                  -> an_enumerator
  *     ary.map                      -> an_enumerator
  *
- *  Invokes <i>block</i> once for each element of +self+. Creates a
+ *  Invokes +block+ once for each element of +self+. Creates a
  *  new array containing the values returned by the block.
- *  See also <code>Enumerable#collect</code>.
+ *  See also Enumerable#collect.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2247,8 +2243,8 @@ rb_ary_collect(VALUE ary)
  *     ary.map                        -> an_enumerator
  *
  *  Invokes the block once for each element of +self+, replacing the
- *  element with the value returned by _block_.
- *  See also <code>Enumerable#collect</code>.
+ *  element with the value returned by +block+.
+ *  See also Enumerable#collect.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2305,7 +2301,7 @@ rb_get_values_at(VALUE obj, long olen, int argc, VALUE *argv, VALUE (*func) (VAL
  *  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>Array#select</code>.
+ *  See also Array#select.
  *
  *     a = %w{ a b c d e f }
  *     a.values_at(1, 3, 5)
@@ -2328,7 +2324,7 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
  *
  *  Invokes the block passing in successive elements from +self+,
  *  returning an array containing those elements for which the block
- *  returns a true value (equivalent to <code>Enumerable#select</code>).
+ *  returns a true value (equivalent to Enumerable#select).
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2361,7 +2357,7 @@ rb_ary_select(VALUE ary)
  *  +self+, deleting elements for which the block returns a
  *  false value. It returns +self+ if changes were made,
  *  otherwise it returns <code>nil</code>.
- *  See also <code>Array#keep_if</code>
+ *  See also Array#keep_if
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2394,9 +2390,9 @@ rb_ary_select_bang(VALUE ary)
  *     ary.keep_if {|item| block } -> ary
  *     ary.keep_if                 -> an_enumerator
  *
- *  Deletes every element of +self+ for which <i>block</i> evaluates
+ *  Deletes every element of +self+ for which +block+ evaluates
  *  to false.
- *  See also <code>Array#select!</code>
+ *  See also Array#select!
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2417,10 +2413,10 @@ rb_ary_keep_if(VALUE ary)
  *     ary.delete(obj)            -> obj or nil
  *     ary.delete(obj) { block }  -> obj or nil
  *
- *  Deletes items from +self+ that are equal to <i>obj</i>.
- *  If any items are found, returns <i>obj</i>.   If
+ *  Deletes items from +self+ that are equal to +obj+.
+ *  If any items are found, returns +obj+.   If
  *  the item is not found, returns <code>nil</code>. If the optional
- *  code block is given, returns the result of <i>block</i> if the item
+ *  code block is given, returns the result of +block+ if the item
  *  is not found.  (To remove <code>nil</code> elements and
  *  get an informative return value, use #compact!)
  *
@@ -2495,7 +2491,7 @@ rb_ary_delete_at(VALUE ary, long pos)
  *
  *  Deletes the element at the specified index, returning that element,
  *  or <code>nil</code> if the index is out of range. See also
- *  <code>Array#slice!</code>.
+ *  Array#slice!.
  *
  *     a = ["ant", "bat", "cat", "dog"]
  *     a.delete_at(2)    #=> "cat"
@@ -2618,10 +2614,10 @@ ary_reject_bang(VALUE ary)
  *     ary.reject! {|item| block }  -> ary or nil
  *     ary.reject!                  -> an_enumerator
  *
- *  Equivalent to <code>Array#delete_if</code>, deleting elements from
+ *  Equivalent to Array#delete_if, deleting elements from
  *  +self+ for which the block evaluates to true, but returns
  *  <code>nil</code> if no changes were made.
- *  See also <code>Enumerable#reject</code> and <code>Array#delete_if</code>.
+ *  See also Enumerable#reject and Array#delete_if.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2641,7 +2637,7 @@ rb_ary_reject_bang(VALUE ary)
  *
  *  Returns a new array containing the items in +self+
  *  for which the block is not true.
- *  See also <code>Array#delete_if</code>
+ *  See also Array#delete_if
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2663,9 +2659,9 @@ rb_ary_reject(VALUE ary)
  *     ary.delete_if {|item| block }  -> ary
  *     ary.delete_if                  -> an_enumerator
  *
- *  Deletes every element of +self+ for which <i>block</i> evaluates
+ *  Deletes every element of +self+ for which +block+ evaluates
  *  to true.
- *  See also <code>Array#reject!</code>
+ *  See also Array#reject!
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -2801,7 +2797,7 @@ rb_ary_transpose(VALUE ary)
  *     ary.replace(other_ary)  -> ary
  *
  *  Replaces the contents of +self+ with the contents of
- *  <i>other_ary</i>, truncating or expanding if necessary.
+ *  +other_ary+, truncating or expanding if necessary.
  *
  *     a = [ "a", "b", "c", "d", "e" ]
  *     a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
@@ -2887,12 +2883,12 @@ rb_ary_clear(VALUE ary)
  *     ary.fill(range) {|index| block }             -> ary
  *
  *  The first three forms set the selected elements of +self+ (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>self.length</i>. The last three
+ *  may be the entire array) to +obj+. A +start+ of
+ *  <code>nil</code> is equivalent to zero. A +length+ of
+ *  <code>nil</code> is equivalent to <code>self.length</code>. 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.
- *  Negative values of <i>start</i> count from the end of the array.
+ *  Negative values of +start+ count from the end of the array.
  *
  *     a = [ "a", "b", "c", "d" ]
  *     a.fill("x")              #=> ["x", "x", "x", "x"]
@@ -3002,7 +2998,7 @@ rb_ary_plus(VALUE x, VALUE y)
  *  call-seq:
  *     ary.concat(other_ary)   -> ary
  *
- *  Appends the elements of <i>other_ary</i> to +self+.
+ *  Appends the elements of +other_ary+ to +self+.
  *
  *     [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
  */
@@ -3027,7 +3023,7 @@ rb_ary_concat(VALUE x, VALUE y)
  *
  *  Repetition---With a String argument, equivalent to
  *  self.join(str). Otherwise, returns a new array
- *  built by concatenating the _int_ copies of +self+.
+ *  built by concatenating the +int+ copies of +self+.
  *
  *
  *     [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
@@ -3086,12 +3082,12 @@ rb_ary_times(VALUE ary, VALUE times)
  *     ary.assoc(obj)   -> new_ary  or  nil
  *
  *  Searches through an array whose elements are also arrays
- *  comparing _obj_ with the first element of each contained array
+ *  comparing +obj+ with the first element of each contained array
  *  using obj.==.
  *  Returns the first contained array that matches (that
  *  is, the first associated array),
  *  or +nil+ if no match is found.
- *  See also <code>Array#rassoc</code>.
+ *  See also Array#rassoc.
  *
  *     s1 = [ "colors", "red", "blue", "green" ]
  *     s2 = [ "letters", "a", "b", "c" ]
@@ -3121,9 +3117,9 @@ rb_ary_assoc(VALUE ary, VALUE key)
  *     ary.rassoc(obj) -> new_ary or nil
  *
  *  Searches through the array whose elements are also arrays. Compares
- *  _obj_ with the second element of each contained array using
+ *  +obj+ with the second element of each contained array using
  *  <code>==</code>. Returns the first contained array that matches. See
- *  also <code>Array#assoc</code>.
+ *  also Array#assoc.
  *
  *     a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
  *     a.rassoc("two")    #=> [2, "two"]
@@ -3204,7 +3200,7 @@ recursive_eql(VALUE ary1, VALUE ary2, int recur)
  *  call-seq:
  *     ary.eql?(other)  -> true or false
  *
- *  Returns <code>true</code> if +self+ and _other_ are the same object,
+ *  Returns <code>true</code> if +self+ and +other+ are the same object,
  *  or are both arrays with the same content.
  */
 
@@ -3254,10 +3250,10 @@ rb_ary_hash(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.include?(obj)   -> true or false
+ *     ary.include?(object)   -> true or false
  *
- *  Returns <code>true</code> if the given object is present in
- *  +self+ (that is, if any object <code>==</code> <i>anObject</i>),
+ *  Returns <code>true</code> if the given +object+ is present in
+ *  +self+ (that is, if any object <code>==</code> +object+),
  *  <code>false</code> otherwise.
  *
  *     a = [ "a", "b", "c" ]
@@ -3304,12 +3300,12 @@ recursive_cmp(VALUE ary1, VALUE ary2, int recur)
  *
  *  Comparison---Returns an integer (-1, 0,
  *  or +1) if this array is less than, equal to, or greater than
- *  <i>other_ary</i>.  Each object in each array is compared
+ *  +other_ary+.  Each object in each array is compared
  *  (using <=>). If any value isn't
  *  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 <code>Array#<=></code> if and only if they have
+ *  ``equal'' according to Array#<=> 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.
  *
@@ -3399,7 +3395,7 @@ ary_recycle_hash(VALUE hash)
  *
  *  Array Difference---Returns a new array that is a copy of
  *  the original array, removing any items that also appear in
- *  <i>other_ary</i>. (If you need set-like behavior, see the
+ *  +other_ary+. (If you need set-like behavior, see the
  *  library class Set.)
  *
  *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
@@ -3465,7 +3461,7 @@ rb_ary_and(VALUE ary1, VALUE ary2)
  *     ary | other_ary     -> new_ary
  *
  *  Set Union---Returns a new array by joining this array with
- *  <i>other_ary</i>, removing duplicates.
+ *  +other_ary+, removing duplicates.
  *
  *     [ "a", "b", "c" ] | [ "c", "d", "a" ]
  *            #=> [ "a", "b", "c", "d" ]
@@ -3606,8 +3602,7 @@ rb_ary_uniq(VALUE ary)
  *     ary.compact!    -> ary  or  nil
  *
  *  Removes +nil+ elements from the array.
- *  Returns +nil+ if no changes were made, otherwise returns
- *  <i>ary</i>.
+ *  Returns +nil+ if no changes were made, otherwise returns the array.
  *
  *     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
  *     [ "a", "b", "c" ].compact!           #=> nil
@@ -3664,7 +3659,7 @@ rb_ary_compact(VALUE ary)
  *     ary.count { |item| block }  -> int
  *
  *  Returns the number of elements.  If an argument is given, counts
- *  the number of elements which equals to <i>obj</i>.  If a block is
+ *  the number of elements which equals to +obj+.  If a block is
  *  given, counts the number of elements yielding a true value.
  *
  *     ary = [1, 2, 4, 2]
@@ -3765,7 +3760,7 @@ flatten(VALUE ary, int level, int *modified)
  *
  *  Flattens +self+ in place.
  *  Returns <code>nil</code> if no modifications were made (i.e.,
- *  <i>ary</i> contains no subarrays.)  If the optional <i>level</i>
+ *  the array contains no subarrays.)  If the optional +level+
  *  argument determines the level of recursion to flatten.
  *
  *     a = [ 1, 2, [3, [4, 5] ] ]
@@ -3807,7 +3802,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
  *  Returns a new array that is a one-dimensional flattening of this
  *  array (recursively). That is, for every element that is an array,
  *  extract its elements into the new array.  If the optional
- *  <i>level</i> argument determines the level of recursion to flatten.
+ *  +level+ argument determines the level of recursion to flatten.
  *
  *     s = [ 1, 2, 3 ]           #=> [1, 2, 3]
  *     t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
@@ -4023,7 +4018,7 @@ rb_ary_sample(int argc, VALUE *argv, VALUE ary)
  *     ary.cycle(n=nil) {|obj| block }  -> nil
  *     ary.cycle(n=nil)                 -> an_enumerator
  *
- *  Calls <i>block</i> for each element repeatedly _n_ times or
+ *  Calls +block+ for each element repeatedly +n+ times or
  *  forever if none or +nil+ is given.  If a non-positive number is
  *  given or the array is empty, does nothing.  Returns +nil+ if the
  *  loop has finished without getting interrupted.
@@ -4118,9 +4113,9 @@ permute0(long n, long r, long *p, long index, char *used, VALUE values)
  *     ary.permutation(n) { |p| block }       -> ary
  *     ary.permutation(n)                     -> an_enumerator
  *
- * When invoked with a block, yield all permutations of length <i>n</i>
- * of the elements of <i>ary</i>, then return the array itself.
- * If <i>n</i> is not specified, yield all permutations of all elements.
+ * When invoked with a block, yield all permutations of length +n+
+ * of the elements of the array, then return the array itself.
+ * If +n+ is not specified, yield all permutations of all elements.
  * The implementation makes no guarantees about the order in which
  * the permutations are yielded.
  *
@@ -4182,8 +4177,8 @@ rb_ary_permutation(int argc, VALUE *argv, VALUE ary)
  *     ary.combination(n) { |c| block }    -> ary
  *     ary.combination(n)                  -> an_enumerator
  *
- * When invoked with a block, yields all combinations of length <i>n</i>
- * of elements from <i>ary</i> and then returns <i>ary</i> itself.
+ * When invoked with a block, yields all combinations of length +n+
+ * of elements from the array and then returns the array itself.
  * The implementation makes no guarantees about the order in which
  * the combinations are yielded.
  *
@@ -4295,7 +4290,7 @@ rpermute0(long n, long r, long *p, long index, VALUE values)
  *     ary.repeated_permutation(n)               -> an_enumerator
  *
  * When invoked with a block, yield all repeated permutations of length
- * <i>n</i> of the elements of <i>ary</i>, then return the array itself.
+ * +n+ of the elements of the array, then return the array itself.
  * The implementation makes no guarantees about the order in which
  * the repeated permutations are yielded.
  *
@@ -4374,8 +4369,8 @@ rcombinate0(long n, long r, long *p, long index, long rest, VALUE values)
  *     ary.repeated_combination(n)               -> an_enumerator
  *
  * When invoked with a block, yields all repeated combinations of
- * length <i>n</i> of elements from <i>ary</i> and then returns
- * <i>ary</i> itself.
+ * length +n+ of elements from the array and then returns
+ * the array itself.
  * The implementation makes no guarantees about the order in which
  * the repeated combinations are yielded.
  *
@@ -4438,7 +4433,7 @@ rb_ary_repeated_combination(VALUE ary, VALUE num)
  *  Returns an array of all combinations of elements from all arrays,
  *  The length of the returned array is the product of the length
  *  of +self+ and the argument arrays.
- *  If given a block, <i>product</i> will yield all combinations
+ *  If given a block, #product will yield all combinations
  *  and return +self+ instead.
  *
  *
@@ -4544,7 +4539,7 @@ done:
  *  call-seq:
  *     ary.take(n)               -> new_ary
  *
- *  Returns first n elements from <i>ary</i>.
+ *  Returns first +n+ elements from the array.
  *
  *     a = [1, 2, 3, 4, 5, 0]
  *     a.take(3)             #=> [1, 2, 3]