Correct whitespace in array.c (#5791)

1 files changed, 370 insertions, 10 deletions

diff --git a/array.c b/array.c
index bc904ec420..9bb767d79f 100644
--- a/array.c
+++ b/array.c
@@ -693,6 +693,7 @@ ary_ensure_room_for_push(VALUE ary, long add_len)
  *    array.freeze -> self
  *
  *  Freezes +self+; returns +self+:
+ *
  *    a = []
  *    a.frozen? # => false
  *    a.freeze
@@ -1132,6 +1133,7 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass)
  *
  *  With no block and a single \Array argument +array+,
  *  returns a new \Array formed from +array+:
+ *
  *    a = Array.new([:foo, 'bar', 2])
  *    a.class # => Array
  *    a # => [:foo, "bar", 2]
@@ -1139,12 +1141,14 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass)
  *  With no block and a single \Integer argument +size+,
  *  returns a new \Array of the given size
  *  whose elements are all +nil+:
+ *
  *    a = Array.new(3)
  *    a # => [nil, nil, nil]
  *
  *  With no block and arguments +size+ and +default_value+,
  *  returns an \Array of the given size;
  *  each element is that same +default_value+:
+ *
  *    a = Array.new(3, 'x')
  *    a # => ['x', 'x', 'x']
  *
@@ -1152,6 +1156,7 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass)
  *  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(3) {|index| "Element #{index}" }
  *    a # => ["Element 0", "Element 1", "Element 2"]
  *
@@ -1388,13 +1393,16 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos
  *    array << object -> self
  *
  *  Appends +object+ to +self+; returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a << :baz # => [:foo, "bar", 2, :baz]
  *
  *  Appends +object+ as one element, even if it is another \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a << [3, 4]
  *    a1 # => [:foo, "bar", 2, [3, 4]]
+ *
  */
 
 VALUE
@@ -1427,10 +1435,12 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len)
  *  Appends trailing elements.
  *
  *  Appends each argument in +objects+ to +self+;  returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
  *
  *  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]]
@@ -1474,6 +1484,7 @@ rb_ary_pop(VALUE ary)
  *
  *  When no argument is given and +self+ is not empty,
  *  removes and returns the last element:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.pop # => 2
  *    a # => [:foo, "bar"]
@@ -1481,12 +1492,14 @@ rb_ary_pop(VALUE ary)
  *  Returns +nil+ if the array is empty.
  *
  *  When a non-negative \Integer argument +n+ is given and is in range,
+ *
  *  removes and returns the last +n+ elements in a new \Array:
  *    a = [:foo, 'bar', 2]
  *    a.pop(2) # => ["bar", 2]
  *
  *  If +n+ is positive and out of range,
  *  removes and returns all elements:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.pop(50) # => [:foo, "bar", 2]
  *
@@ -1535,6 +1548,7 @@ rb_ary_shift(VALUE ary)
  *  Removes and returns leading elements.
  *
  *  When no argument is given, removes and returns the first element:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.shift # => :foo
  *    a # => ['bar', 2]
@@ -1543,12 +1557,14 @@ rb_ary_shift(VALUE ary)
  *
  *  When positive \Integer argument +n+ is given, removes the first +n+ elements;
  *  returns those elements in a new \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.shift(2) # => [:foo, 'bar']
  *    a # => [2]
  *
  *  If +n+ is as large as or larger than <tt>self.length</tt>,
  *  removes all elements; returns those elements in a new \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.shift(3) # => [:foo, 'bar', 2]
  *
@@ -1698,6 +1714,7 @@ ary_ensure_room_for_unshift(VALUE ary, int argc)
  *    array.unshift(*objects) -> self
  *
  *  Prepends the given +objects+ to +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
  *
@@ -1791,12 +1808,14 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *  Returns elements from +self+; does not modify +self+.
  *
  *  When a single \Integer argument +index+ is given, returns the element at offset +index+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0] # => :foo
  *    a[2] # => 2
  *    a # => [:foo, "bar", 2]
  *
  *  If +index+ is negative, counts relative to the end of +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[-1] # => 2
  *    a[-2] # => "bar"
@@ -1805,12 +1824,14 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *
  *  When two \Integer arguments +start+ and +length+ are given,
  *  returns a new \Array of size +length+ containing successive elements beginning at offset +start+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0, 2] # => [:foo, "bar"]
  *    a[1, 2] # => ["bar", 2]
  *
  *  If <tt>start + length</tt> is greater than <tt>self.length</tt>,
  *  returns all elements from offset +start+ to the end:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0, 4] # => [:foo, "bar", 2]
  *    a[1, 3] # => ["bar", 2]
@@ -1824,6 +1845,7 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *  When a single \Range argument +range+ is given,
  *  treats <tt>range.min</tt> as +start+ above
  *  and <tt>range.size</tt> as +length+ above:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0..1] # => [:foo, "bar"]
  *    a[1..2] # => ["bar", 2]
@@ -1831,18 +1853,21 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *  Special case: If <tt>range.start == a.size</tt>, returns a new empty \Array.
  *
  *  If <tt>range.end</tt> is negative, calculates the end index from the end:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0..-1] # => [:foo, "bar", 2]
  *    a[0..-2] # => [:foo, "bar"]
  *    a[0..-3] # => [:foo]
  *
  *  If <tt>range.start</tt> is negative, calculates the start index from the end:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[-1..2] # => [2]
  *    a[-2..2] # => ["bar", 2]
  *    a[-3..2] # => [:foo, "bar", 2]
  *
  *  If <tt>range.start</tt> is larger than the array size, returns +nil+.
+ *
  *    a = [:foo, 'bar', 2]
  *    a[4..1] # => nil
  *    a[4..0] # => nil
@@ -1851,11 +1876,13 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *  When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
  *  returns an \Array of elements corresponding to the indexes produced by
  *  the sequence.
+ *
  *    a = ['--', 'data1', '--', 'data2', '--', 'data3']
  *    a[(1..).step(2)] # => ["data1", "data2", "data3"]
  *
  *  Unlike slicing with range, if the start or the end of the arithmetic sequence
  *  is larger than array size, throws RangeError.
+ *
  *    a = ['--', 'data1', '--', 'data2', '--', 'data3']
  *    a[(1..11).step(2)]
  *    # RangeError (((1..11).step(2)) out of range)
@@ -1864,6 +1891,7 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e);
  *
  *  If given a single argument, and its type is not one of the listed, tries to
  *  convert it to Integer, and raises if it is impossible:
+ *
  *    a = [:foo, 'bar', 2]
  *    # Raises TypeError (no implicit conversion of Symbol into Integer):
  *    a[:foo]
@@ -1922,6 +1950,7 @@ rb_ary_aref1(VALUE ary, VALUE arg)
  *    a = [:foo, 'bar', 2]
  *    a.at(0) # => :foo
  *    a.at(2) # => 2
+ *
  */
 
 VALUE
@@ -1938,6 +1967,7 @@ rb_ary_at(VALUE ary, VALUE pos)
  *  Returns elements from +self+; does not modify +self+.
  *
  *  When no argument is given, returns the first element:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.first # => :foo
  *    a # => [:foo, "bar", 2]
@@ -1946,14 +1976,17 @@ rb_ary_at(VALUE ary, VALUE pos)
  *
  *  When non-negative \Integer argument +n+ is given,
  *  returns the first +n+ elements in a new \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.first(2) # => [:foo, "bar"]
  *
  *  If <tt>n >= array.size</tt>, returns all elements:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.first(50) # => [:foo, "bar", 2]
  *
  *  If <tt>n == 0</tt> returns an new empty \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.first(0) # []
  *
@@ -1979,6 +2012,7 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary)
  *  Returns elements from +self+; +self+ is not modified.
  *
  *  When no argument is given, returns the last element:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.last # => 2
  *    a # => [:foo, "bar", 2]
@@ -1987,14 +2021,17 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary)
  *
  *  When non-negative \Innteger argument +n+ is given,
  *  returns the last +n+ elements in a new \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.last(2) # => ["bar", 2]
  *
  *  If <tt>n >= array.size</tt>, returns all elements:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.last(50) # => [:foo, "bar", 2]
  *
  *  If <tt>n == 0</tt>, returns an new empty \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.last(0) # []
  *
@@ -2024,10 +2061,12 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary)
  *
  *  With the single \Integer argument +index+,
  *  returns the element at offset +index+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.fetch(1) # => "bar"
  *
  *  If +index+ is negative, counts from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.fetch(-1) # => 2
  *    a.fetch(-2) # => "bar"
@@ -2035,6 +2074,7 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary)
  *  With arguments +index+ and +default_value+,
  *  returns the element at offset +index+ if index is in range,
  *  otherwise returns +default_value+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.fetch(1, nil) # => "bar"
  *
@@ -2045,6 +2085,7 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary)
  *    a = [:foo, 'bar', 2]
  *    a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
  *    a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
+ *
  */
 
 static VALUE
@@ -2086,6 +2127,7 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
  *  When argument +object+ is given but no block,
  *  returns the index of the first element +element+
  *  for which <tt>object == element</tt>:
+ *
  *    a = [:foo, 'bar', 2, 'bar']
  *    a.index('bar') # => 1
  *
@@ -2094,12 +2136,14 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
  *  When both argument +object+ and a block are given,
  *  calls the block with each successive element;
  *  returns the index of the first element for which the block returns a truthy value:
+ *
  *    a = [:foo, 'bar', 2, 'bar']
  *    a.index {|element| element == 'bar' } # => 1
  *
  *  Returns +nil+ if the block never returns a truthy value.
  *
  *  When neither an argument nor a block is given, returns a new Enumerator:
+ *
  *    a = [:foo, 'bar', 2]
  *    e = a.index
  *    e # => #<Enumerator: [:foo, "bar", 2]:index>
@@ -2147,6 +2191,7 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary)
  *  Returns the index of the last element for which <tt>object == element</tt>.
  *
  *  When argument +object+ is given but no block, returns the index of the last such element found:
+ *
  *    a = [:foo, 'bar', 2, 'bar']
  *    a.rindex('bar') # => 3
  *
@@ -2154,6 +2199,7 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary)
  *
  *  When a block is given but no argument, calls the block with each successive element;
  *  returns the index of the last element for which the block returns a truthy value:
+ *
  *    a = [:foo, 'bar', 2, 'bar']
  *    a.rindex {|element| element == 'bar' } # => 3
  *
@@ -2368,16 +2414,19 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val)
  *  When \Integer argument +index+ is given, assigns +object+ to an element in +self+.
  *
  *  If +index+ is non-negative, assigns +object+ the element at offset +index+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0] = 'foo' # => "foo"
  *    a # => ["foo", "bar", 2]
  *
  *  If +index+ is greater than <tt>self.length</tt>, extends the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[7] = 'foo' # => "foo"
  *    a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
  *
  *  If +index+ is negative, counts backwards from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[-1] = 'two' # => "two"
  *    a # => [:foo, "bar", "two"]
@@ -2385,11 +2434,13 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val)
  *  When \Integer arguments +start+ and +length+ are given and +object+ is not an \Array,
  *  removes <tt>length - 1</tt> elements beginning at offset +start+,
  *  and assigns +object+ at offset +start+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0, 2] = 'foo' # => "foo"
  *    a # => ["foo", 2]
  *
  *  If +start+ is negative, counts backwards from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[-2, 2] = 'foo' # => "foo"
  *    a # => [:foo, "foo"]
@@ -2397,17 +2448,20 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val)
  *  If +start+ is non-negative and outside the array (<tt> >= self.size</tt>),
  *  extends the array with +nil+, assigns +object+ at offset +start+,
  *  and ignores +length+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[6, 50] = 'foo' # => "foo"
  *    a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
  *
  *  If +length+ is zero, shifts elements at and following offset +start+
  *  and assigns +object+ at offset +start+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[1, 0] = 'foo' # => "foo"
  *    a # => [:foo, "foo", "bar", 2]
  *
  *  If +length+ is too large for the existing array, does not extend the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[1, 5] = 'foo' # => "foo"
  *    a # => [:foo, "foo"]
@@ -2415,29 +2469,34 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val)
  *  When \Range argument +range+ is given and +object+ is an \Array,
  *  removes <tt>length - 1</tt> elements beginning at offset +start+,
  *  and assigns +object+ at offset +start+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[0..1] = 'foo' # => "foo"
  *    a # => ["foo", 2]
  *
  *  if <tt>range.begin</tt> is negative, counts backwards from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[-2..2] = 'foo' # => "foo"
  *    a # => [:foo, "foo"]
  *
  *  If the array length is less than <tt>range.begin</tt>,
  *  assigns +object+ at offset <tt>range.begin</tt>, and ignores +length+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[6..50] = 'foo' # => "foo"
  *    a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
  *
  *  If <tt>range.end</tt> is zero, shifts elements at and following offset +start+
  *  and assigns +object+ at offset +start+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[1..0] = 'foo' # => "foo"
  *    a # => [:foo, "foo", "bar", 2]
  *
  *  If <tt>range.end</tt> is negative, assigns +object+ at offset +start+,
  *  retains <tt>range.end.abs -1</tt> elements past that, and removes those beyond:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[1..-1] = 'foo' # => "foo"
  *    a # => [:foo, "foo"]
@@ -2451,9 +2510,11 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val)
  *
  *  If <tt>range.end</tt> is too large for the existing array,
  *  replaces array elements, but does not extend the array with +nil+ values:
+ *
  *    a = [:foo, 'bar', 2]
  *    a[1..5] = 'foo' # => "foo"
  *    a # => [:foo, "foo"]
+ *
  */
 
 static VALUE
@@ -2490,15 +2551,18 @@ rb_ary_aset(int argc, VALUE *argv, VALUE ary)
  *
  *  When +index+ is non-negative, inserts all given +objects+
  *  before the element at offset +index+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2]
  *
  *  Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
+ *
  *    a = [:foo, 'bar', 2]
  *    a.insert(5, :bat, :bam)
  *    a # => [:foo, "bar", 2, nil, nil, :bat, :bam]
  *
  *  Does nothing if no objects given:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.insert(1)
  *    a.insert(50)
@@ -2507,9 +2571,11 @@ rb_ary_aset(int argc, VALUE *argv, VALUE ary)
  *
  *  When +index+ is negative, inserts all given +objects+
  *  _after_ the element at offset <tt>index+self.size</tt>:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.insert(-2, :bat, :bam)
  *    a # => [:foo, "bar", :bat, :bam, 2]
+ *
  */
 
 static VALUE
@@ -2554,29 +2620,35 @@ ary_enum_length(VALUE ary, VALUE args, VALUE eobj)
  *
  *  When a block given, passes each successive array element to the block;
  *  returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.each {|element|  puts "#{element.class} #{element}" }
  *
  *  Output:
+ *
  *    Symbol foo
  *    String bar
  *    Integer 2
  *
  *  Allows the array to be modified during iteration:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }
  *
  *  Output:
+ *
  *    foo
  *    bar
  *
  *  When no block given, returns a new \Enumerator:
  *    a = [:foo, 'bar', 2]
+ *
  *    e = a.each
  *    e # => #<Enumerator: [:foo, "bar", 2]:each>
  *    a1 = e.each {|element|  puts "#{element.class} #{element}" }
  *
  *  Output:
+ *
  *    Symbol foo
  *    String bar
  *    Integer 2
@@ -2605,29 +2677,35 @@ rb_ary_each(VALUE ary)
  *
  *  When a block given, passes each successive array index to the block;
  *  returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.each_index {|index|  puts "#{index} #{a[index]}" }
  *
  *  Output:
+ *
  *    0 foo
  *    1 bar
  *    2 2
  *
  *  Allows the array to be modified during iteration:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.each_index {|index| puts index; a.clear if index > 0 }
  *
  *  Output:
+ *
  *    0
  *    1
  *
  *  When no block given, returns a new \Enumerator:
+ *
  *    a = [:foo, 'bar', 2]
  *    e = a.each_index
  *    e # => #<Enumerator: [:foo, "bar", 2]:each_index>
  *    a1 = e.each {|index|  puts "#{index} #{a[index]}"}
  *
  *  Output:
+ *
  *    0 foo
  *    1 bar
  *    2 2
@@ -2656,28 +2734,35 @@ rb_ary_each_index(VALUE ary)
  *
  *  When a block given, passes, in reverse order, each element to the block;
  *  returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.reverse_each {|element|  puts "#{element.class} #{element}" }
  *
  *  Output:
+ *
  *    Integer 2
  *    String bar
  *    Symbol foo
  *
  *  Allows the array to be modified during iteration:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }
  *
  *  Output:
+ *
  *    2
  *    bar
  *
  *  When no block given, returns a new \Enumerator:
+ *
  *    a = [:foo, 'bar', 2]
  *    e = a.reverse_each
  *    e # => #<Enumerator: [:foo, "bar", 2]:reverse_each>
  *    a1 = e.each {|element|  puts "#{element.class} #{element}" }
+ *
  *  Output:
+ *
  *    Integer 2
  *    String bar
  *    Symbol foo
@@ -2890,22 +2975,27 @@ rb_ary_join(VALUE ary, VALUE sep)
  *    array.join(separator = $,) -> new_string
  *
  *  Returns the new \String formed by joining the array elements after conversion.
- *  For each element +element+
+ *  For each element +element+:
+ *
  *  - Uses <tt>element.to_s</tt> if +element+ is not a <tt>kind_of?(Array)</tt>.
  *  - Uses recursive <tt>element.join(separator)</tt> if +element+ is a <tt>kind_of?(Array)</tt>.
  *
  *  With no argument, joins using the output field separator, <tt>$,</tt>:
+ *
  *    a = [:foo, 'bar', 2]
  *    $, # => nil
  *    a.join # => "foobar2"
  *
  *  With \string argument +separator+, joins using that separator:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.join("\n") # => "foo\nbar\n2"
  *
  *  Joins recursively for nested Arrays:
+ *
  *   a = [:foo, [:bar, [:baz, :bat]]]
  *   a.join # => "foobarbazbat"
+ *
  */
 static VALUE
 rb_ary_join_m(int argc, VALUE *argv, VALUE ary)
@@ -2946,6 +3036,7 @@ inspect_ary(VALUE ary, VALUE dummy, int recur)
  *
  *  Returns the new \String formed by calling method <tt>#inspect</tt>
  *  on each array element:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.inspect # => "[:foo, \"bar\", 2]"
  *
@@ -2970,10 +3061,12 @@ rb_ary_to_s(VALUE ary)
  *    to_a -> self or new_array
  *
  *  When +self+ is an instance of \Array, returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.to_a # => [:foo, "bar", 2]
  *
  *  Otherwise, returns a new \Array containing the elements of +self+:
+ *
  *    class MyArray < Array; end
  *    a = MyArray.new(['foo', 'bar', 'two'])
  *    a.instance_of?(Array) # => false
@@ -2981,6 +3074,7 @@ rb_ary_to_s(VALUE ary)
  *    a1 = a.to_a
  *    a1 # => ["foo", "bar", "two"]
  *    a1.class # => Array # Not MyArray
+ *
  */
 
 static VALUE
@@ -3004,16 +3098,19 @@ rb_ary_to_a(VALUE ary)
  *  When a block is given, calls the block with each array element;
  *  the block must return a 2-element \Array whose two elements
  *  form a key-value pair in the returned \Hash:
+ *
  *    a = ['foo', :bar, 1, [2, 3], {baz: 4}]
  *    h = a.to_h {|item| [item, item] }
  *    h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}
  *
  *  When no block is given, +self+ must be an \Array of 2-element sub-arrays,
  *  each sub-array is formed into a key-value pair in the new \Hash:
+ *
  *    [].to_h # => {}
  *    a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
  *    h = a.to_h
  *    h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
+ *
  */
 
 static VALUE
@@ -3084,8 +3181,10 @@ rb_ary_reverse(VALUE ary)
  *    array.reverse! -> self
  *
  *  Reverses +self+ in place:
+ *
  *    a = ['foo', 'bar', 'two']
  *    a.reverse! # => ["two", "bar", "foo"]
+ *
  */
 
 static VALUE
@@ -3098,10 +3197,12 @@ rb_ary_reverse_bang(VALUE ary)
  *  call-seq:
  *    array.reverse -> new_array
  *
- *  Returns a new \Array with the elements of +self+ in reverse order.
+ *  Returns a new \Array with the elements of +self+ in reverse order:
+ *
  *    a = ['foo', 'bar', 'two']
  *    a1 = a.reverse
  *    a1 # => ["two", "bar", "foo"]
+ *
  */
 
 static VALUE
@@ -3169,35 +3270,42 @@ rb_ary_rotate(VALUE ary, long cnt)
  *  Rotates +self+ in place by moving elements from one end to the other; returns +self+.
  *
  *  When no argument given, rotates the first element to the last position:
+ *
  *    a = [:foo, 'bar', 2, 'bar']
  *    a.rotate! # => ["bar", 2, "bar", :foo]
  *
  *  When given a non-negative \Integer +count+,
  *  rotates +count+ elements from the beginning to the end:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.rotate!(2)
  *    a # => [2, :foo, "bar"]
  *
  *  If +count+ is large, uses <tt>count % array.size</tt> as the count:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.rotate!(20)
  *    a # => [2, :foo, "bar"]
  *
  *  If +count+ is zero, returns +self+ unmodified:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.rotate!(0)
  *    a # => [:foo, "bar", 2]
  *
  *  When given a negative Integer +count+, rotates in the opposite direction,
  *  from end to beginning:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.rotate!(-2)
  *    a # => ["bar", 2, :foo]
  *
  *  If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.rotate!(-5)
  *    a # => ["bar", 2, :foo]
+ *
  */
 
 static VALUE
@@ -3218,36 +3326,43 @@ rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary)
  *
  *  When no argument given, returns a new \Array that is like +self+,
  *  except that the first element has been rotated to the last position:
+ *
  *    a = [:foo, 'bar', 2, 'bar']
  *    a1 = a.rotate
  *    a1 # => ["bar", 2, "bar", :foo]
  *
  *  When given a non-negative \Integer +count+,
  *  returns a new \Array with +count+ elements rotated from the beginning to the end:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.rotate(2)
  *    a1 # => [2, :foo, "bar"]
  *
  *  If +count+ is large, uses <tt>count % array.size</tt> as the count:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.rotate(20)
  *    a1 # => [2, :foo, "bar"]
  *
  *  If +count+ is zero, returns a copy of +self+, unmodified:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.rotate(0)
  *    a1 # => [:foo, "bar", 2]
  *
  *  When given a negative \Integer +count+, rotates in the opposite direction,
  *  from end to beginning:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.rotate(-2)
  *    a1 # => ["bar", 2, :foo]
  *
  *  If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.rotate(-5)
  *    a1 # => ["bar", 2, :foo]
+ *
  */
 
 static VALUE
@@ -3348,6 +3463,7 @@ sort_2(const void *ap, const void *bp, void *dummy)
  *
  *  With no block, compares elements using operator <tt><=></tt>
  *  (see Comparable):
+ *
  *    a = 'abcde'.split('').shuffle
  *    a # => ["e", "b", "d", "a", "c"]
  *    a.sort!
@@ -3355,11 +3471,13 @@ sort_2(const void *ap, const void *bp, void *dummy)
  *
  *  With a block, calls the block with each element pair;
  *  for each element pair +a+ and +b+, the block should return an integer:
+ *
  *  - Negative when +b+ is to follow +a+.
  *  - Zero when +a+ and +b+ are equivalent.
  *  - Positive when +a+ is to follow +b+.
  *
  *  Example:
+ *
  *    a = 'abcde'.split('').shuffle
  *    a # => ["e", "b", "d", "a", "c"]
  *    a.sort! {|a, b| a <=> b }
@@ -3369,10 +3487,12 @@ sort_2(const void *ap, const void *bp, void *dummy)
  *
  *  When the block returns zero, the order for +a+ and +b+ is indeterminate,
  *  and may be unstable:
+ *
  *    a = 'abcde'.split('').shuffle
  *    a # => ["e", "b", "d", "a", "c"]
  *    a.sort! {|a, b| 0 }
  *    a # => ["d", "e", "c", "a", "b"]
+ *
  */
 
 VALUE
@@ -3445,6 +3565,7 @@ rb_ary_sort_bang(VALUE ary)
  *
  *  With no block, compares elements using operator <tt><=></tt>
  *  (see Comparable):
+ *
  *    a = 'abcde'.split('').shuffle
  *    a # => ["e", "b", "d", "a", "c"]
  *    a1 = a.sort
@@ -3452,11 +3573,13 @@ rb_ary_sort_bang(VALUE ary)
  *
  *  With a block, calls the block with each element pair;
  *  for each element pair +a+ and +b+, the block should return an integer:
+ *
  *  - Negative when +b+ is to follow +a+.
  *  - Zero when +a+ and +b+ are equivalent.
  *  - Positive when +a+ is to follow +b+.
  *
  *  Example:
+ *
  *    a = 'abcde'.split('').shuffle
  *    a # => ["e", "b", "d", "a", "c"]
  *    a1 = a.sort {|a, b| a <=> b }
@@ -3466,6 +3589,7 @@ rb_ary_sort_bang(VALUE ary)
  *
  *  When the block returns zero, the order for +a+ and +b+ is indeterminate,
  *  and may be unstable:
+ *
  *    a = 'abcde'.split('').shuffle
  *    a # => ["e", "b", "d", "a", "c"]
  *    a1 = a.sort {|a, b| 0 }
@@ -3582,6 +3706,7 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy))
  *  For duplicates returned by the block, the ordering is indeterminate, and may be unstable.
  *
  *  This example sorts strings based on their sizes:
+ *
  *    a = ['aaaa', 'bbb', 'cc', 'd']
  *    a.sort_by! {|element| element.size }
  *    a # => ["d", "cc", "bbb", "aaaa"]
@@ -3590,6 +3715,7 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy))
  *
  *    a = ['aaaa', 'bbb', 'cc', 'd']
  *    a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
+ *
  */
 
 static VALUE
@@ -3612,6 +3738,7 @@ rb_ary_sort_by_bang(VALUE ary)
  *
  *  Calls the block, if given, with each element of +self+;
  *  returns a new \Array whose elements are the return values from the block:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.map {|element| element.class }
  *    a1 # => [Symbol, String, Integer]
@@ -3646,10 +3773,12 @@ rb_ary_collect(VALUE ary)
  *
  *  Calls the block, if given, with each element;
  *  replaces the element with the block's return value:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.map! { |element| element.class } # => [Symbol, String, Integer]
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [:foo, 'bar', 2]
  *    a1 = a.map!
  *    a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
@@ -3732,32 +3861,39 @@ append_values_at_single(VALUE result, VALUE ary, long olen, VALUE idx)
  *  of +self+ at the given \Integer or \Range +indexes+.
  *
  *  For each positive +index+, returns the element at offset +index+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.values_at(0, 2) # => [:foo, 2]
  *    a.values_at(0..1) # => [:foo, "bar"]
  *
  *  The given +indexes+ may be in any order, and may repeat:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
  *    a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
  *
  *  Assigns +nil+ for an +index+ that is too large:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
  *
  *  Returns a new empty \Array if no arguments given.
  *
  *  For each negative +index+, counts backward from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.values_at(-1, -3) # => [2, :foo]
  *
  *  Assigns +nil+ for an +index+ that is too small:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
  *
  *  The given +indexes+ may have a mixture of signs:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
+ *
  */
 
 static VALUE
@@ -3781,11 +3917,13 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
  *  Calls the block, if given, with each element of +self+;
  *  returns a new \Array containing those elements of +self+
  *  for which the block returns a truthy value:
+ *
  *    a = [:foo, 'bar', 2, :bam]
  *    a1 = a.select {|element| element.to_s.start_with?('b') }
  *    a1 # => ["bar", :bam]
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [:foo, 'bar', 2, :bam]
  *    a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
  *
@@ -3862,12 +4000,14 @@ select_bang_ensure(VALUE a)
  *  removes from +self+ those elements for which the block returns +false+ or +nil+.
  *
  *  Returns +self+ if any elements were removed:
+ *
  *    a = [:foo, 'bar', 2, :bam]
  *    a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
  *
  *  Returns +nil+ if no elements were removed.
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [:foo, 'bar', 2, :bam]
  *    a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
  *
@@ -3894,12 +4034,15 @@ rb_ary_select_bang(VALUE ary)
  *
  *  Retains those elements for which the block returns a truthy value;
  *  deletes all other elements; returns +self+:
+ *
  *    a = [:foo, 'bar', 2, :bam]
  *    a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [:foo, 'bar', 2, :bam]
  *    a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>
+ *
  */
 
 static VALUE
@@ -3933,6 +4076,7 @@ ary_resize_smaller(VALUE ary, long len)
  *  When no block is given,
  *  removes from +self+ each element +ele+ such that <tt>ele == obj</tt>;
  *  returns the last deleted element:
+ *
  *    s1 = 'bar'; s2 = 'bar'
  *    a = [:foo, s1, 2, s2]
  *    a.delete('bar') # => "bar"
@@ -3945,14 +4089,17 @@ ary_resize_smaller(VALUE ary, long len)
  *
  *  If any such elements are found, ignores the block
  *  and returns the last deleted element:
+ *
  *    s1 = 'bar'; s2 = 'bar'
  *    a = [:foo, s1, 2, s2]
  *    deleted_obj = a.delete('bar') {|obj| fail 'Cannot happen' }
  *    a # => [:foo, 2]
  *
  *  If no such elements are found, returns the block's return value:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.delete(:nosuch) {|obj| "#{obj} not found" } # => "nosuch not found"
+ *
  */
 
 VALUE
@@ -4038,6 +4185,7 @@ rb_ary_delete_at(VALUE ary, long pos)
  *  Deletes an element from +self+, per the given \Integer +index+.
  *
  *  When +index+ is non-negative, deletes the element at offset +index+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.delete_at(1) # => "bar"
  *    a # => [:foo, 2]
@@ -4045,6 +4193,7 @@ rb_ary_delete_at(VALUE ary, long pos)
  *  If index is too large, returns +nil+.
  *
  *  When +index+ is negative, counts backward from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.delete_at(-2) # => "bar"
  *    a # => [:foo, 2]
@@ -4098,11 +4247,13 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len)
  *
  *  When the only argument is an \Integer +n+,
  *  removes and returns the _nth_ element in +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.slice!(1) # => "bar"
  *    a # => [:foo, 2]
  *
  *  If +n+ is negative, counts backwards from the end of +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.slice!(-1) # => 2
  *    a # => [:foo, "bar"]
@@ -4112,12 +4263,14 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len)
  *  When the only arguments are Integers +start+ and +length+,
  *  removes +length+ elements from +self+ beginning at offset  +start+;
  *  returns the deleted objects in a new \Array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.slice!(0, 2) # => [:foo, "bar"]
  *    a # => [2]
  *
  *  If <tt>start + length</tt> exceeds the array size,
  *  removes and returns all elements from offset +start+ to the end:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.slice!(1, 50) # => ["bar", 2]
  *    a # => [:foo]
@@ -4129,8 +4282,9 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len)
  *
  *  When the only argument is a \Range object +range+,
  *  treats <tt>range.min</tt> as +start+ above and <tt>range.size</tt> as +length+ above:
+ *
  *    a = [:foo, 'bar', 2]
- *     a.slice!(1..2) # => ["bar", 2]
+ *    a.slice!(1..2) # => ["bar", 2]
  *    a # => [:foo]
  *
  *  If <tt>range.start == a.size</tt>, returns a new empty \Array.
@@ -4138,15 +4292,18 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len)
  *  If <tt>range.start</tt> is larger than the array size, returns +nil+.
  *
  *  If <tt>range.end</tt> is negative, counts backwards from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.slice!(0..-2) # => [:foo, "bar"]
  *    a # => [2]
  *
  *  If <tt>range.start</tt> is negative,
  *  calculates the start index backwards from the end of the array:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.slice!(-2..2) # => ["bar", 2]
  *    a # => [:foo]
+ *
  */
 
 static VALUE
@@ -4233,14 +4390,17 @@ ary_reject_bang(VALUE ary)
  *  Removes each element for which the block returns a truthy value.
  *
  *  Returns +self+ if any elements removed:
+ *
  *    a = [:foo, 'bar', 2, 'bat']
  *    a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
  *
  *  Returns +nil+ if no elements removed.
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>
+ *
  */
 
 static VALUE
@@ -4258,13 +4418,16 @@ rb_ary_reject_bang(VALUE ary)
  *
  *  Returns a new \Array whose elements are all those from +self+
  *  for which the block returns +false+ or +nil+:
+ *
  *    a = [:foo, 'bar', 2, 'bat']
  *    a1 = a.reject {|element| element.to_s.start_with?('b') }
  *    a1 # => [:foo, 2]
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *     a = [:foo, 'bar', 2]
  *     a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>
+ *
  */
 
 static VALUE
@@ -4285,13 +4448,16 @@ rb_ary_reject(VALUE ary)
  *
  *  Removes each element in +self+ for which the block returns a truthy value;
  *  returns +self+:
+ *
  *    a = [:foo, 'bar', 2, 'bat']
  *    a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>
- */
+ *
+3 */
 
 static VALUE
 rb_ary_delete_if(VALUE ary)
@@ -4339,10 +4505,12 @@ take_items(VALUE obj, long n)
  *
  *  Each nested array <tt>new_array[n]</tt> is of size <tt>other_arrays.size+1</tt>,
  *  and contains:
+ *
  *  - The _nth_ element of +self+.
  *  - The _nth_ element of each of the +other_arrays+.
  *
  *  If all +other_arrays+ and +self+ are the same size:
+ *
  *    a = [:a0, :a1, :a2, :a3]
  *    b = [:b0, :b1, :b2, :b3]
  *    c = [:c0, :c1, :c2, :c3]
@@ -4351,6 +4519,7 @@ take_items(VALUE obj, long n)
  *
  *  If any array in +other_arrays+ is smaller than +self+,
  *  fills to <tt>self.size</tt> with +nil+:
+ *
  *    a = [:a0, :a1, :a2, :a3]
  *    b = [:b0, :b1, :b2]
  *    c = [:c0, :c1]
@@ -4359,23 +4528,27 @@ take_items(VALUE obj, long n)
  *
  *  If any array in +other_arrays+ is larger than +self+,
  *  its trailing elements are ignored:
+ *
  *    a = [:a0, :a1, :a2, :a3]
  *    b = [:b0, :b1, :b2, :b3, :b4]
  *    c = [:c0, :c1, :c2, :c3, :c4, :c5]
  *    d = a.zip(b, c)
  *    d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
  *
- *  When a block is given, calls the block with each of the sub-arrays (formed as above); returns nil
+ *  When a block is given, calls the block with each of the sub-arrays (formed as above); returns +nil+:
+ *
  *    a = [:a0, :a1, :a2, :a3]
  *    b = [:b0, :b1, :b2, :b3]
  *    c = [:c0, :c1, :c2, :c3]
  *    a.zip(b, c) {|sub_array| p sub_array} # => nil
  *
  *  Output:
+ *
  *    [:a0, :b0, :c0]
  *    [:a1, :b1, :c1]
  *    [:a2, :b2, :c2]
  *    [:a3, :b3, :c3]
+ *
  */
 
 static VALUE
@@ -4442,8 +4615,10 @@ rb_ary_zip(int argc, VALUE *argv, VALUE ary)
  *
  *  Transposes the rows and columns in an \Array of Arrays;
  *  the nested Arrays must all be the same size:
+ *
  *    a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
  *    a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
+ *
  */
 
 static VALUE
@@ -4479,8 +4654,10 @@ rb_ary_transpose(VALUE ary)
  *    array.replace(other_array) -> self
  *
  *  Replaces the content of +self+ with the content of +other_array+; returns +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3]
+ *
  */
 
 VALUE
@@ -4531,8 +4708,10 @@ rb_ary_replace(VALUE copy, VALUE orig)
  *     array.clear -> self
  *
  *  Removes all elements from +self+:
+ *
  *    a = [:foo, 'bar', 2]
  *    a.clear # => []
+ *
  */
 
 VALUE
@@ -4570,6 +4749,7 @@ rb_ary_clear(VALUE ary)
  *  Replaces specified elements in +self+ with specified objects; returns +self+.
  *
  *  With argument +obj+ and no block given, replaces all elements with that one object:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a # => ["a", "b", "c", "d"]
  *    a.fill(:X) # => [:X, :X, :X, :X]
@@ -4579,20 +4759,24 @@ rb_ary_clear(VALUE ary)
  *
  *  If +start+ is in range (<tt>0 <= start < array.size</tt>),
  *  replaces all elements from offset +start+ through the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 2) # => ["a", "b", :X, :X]
  *
  *  If +start+ is too large (<tt>start >= array.size</tt>), does nothing:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 4) # => ["a", "b", "c", "d"]
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 5) # => ["a", "b", "c", "d"]
  *
  *  If +start+ is negative, counts from the end (starting index is <tt>start + array.size</tt>):
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, -2) # => ["a", "b", :X, :X]
  *
  *  If +start+ is too small (less than and far from zero), replaces all elements:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, -6) # => [:X, :X, :X, :X]
  *    a = ['a', 'b', 'c', 'd']
@@ -4602,20 +4786,24 @@ rb_ary_clear(VALUE ary)
  *  replaces elements based on the given +start+ and +length+.
  *
  *  If +start+ is in range, replaces +length+ elements beginning at offset +start+:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]
  *
  *  If +start+ is negative, counts from the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]
  *
  *  If +start+ is large (<tt>start >= array.size</tt>), extends +self+ with +nil+:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]
  *
  *  If +length+ is zero or negative, replaces no elements:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]
  *    a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]
@@ -4625,14 +4813,17 @@ rb_ary_clear(VALUE ary)
  *
  *  If the range is positive and ascending (<tt>0 < range.begin <= range.end</tt>),
  *  replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]
  *
  *  If <tt>range.first</tt> is negative, replaces no elements:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]
  *
  *  If <tt>range.last</tt> is negative, counts from the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]
  *    a = ['a', 'b', 'c', 'd']
@@ -4640,6 +4831,7 @@ rb_ary_clear(VALUE ary)
  *
  *  If <tt>range.last</tt> and <tt>range.last</tt> are both negative,
  *  both count from the end of the array:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]
  *    a = ['a', 'b', 'c', 'd']
@@ -4647,29 +4839,34 @@ rb_ary_clear(VALUE ary)
  *
  *  With no arguments and a block given, calls the block with each index;
  *  replaces the corresponding element with the block's return value:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
  *
  *  With argument +start+ and a block given, calls the block with each index
  *  from offset +start+ to the end; replaces the corresponding element
- *  with the block's return value:
+ *  with the block's return value.
  *
  *  If start is in range (<tt>0 <= start < array.size</tt>),
  *  replaces from offset +start+ to the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]
  *
  *  If +start+ is too large(<tt>start >= array.size</tt>), does nothing:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
  *
  *  If +start+ is negative, counts from the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]
  *
  *  If start is too small (<tt>start <= -array.size</tt>, replaces all elements:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
  *    a = ['a', 'b', 'c', 'd']
@@ -4680,20 +4877,24 @@ rb_ary_clear(VALUE ary)
  *  replaces the corresponding element with the block's return value.
  *
  *  If +start+ is in range, replaces +length+ elements beginning at offset +start+:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
  *
  *  If start is negative, counts from the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
  *
  *  If +start+ is large (<tt>start >= array.size</tt>), extends +self+ with +nil+:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]
  *
  *  If +length+ is zero or less, replaces no elements:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
  *    a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
@@ -4704,14 +4905,17 @@ rb_ary_clear(VALUE ary)
  *
  *  If the range is positive and ascending (<tt>range 0 < range.begin <= range.end</tt>,
  *  replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
  *
  *  If +range.first+ is negative, does nothing:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
  *
  *  If <tt>range.last</tt> is negative, counts from the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"]
  *    a = ['a', 'b', 'c', 'd']
@@ -4719,10 +4923,12 @@ rb_ary_clear(VALUE ary)
  *
  *  If <tt>range.first</tt> and <tt>range.last</tt> are both negative,
  *  both count from the end:
+ *
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]
  *    a = ['a', 'b', 'c', 'd']
  *    a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
+ *
  */
 
 static VALUE
@@ -4795,6 +5001,7 @@ rb_ary_fill(int argc, VALUE *argv, VALUE ary)
  *
  *  Returns a new \Array containing all elements of +array+
  *  followed by all elements of +other_array+:
+ *
  *    a = [0, 1] + [2, 3]
  *    a # => [0, 1, 2, 3]
  *
@@ -4835,6 +5042,7 @@ ary_append(VALUE x, VALUE y)
  *    array.concat(*other_arrays) -> self
  *
  *  Adds to +array+ all elements from each \Array in +other_arrays+; returns +self+:
+ *
  *    a = [0, 1]
  *    a.concat([2, 3], [4, 5]) # => [0, 1, 2, 3, 4, 5]
  */
@@ -4873,12 +5081,15 @@ rb_ary_concat(VALUE x, VALUE y)
  *
  *  When non-negative argument \Integer +n+ is given,
  *  returns a new \Array built by concatenating the +n+ copies of +self+:
+ *
  *    a = ['x', 'y']
  *    a * 3 # => ["x", "y", "x", "y", "x", "y"]
  *
  *  When \String argument +string_separator+ is given,
  *  equivalent to <tt>array.join(string_separator)</tt>:
+ *
  *    [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
+ *
  */
 
 static VALUE
@@ -4931,6 +5142,7 @@ rb_ary_times(VALUE ary, VALUE times)
  *
  *  Returns the first element in +self+ that is an \Array
  *  whose first element <tt>==</tt> +obj+:
+ *
  *    a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
  *    a.assoc(4) # => [4, 5, 6]
  *
@@ -4960,6 +5172,7 @@ rb_ary_assoc(VALUE ary, VALUE key)
  *
  *  Returns the first element in +self+ that is an \Array
  *  whose second element <tt>==</tt> +obj+:
+ *
  *    a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
  *    a.rassoc(4) # => [2, 4]
  *
@@ -5024,6 +5237,7 @@ recursive_equal(VALUE ary1, VALUE ary2, int recur)
  *
  *  Returns +true+ if both <tt>array.size == other_array.size</tt>
  *  and for each index +i+ in +array+, <tt>array[i] == other_array[i]</tt>:
+ *
  *    a0 = [:foo, 'bar', 2]
  *    a1 = [:foo, 'bar', 2.0]
  *    a1 == a0 # => true
@@ -5069,6 +5283,7 @@ recursive_eql(VALUE ary1, VALUE ary2, int recur)
  *
  *  Returns +true+ if +self+ and +other_array+ are the same size,
  *  and if, for each index +i+ in +self+, <tt>self[i].eql? other_array[i]</tt>:
+ *
  *    a0 = [:foo, 'bar', 2]
  *    a1 = [:foo, 'bar', 2]
  *    a1.eql?(a0) # => true
@@ -5096,8 +5311,10 @@ rb_ary_eql(VALUE ary1, VALUE ary2)
  *  Returns the integer hash value for +self+.
  *
  *  Two arrays with the same content will have the same hash code (and will compare using eql?):
+ *
  *    [0, 1, 2].hash == [0, 1, 2].hash # => true
  *    [0, 1, 2].hash == [0, 1, 3].hash # => false
+ *
  */
 
 static VALUE
@@ -5123,6 +5340,7 @@ rb_ary_hash(VALUE ary)
  *
  *  Returns +true+ if for some index +i+ in +self+, <tt>obj == self[i]</tt>;
  *  otherwise +false+:
+ *
  *    [0, 1, 2].include?(2) # => true
  *    [0, 1, 2].include?(3) # => false
  */
@@ -5185,18 +5403,27 @@ recursive_cmp(VALUE ary1, VALUE ary2, int recur)
  *  For each index +i+ in +self+, evaluates <tt>result = self[i] <=> other_array[i]</tt>.
  *
  *  Returns -1 if any result is -1:
+ *
  *    [0, 1, 2] <=> [0, 1, 3] # => -1
  *
  *  Returns 1 if any result is 1:
+ *
  *    [0, 1, 2] <=> [0, 1, 1] # => 1
  *
  *  When all results are zero:
+ *
  *  - Returns -1 if +array+ is smaller than +other_array+:
+ *
  *      [0, 1, 2] <=> [0, 1, 2, 3] # => -1
+ *
  *  - Returns 1 if +array+ is larger than +other_array+:
+ *
  *      [0, 1, 2] <=> [0, 1] # => 1
+ *
  *  - Returns 0 if +array+ and +other_array+ are the same size:
+ *
  *      [0, 1, 2] <=> [0, 1, 2] # => 0
+ *
  */
 
 VALUE
@@ -5283,6 +5510,7 @@ ary_recycle_hash(VALUE hash)
  *  that are not found in \Array +other_array+;
  *  items are compared using <tt>eql?</tt>;
  *  the order from +array+ is preserved:
+ *
  *    [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
  *    [0, 1, 2, 3] - [3, 0] # => [1, 2]
  *    [0, 1, 2] - [4] # => [0, 1, 2]
@@ -5326,6 +5554,7 @@ rb_ary_diff(VALUE ary1, VALUE ary2)
  *  Returns a new \Array containing only those elements from +self+
  *  that are not found in any of the Arrays +other_arrays+;
  *  items are compared using <tt>eql?</tt>;  order from +self+ is preserved:
+ *
  *    [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
  *    [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
  *    [0, 1, 2].difference([4]) # => [0, 1, 2]
@@ -5378,10 +5607,12 @@ rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary)
  *
  *  Returns a new \Array containing each element found in both +array+ and \Array +other_array+;
  *  duplicates are omitted; items are compared using <tt>eql?</tt>:
+ *
  *    [0, 1, 2, 3] & [1, 2] # => [1, 2]
  *    [0, 1, 0, 1] & [0, 1] # => [0, 1]
  *
  *  Preserves order from +array+:
+ *
  *    [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
  *
  *  Related: Array#intersection.
@@ -5430,10 +5661,12 @@ rb_ary_and(VALUE ary1, VALUE ary2)
  *  Returns a new \Array containing each element found both in +self+
  *  and in all of the given Arrays +other_arrays+;
  *  duplicates are omitted; items are compared using <tt>eql?</tt>:
+ *
  *    [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
  *    [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
  *
  *  Preserves order from +self+:
+ *
  *    [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
  *
  *  Returns a copy of +self+ if no arguments given.
@@ -5492,6 +5725,7 @@ rb_ary_union_hash(VALUE hash, VALUE ary2)
  *  Returns the union of +array+ and \Array +other_array+;
  *  duplicates are removed; order is preserved;
  *  items are compared using <tt>eql?</tt>:
+ *
  *    [0, 1] | [2, 3] # => [0, 1, 2, 3]
  *    [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
  *    [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
@@ -5526,6 +5760,7 @@ rb_ary_or(VALUE ary1, VALUE ary2)
  *
  *  Returns a new \Array that is the union of +self+ and all given Arrays +other_arrays+;
  *  duplicates are removed;  order is preserved;  items are compared using <tt>eql?</tt>:
+ *
  *    [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
  *    [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
  *    [0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]
@@ -5570,13 +5805,14 @@ rb_ary_union_multi(int argc, VALUE *argv, VALUE ary)
  *     ary.intersect?(other_ary)   -> true or false
  *
  *  Returns +true+ if the array and +other_ary+ have at least one element in
- *  common, otherwise returns +false+.
+ *  common, otherwise returns +false+:
  *
  *     a = [ 1, 2, 3 ]
  *     b = [ 3, 4, 5 ]
  *     c = [ 5, 6, 7 ]
  *     a.intersect?(b)   #=> true
  *     a.intersect?(c)   #=> false
+ *
  */
 
 static VALUE
@@ -5717,6 +5953,7 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax)
  *    array.max(n) {|a, b| ... } -> new_array
  *
  *  Returns one of the following:
+ *
  *  - The maximum-valued element from +self+.
  *  - A new \Array of maximum-valued elements selected from +self+.
  *
@@ -5725,10 +5962,12 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax)
  *
  *  With no argument and no block, returns the element in +self+
  *  having the maximum value per method <tt><=></tt>:
+ *
  *    [0, 1, 2].max # => 2
  *
  *  With an argument \Integer +n+ and no block, returns a new \Array with at most +n+ elements,
  *  in descending order per method <tt><=></tt>:
+ *
  *    [0, 1, 2, 3].max(3) # => [3, 2, 1]
  *    [0, 1, 2, 3].max(6) # => [3, 2, 1, 0]
  *
@@ -5736,11 +5975,14 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax)
  *
  *  With a block and no argument, calls the block <tt>self.size-1</tt> times to compare elements;
  *  returns the element having the maximum value per the block:
+ *
  *    ['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000"
  *
  *  With an argument +n+ and a block, returns a new \Array with at most +n+ elements,
  *  in descending order per the block:
+ *
  *    ['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"]
+ *
  */
 static VALUE
 rb_ary_max(int argc, VALUE *argv, VALUE ary)
@@ -5880,6 +6122,7 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin)
  *    array.min(n) { |a, b| ... } -> new_array
  *
  *  Returns one of the following:
+ *
  *  - The minimum-valued element from +self+.
  *  - A new \Array of minimum-valued elements selected from +self+.
  *
@@ -5888,10 +6131,12 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin)
  *
  *  With no argument and no block, returns the element in +self+
  *  having the minimum value per method <tt><=></tt>:
+ *
  *    [0, 1, 2].min # => 0
  *
  *  With \Integer argument +n+ and no block, returns a new \Array with at most +n+ elements,
  *  in ascending order per method <tt><=></tt>:
+ *
  *    [0, 1, 2, 3].min(3) # => [0, 1, 2]
  *    [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
  *
@@ -5899,11 +6144,14 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin)
  *
  *  With a block and no argument, calls the block <tt>self.size-1</tt> times to compare elements;
  *  returns the element having the minimum value per the block:
+ *
  *    ['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"
  *
  *  With an argument +n+ and a block, returns a new \Array with at most +n+ elements,
  *  in ascending order per the block:
+ *
  *    ['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"]
+ *
  */
 static VALUE
 rb_ary_min(int argc, VALUE *argv, VALUE ary)
@@ -5958,13 +6206,16 @@ rb_ary_min(int argc, VALUE *argv, VALUE ary)
  *  with an \Integer;
  *  returns a new 2-element \Array containing the minimum and maximum values
  *  from +self+, per method <tt><=></tt>:
+ *
  *    [0, 1, 2].minmax # => [0, 2]
  *
  *  When a block is given, the block must return an \Integer;
  *  the block is called <tt>self.size-1</tt> times to compare elements;
  *  returns a new 2-element \Array containing the minimum and maximum values
  *  from +self+, per the block:
+ *
  *    ['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]
+ *
  */
 static VALUE
 rb_ary_minmax(VALUE ary)
@@ -5994,6 +6245,7 @@ push_value(st_data_t key, st_data_t val, st_data_t ary)
  *  to compare.
  *
  *  Returns +self+ if any elements removed:
+ *
  *    a = [0, 0, 1, 1, 2, 2]
  *    a.uniq! # => [0, 1, 2]
  *
@@ -6004,6 +6256,7 @@ push_value(st_data_t key, st_data_t val, st_data_t ary)
  *  elements for which the block returns duplicate values.
  *
  *  Returns +self+ if any elements removed:
+ *
  *    a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
  *    a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
  *
@@ -6049,15 +6302,18 @@ rb_ary_uniq_bang(VALUE ary)
  *  the first occurrence always being retained.
  *
  *  With no block given, identifies and omits duplicates using method <tt>eql?</tt>
- *  to compare.
+ *  to compare:
+ *
  *    a = [0, 0, 1, 1, 2, 2]
  *    a.uniq # => [0, 1, 2]
  *
  *  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
@@ -6121,6 +6377,7 @@ rb_ary_compact_bang(VALUE ary)
  *    array.compact -> new_array
  *
  *  Returns a new \Array containing all non-+nil+ elements from +self+:
+ *
  *    a = [nil, 0, nil, 1, nil, 2, nil]
  *    a.compact # => [0, 1, 2]
  */
@@ -6142,19 +6399,22 @@ rb_ary_compact(VALUE ary)
  *  Returns a count of specified elements.
  *
  *  With no argument and no block, returns the count of all elements:
+ *
  *    [0, 1, 2].count # => 3
  *    [].count # => 0
  *
  *  With argument +obj+, returns the count of elements <tt>==</tt> to +obj+:
+ *
  *    [0, 1, 2, 0.0].count(0) # => 2
  *    [0, 1, 2].count(3) # => 0
  *
  *  With no argument and a block given, calls the block with each element;
  *  returns the count of elements for which the block returns a truthy value:
+ *
  *    [0, 1, 2, 3].count {|element| element > 1} # => 2
  *
  *  With argument +obj+ and a block given, issues a warning, ignores the block,
- *  and returns the count of elements <tt>==</tt> to +obj+:
+ *  and returns the count of elements <tt>==</tt> to +obj+.
  */
 
 static VALUE
@@ -6288,6 +6548,7 @@ flatten(VALUE ary, int level)
  *  returns +self+ if any changes, +nil+ otherwise.
  *
  *  With non-negative \Integer argument +level+, flattens recursively through +level+ levels:
+ *
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
  *    a.flatten!(1) # => [0, 1, [2, 3], 4, 5]
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
@@ -6297,6 +6558,7 @@ flatten(VALUE ary, int level)
  *    [0, 1, 2].flatten!(1) # => nil
  *
  *  With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels:
+ *
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
  *    a.flatten! # => [0, 1, 2, 3, 4, 5]
  *    [0, 1, 2].flatten! # => nil
@@ -6305,6 +6567,7 @@ flatten(VALUE ary, int level)
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
  *    a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
  *    [0, 1, 2].flatten!(-1) # => nil
+ *
  */
 
 static VALUE
@@ -6339,6 +6602,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
  *  - Each \Array is replaced by its individual elements.
  *
  *  With non-negative \Integer argument +level+, flattens recursively through +level+ levels:
+ *
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
  *    a.flatten(0) # => [0, [1, [2, 3], 4], 5]
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
@@ -6349,6 +6613,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
  *    a.flatten(3) # => [0, 1, 2, 3, 4, 5]
  *
  *  With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels:
+ *
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
  *    a.flatten # => [0, 1, 2, 3, 4, 5]
  *    [0, 1, 2].flatten # => [0, 1, 2]
@@ -6357,6 +6622,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
  *    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
  *    a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
  *    [0, 1, 2].flatten(-1) # => [0, 1, 2]
+ *
  */
 
 static VALUE
@@ -6572,15 +6838,18 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj)
  *  When called with positive \Integer argument +count+ and a block,
  *  calls the block with each element, then does so again,
  *  until it has done so +count+ times; returns +nil+:
+ *
  *    output = []
  *    [0, 1].cycle(2) {|element| output.push(element) } # => nil
  *    output # => [0, 1, 0, 1]
  *
  *  If +count+ is zero or negative, does not call the block:
+ *
  *    [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
  *    [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
  *
  *  When a block is given, and argument is omitted or +nil+, cycles forever:
+ *
  *    # Prints 0 and 1 forever.
  *    [0, 1].cycle {|element| puts element }
  *    [0, 1].cycle(nil) {|element| puts element }
@@ -6590,6 +6859,7 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj)
  *    [0, 1].cycle(2) # => #<Enumerator: [0, 1]:cycle(2)>
  *    [0, 1].cycle # => # => #<Enumerator: [0, 1]:cycle>
  *    [0, 1].cycle.first(5) # => [0, 1, 0, 1, 0]
+ *
  */
 static VALUE
 rb_ary_cycle(int argc, VALUE *argv, VALUE ary)
@@ -6748,19 +7018,26 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj)
  *  are given, calls the block with all +n+-tuple permutations of +self+.
  *
  *  Example:
+ *
  *    a = [0, 1, 2]
  *    a.permutation(2) {|permutation| p permutation }
+ *
  *  Output:
+ *
  *    [0, 1]
  *    [0, 2]
  *    [1, 0]
  *    [1, 2]
  *    [2, 0]
  *    [2, 1]
+ *
  *  Another example:
+ *
  *    a = [0, 1, 2]
  *    a.permutation(3) {|permutation| p permutation }
+ *
  *  Output:
+ *
  *    [0, 1, 2]
  *    [0, 2, 1]
  *    [1, 0, 2]
@@ -6769,22 +7046,29 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj)
  *    [2, 1, 0]
  *
  *  When +n+ is zero, calls the block once with a new empty \Array:
+ *
  *    a = [0, 1, 2]
  *    a.permutation(0) {|permutation| p permutation }
+ *
  *  Output:
+ *
  *    []
  *
  *  When +n+ is out of range (negative or larger than <tt>self.size</tt>),
  *  does not call the block:
+ *
  *    a = [0, 1, 2]
  *    a.permutation(-1) {|permutation| fail 'Cannot happen' }
  *    a.permutation(4) {|permutation| fail 'Cannot happen' }
  *
  *  When a block given but no argument,
  *  behaves the same as <tt>a.permutation(a.size)</tt>:
+ *
  *    a = [0, 1, 2]
  *    a.permutation {|permutation| p permutation }
+ *
  *  Output:
+ *
  *    [0, 1, 2]
  *    [0, 2, 1]
  *    [1, 0, 2]
@@ -6793,9 +7077,11 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj)
  *    [2, 1, 0]
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [0, 1, 2]
  *    a.permutation # => #<Enumerator: [0, 1, 2]:permutation>
  *    a.permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
+ *
  */
 
 static VALUE
@@ -6878,34 +7164,46 @@ rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj)
  *  are given, calls the block with all +n+-tuple combinations of +self+.
  *
  *  Example:
+ *
  *    a = [0, 1, 2]
  *    a.combination(2) {|combination| p combination }
+ *
  *  Output:
+ *
  *    [0, 1]
  *    [0, 2]
  *    [1, 2]
  *
  *  Another example:
+ *
  *    a = [0, 1, 2]
  *    a.combination(3) {|combination| p combination }
+ *
  *  Output:
+ *
  *    [0, 1, 2]
  *
  *  When +n+ is zero, calls the block once with a new empty \Array:
+ *
  *    a = [0, 1, 2]
  *    a1 = a.combination(0) {|combination| p combination }
+ *
  *  Output:
+ *
  *    []
  *
  *  When +n+ is out of range (negative or larger than <tt>self.size</tt>),
  *  does not call the block:
+ *
  *    a = [0, 1, 2]
  *    a.combination(-1) {|combination| fail 'Cannot happen' }
  *    a.combination(4) {|combination| fail 'Cannot happen' }
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [0, 1, 2]
  *    a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
+ *
  */
 
 static VALUE
@@ -7004,16 +7302,22 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj)
  *  The number of permutations is <tt>self.size**n</tt>.
  *
  *  +n+ = 1:
+ *
  *    a = [0, 1, 2]
  *    a.repeated_permutation(1) {|permutation| p permutation }
+ *
  *  Output:
+ *
  *    [0]
  *    [1]
  *    [2]
  *
  *  +n+ = 2:
+ *
  *    a.repeated_permutation(2) {|permutation| p permutation }
+ *
  *  Output:
+ *
  *    [0, 0]
  *    [0, 1]
  *    [0, 2]
@@ -7027,14 +7331,17 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj)
  *  If +n+ is zero, calls the block once with an empty \Array.
  *
  *  If +n+ is negative, does not call the block:
+ *
  *    a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [0, 1, 2]
  *    a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
  *
  *  Using Enumerators, it's convenient to show the permutations and counts
  *  for some values of +n+:
+ *
  *    e = a.repeated_permutation(0)
  *    e.size # => 1
  *    e.to_a # => [[]]
@@ -7044,6 +7351,7 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj)
  *    e = a.repeated_permutation(2)
  *    e.size # => 9
  *    e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
+ *
  */
 static VALUE
 rb_ary_repeated_permutation(VALUE ary, VALUE num)
@@ -7126,16 +7434,22 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj)
  *  The number of combinations is <tt>(n+1)(n+2)/2</tt>.
  *
  *  +n+ = 1:
+ *
  *    a = [0, 1, 2]
  *    a.repeated_combination(1) {|combination| p combination }
+ *
  *  Output:
+ *
  *    [0]
  *    [1]
  *    [2]
  *
  *  +n+ = 2:
+ *
  *    a.repeated_combination(2) {|combination| p combination }
+ *
  *  Output:
+ *
  *    [0, 0]
  *    [0, 1]
  *    [0, 2]
@@ -7146,14 +7460,17 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj)
  *  If +n+ is zero, calls the block once with an empty \Array.
  *
  *  If +n+ is negative, does not call the block:
+ *
  *    a.repeated_combination(-1) {|combination| fail 'Cannot happen' }
  *
  *  Returns a new \Enumerator if no block given:
+ *
  *    a = [0, 1, 2]
  *    a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
  *
  *  Using Enumerators, it's convenient to show the combinations and counts
  *  for some values of +n+:
+ *
  *    e = a.repeated_combination(0)
  *    e.size # => 1
  *    e.to_a # => [[]]
@@ -7163,6 +7480,7 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj)
  *    e = a.repeated_combination(2)
  *    e.size # => 6
  *    e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
+ *
  */
 
 static VALUE
@@ -7206,12 +7524,14 @@ rb_ary_repeated_combination(VALUE ary, VALUE num)
  *    array.product(*other_arrays) {|combination| ... } -> self
  *
  *  Computes and returns or yields all combinations of elements from all the Arrays,
- *  including both +self+ and +other_arrays+.
+ *  including both +self+ and +other_arrays+:
+ *
  *  - The number of combinations is the product of the sizes of all the arrays,
  *    including both +self+ and +other_arrays+.
  *  - The order of the returned combinations is indeterminate.
  *
  *  When no block is given, returns the combinations as an \Array of Arrays:
+ *
  *    a = [0, 1, 2]
  *    a1 = [3, 4]
  *    a2 = [5, 6]
@@ -7226,11 +7546,15 @@ rb_ary_repeated_combination(VALUE ary, VALUE num)
  *
  *  If no argument is given, returns an \Array of 1-element Arrays,
  *  each containing an element of +self+:
+ *
  *    a.product # => [[0], [1], [2]]
  *
  *  When a block is given, yields each combination as an \Array; returns +self+:
+ *
  *    a.product(a1) {|combination| p combination }
+ *
  *  Output:
+ *
  *    [0, 3]
  *    [0, 4]
  *    [1, 3]
@@ -7239,14 +7563,19 @@ rb_ary_repeated_combination(VALUE ary, VALUE num)
  *    [2, 4]
  *
  *  If any argument is an empty \Array, does not call the block:
+ *
  *    a.product(a1, a2, []) {|combination| fail 'Cannot happen' }
  *
  *  If no argument is given, yields each element of +self+ as a 1-element \Array:
+ *
  *    a.product {|combination| p combination }
+ *
  *  Output:
+ *
  *    [0]
  *    [1]
  *    [2]
+ *
  */
 
 static VALUE
@@ -7346,11 +7675,13 @@ done:
  *  does not modify +self+.
  *
  *  Examples:
+ *
  *    a = [0, 1, 2, 3, 4, 5]
  *    a.take(1) # => [0]
  *    a.take(2) # => [0, 1]
  *    a.take(50) # => [0, 1, 2, 3, 4, 5]
  *    a # => [0, 1, 2, 3, 4, 5]
+ *
  */
 
 static VALUE
@@ -7374,13 +7705,16 @@ rb_ary_take(VALUE obj, VALUE n)
  *  With a block given, calls the block with each successive element of +self+;
  *  stops if the block returns +false+ or +nil+;
  *  returns a new \Array containing those elements for which the block returned a truthy value:
+ *
  *    a = [0, 1, 2, 3, 4, 5]
  *    a.take_while {|element| element < 3 } # => [0, 1, 2]
  *    a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
  *    a # => [0, 1, 2, 3, 4, 5]
  *
  *  With no block given, returns a new \Enumerator:
+ *
  *    [0, 1].take_while # => #<Enumerator: [0, 1]:take_while>
+ *
  */
 
 static VALUE
@@ -7404,10 +7738,12 @@ rb_ary_take_while(VALUE ary)
  *  does not modify +self+.
  *
  *  Examples:
+ *
  *    a = [0, 1, 2, 3, 4, 5]
  *    a.drop(0) # => [0, 1, 2, 3, 4, 5]
  *    a.drop(1) # => [1, 2, 3, 4, 5]
  *    a.drop(2) # => [2, 3, 4, 5]
+ *
  */
 
 static VALUE
@@ -7435,11 +7771,14 @@ rb_ary_drop(VALUE ary, VALUE n)
  *  With a block given, calls the block with each successive element of +self+;
  *  stops if the block returns +false+ or +nil+;
  *  returns a new \Array _omitting_ those elements for which the block returned a truthy value:
+ *
  *    a = [0, 1, 2, 3, 4, 5]
  *    a.drop_while {|element| element < 3 } # => [3, 4, 5]
  *
  *  With no block given, returns a new \Enumerator:
+ *
  *    [0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while>
+ *
  */
 
 static VALUE
@@ -7464,17 +7803,20 @@ rb_ary_drop_while(VALUE ary)
  *
  *  With no block given and no argument, returns +true+ if +self+ has any truthy element,
  *  +false+ otherwise:
+ *
  *    [nil, 0, false].any? # => true
  *    [nil, false].any? # => false
  *    [].any? # => false
  *
  *  With a block given and no argument, calls the block with each element in +self+;
  *  returns +true+ if the block returns any truthy value, +false+ otherwise:
+ *
  *    [0, 1, 2].any? {|element| element > 1 } # => true
  *    [0, 1, 2].any? {|element| element > 2 } # => false
  *
  *  If argument +obj+ is given, returns +true+ if +obj+.<tt>===</tt> any element,
  *  +false+ otherwise:
+ *
  *    ['food', 'drink'].any?(/foo/) # => true
  *    ['food', 'drink'].any?(/bar/) # => false
  *    [].any?(/foo/) # => false
@@ -7522,16 +7864,19 @@ rb_ary_any_p(int argc, VALUE *argv, VALUE ary)
  *
  *  With no block given and no argument, returns +true+ if +self+ contains only truthy elements,
  *  +false+ otherwise:
+ *
  *    [0, 1, :foo].all? # => true
  *    [0, nil, 2].all? # => false
  *    [].all? # => true
  *
  *  With a block given and no argument, calls the block with each element in +self+;
  *  returns +true+ if the block returns only truthy values, +false+ otherwise:
+ *
  *    [0, 1, 2].all? { |element| element < 3 } # => true
  *    [0, 1, 2].all? { |element| element < 2 } # => false
  *
  *  If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> every element, +false+ otherwise:
+ *
  *    ['food', 'fool', 'foot'].all?(/foo/) # => true
  *    ['food', 'drink'].all?(/bar/) # => false
  *    [].all?(/foo/) # => true
@@ -7579,16 +7924,19 @@ rb_ary_all_p(int argc, VALUE *argv, VALUE ary)
  *
  *  With no block given and no argument, returns +true+ if +self+ has no truthy elements,
  *  +false+ otherwise:
+ *
  *    [nil, false].none? # => true
  *    [nil, 0, false].none? # => false
  *    [].none? # => true
  *
  *  With a block given and no argument, calls the block with each element in +self+;
  *  returns +true+ if the block returns no truthy value, +false+ otherwise:
+ *
  *    [0, 1, 2].none? {|element| element > 3 } # => true
  *    [0, 1, 2].none? {|element| element > 1 } # => false
  *
  *  If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> no element, +false+ otherwise:
+ *
  *    ['food', 'drink'].none?(/bar/) # => true
  *    ['food', 'drink'].none?(/foo/) # => false
  *    [].none?(/foo/) # => true
@@ -7636,6 +7984,7 @@ rb_ary_none_p(int argc, VALUE *argv, VALUE ary)
  *
  *  With no block given and no argument, returns +true+ if +self+ has exactly one truthy element,
  *  +false+ otherwise:
+ *
  *    [nil, 0].one? # => true
  *    [0, 0].one? # => false
  *    [nil, nil].one? # => false
@@ -7643,12 +7992,14 @@ rb_ary_none_p(int argc, VALUE *argv, VALUE ary)
  *
  *  With a block given and no argument, calls the block with each element in +self+;
  *  returns +true+ if the block a truthy value for exactly one element, +false+ otherwise:
+ *
  *    [0, 1, 2].one? {|element| element > 0 } # => false
  *    [0, 1, 2].one? {|element| element > 1 } # => true
  *    [0, 1, 2].one? {|element| element > 2 } # => false
  *
  *  If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> exactly one element,
  *  +false+ otherwise:
+ *
  *    [0, 1, 2].one?(0) # => true
  *    [0, 0, 1].one?(0) # => false
  *    [1, 1, 2].one?(0) # => false
@@ -7707,11 +8058,13 @@ rb_ary_one_p(int argc, VALUE *argv, VALUE ary)
  *  See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
  *
  *  Examples:
+ *
  *    a = [:foo, [:bar, :baz, [:bat, :bam]]]
  *    a.dig(1) # => [:bar, :baz, [:bat, :bam]]
  *    a.dig(1, 2) # => [:bat, :bam]
  *    a.dig(1, 2, 0) # => :bat
  *    a.dig(1, 2, 3) # => nil
+ *
  */
 
 static VALUE
@@ -7744,31 +8097,38 @@ finish_exact_sum(long n, VALUE r, VALUE v, int z)
  *   array.sum(init = 0) {|element| ... } -> object
  *
  *  When no block is given, returns the object equivalent to:
+ *
  *    sum = init
  *    array.each {|element| sum += element }
  *    sum
+ *
  *  For example, <tt>[e1, e2, e3].sum</tt> returns <tt>init + e1 + e2 + e3</tt>.
  *
  *  Examples:
+ *
  *    a = [0, 1, 2, 3]
  *    a.sum # => 6
  *    a.sum(100) # => 106
  *
  *  The elements need not be numeric, but must be <tt>+</tt>-compatible
  *  with each other and with +init+:
+ *
  *    a = ['abc', 'def', 'ghi']
  *    a.sum('jkl') # => "jklabcdefghi"
  *
  *  When a block is given, it is called with each element
  *  and the block's return value (instead of the element itself) is used as the addend:
+ *
  *    a = ['zero', 1, :two]
  *    s = a.sum('Coerced and concatenated: ') {|element| element.to_s }
  *    s # => "Coerced and concatenated: zero1two"
  *
  *  Notes:
+ *
  *  - Array#join and Array#flatten may be faster than Array#sum
  *    for an \Array of Strings or an \Array of Arrays.
  *  - Array#sum method may not respect method redefinition of "+" methods such as Integer#+.
+ *
  */
 
 static VALUE