https://git.ruby-lang.org/ruby.git/commit/?id=f0ad5594bf

From f0ad5594bf6107389cb8b3dfdfff1425e3317b16 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Sat, 29 Aug 2020 12:15:06 -0500
Subject: Comply with guide for method doc: array.c (#3473)

Methods considered:

    at
    first
    last
    fetch
    index
    rindex
    []
    insert
    each
    each_index
    reverse_each

diff --git a/array.c b/array.c
index 3d90b5a..2c8f8d9 100644
--- a/array.c
+++ b/array.c
@@ -992,7 +992,7 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L992
  *  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 = Array.new(3) {|index| "Element #{index}" }
  *    a # => ["Element 0", "Element 1", "Element 2"]
  *
  *  Raises ArgumentError if +size+ is negative.
@@ -1519,7 +1519,6 @@ ary_ensure_room_for_unshift(VALUE ary, int argc) https://github.com/ruby/ruby/blob/trunk/array.c#L1519
 /*
  *  call-seq:
  *    array.unshift(*objects) -> self
- *    array.prepend(*objects) -> self
  *
  *  Prepends the given +objects+ to +self+:
  *    a = [:foo, 'bar', 2]
@@ -1702,9 +1701,7 @@ rb_ary_aref1(VALUE ary, VALUE arg) https://github.com/ruby/ruby/blob/trunk/array.c#L1701
  *  call-seq:
  *    array.at(index) -> object
  *
- *  Argument +index+ must be an \Integer.
- *
- *  Returns the element at offset +index+; does not modify +self+.
+ *  Returns the element at \Integer offset +index+; does not modify +self+.
  *    a = [:foo, 'bar', 2]
  *    a.at(0) # => :foo
  *    a.at(2) # => 2
@@ -1722,11 +1719,6 @@ rb_ary_at(VALUE ary, VALUE pos) https://github.com/ruby/ruby/blob/trunk/array.c#L1719
  *    array.first(n) -> new_array
  *
  *  Returns elements from +self+; does not modify +self+.
- *  See also #last.
- *
- *  Argument +n+, if given, must be an \Integer.
- *
- *  ---
  *
  *  When no argument is given, returns the first element:
  *    a = [:foo, 'bar', 2]
@@ -1735,9 +1727,8 @@ rb_ary_at(VALUE ary, VALUE pos) https://github.com/ruby/ruby/blob/trunk/array.c#L1727
  *
  *  If +self+ is empty, returns +nil+.
  *
- *  ---
- *
- *  When argument +n+ is given, returns the first +n+ elements in a new \Array:
+ *  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"]
  *
@@ -1749,12 +1740,7 @@ rb_ary_at(VALUE ary, VALUE pos) https://github.com/ruby/ruby/blob/trunk/array.c#L1740
  *    a = [:foo, 'bar', 2]
  *    a.first(0) # []
  *
- *  ---
- *
- *  Raises an exception if +n+ is negative:
- *    a = [:foo, 'bar', 2]
- *    # Raises ArgumentError (negative array size):
- *    a.first(-1)
+ *  Related: #last.
  */
 static VALUE
 rb_ary_first(int argc, VALUE *argv, VALUE ary)
@@ -1774,11 +1760,6 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1760
  *    array.last(n) -> new_array
  *
  *  Returns elements from +self+; +self+ is not modified.
- *  See also #first.
- *
- *  Argument +n+, if given, must be an \Integer.
- *
- *  ---
  *
  *  When no argument is given, returns the last element:
  *    a = [:foo, 'bar', 2]
@@ -1787,9 +1768,8 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1768
  *
  *  If +self+ is empty, returns +nil+.
  *
- *  ---
- *
- *  When argument +n+ is given, returns the last +n+ elements in a new \Array:
+ *  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]
  *
@@ -1801,12 +1781,7 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1781
  *    a = [:foo, 'bar', 2]
  *    a.last(0) # []
  *
- *  ---
- *
- *  Raises an exception if +n+ is negative:
- *    a = [:foo, 'bar', 2]
- *    # Raises ArgumentError (negative array size):
- *    a.last(-1)
+ *  Related: #first.
  */
 
 VALUE
@@ -1830,11 +1805,8 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1805
  *
  *  Returns the element at offset  +index+.
  *
- *  Argument +index+ must be an \Integer.
- *
- *  ---
- *
- *  With the single argument +index+, returns the element at offset +index+:
+ *  With the single \Integer argument +index+,
+ *  returns the element at offset +index+:
  *    a = [:foo, 'bar', 2]
  *    a.fetch(1) # => "bar"
  *
@@ -1843,30 +1815,19 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1815
  *    a.fetch(-1) # => 2
  *    a.fetch(-2) # => "bar"
  *
- *  ---
- *
  *  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"
  *
- *  ---
- *
  *  With argument +index+ and a block,
  *  returns the element at offset +index+ if index is in range
  *  (and the block is not called); otherwise calls the block with index and returns its return value:
  *
  *    a = [:foo, 'bar', 2]
- *    a.fetch(1) { |index| raise 'Cannot happen' } # => "bar"
- *    a.fetch(50) { |index| "Value for #{index}" } # => "Value for 50"
- *
- *  ---
- *
- *  Raises an exception if +index+ is out of range and neither default_value nor a block given:
- *    a = [:foo, 'bar', 2]
- *    # Raises IndexError (index 50 outside of array bounds: -3...3):
- *    a.fetch(50)
+ *    a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
+ *    a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
  */
 
 static VALUE
@@ -1902,17 +1863,9 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1863
  *    array.index(object) -> integer or nil
  *    array.index {|element| ... } -> integer or nil
  *    array.index -> new_enumerator
- *    array.find_index(object) -> integer or nil
- *    array.find_index {|element| ... } -> integer or nil
- *    array.find_index -> new_enumerator
- *
- *  Array#find_index is an alias for Array#index.
- *  See also Array#rindex.
  *
  *  Returns the index of a specified element.
  *
- *  ---
- *
  *  When argument +object+ is given but no block,
  *  returns the index of the first element +element+
  *  for which <tt>object == element</tt>:
@@ -1921,31 +1874,21 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1874
  *
  *  Returns +nil+ if no such element found.
  *
- *  ---
- *
  *  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
+ *    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>
- *    e.each { |element| element == 'bar' } # => 1
- *
- *  ---
+ *    e.each {|element| element == 'bar' } # => 1
  *
- *  When both an argument and a block given, gives a warning (warning: given block not used)
- *  and ignores the block:
- *    a = [:foo, 'bar', 2, 'bar']
- *    index = a.index('bar') { raise 'Cannot happen' }
- *    index # => 1
+ *  Array#find_index is an alias for Array#index.
  *
  *  Related: #rindex.
  */
@@ -1986,16 +1929,12 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1929
  *
  *  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
  *
  *  Returns +nil+ if no such object found.
  *
- *  ---
- *
  *  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']
@@ -2003,22 +1942,14 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1942
  *
  *  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, 'bar']
  *    e = a.rindex
  *    e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
- *    e.each { |element| element == 'bar' } # => 3
+ *    e.each {|element| element == 'bar' } # => 3
  *
- *  ---
- *
- *  When both an argument and a block given, gives a warning (warning: given block not used)
- *  and ignores the block:
- *    a = [:foo, 'bar', 2, 'bar']
- *    index = a.rindex('bar') { raise 'Cannot happen' }
- *    index # => 3
+ *  Related: #index.
  */
 
 static VALUE
@@ -2219,12 +2150,7 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) https://github.com/ruby/ruby/blob/trunk/array.c#L2150
  *
  *  Assigns elements in +self+; returns the given +object+.
  *
- *  - Arguments +index+, +start+, and +length+, if given, must be Integers.
- *  - Argument +range+, if given, must be a \Range object.
- *
- *  ---
- *
- *  When +index+ is given, assigns +object+ to an element in +self+.
+ *  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]
@@ -2241,9 +2167,7 @@ ary_aset_by_rb_ary_splice(VALUE ary, long beg, long len, VALUE val) https://github.com/ruby/ruby/blob/trunk/array.c#L2167
  *    a[-1] = 'two' # => "two" (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/