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

From dc351ff984de001863d5167adf9ebd2fb317becd Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Tue, 23 Jun 2020 08:58:26 -0500
Subject: [ci skip] Enhanced RDoc for Array (#3237)

Methods:

    #rotate!
    #rotate
    #sort!
    #sort
    #bsearch
    #bsearch_index

diff --git a/array.c b/array.c
index 6d03122..9b47bf6 100644
--- a/array.c
+++ b/array.c
@@ -1485,7 +1485,7 @@ rb_ary_shift(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1485
  *    a.shift(3) # => [:foo, 'bar', 2]
  *    a # => []
  *
- *  If +n+ is 0, returns a new empty \Array; +self+ is unmodified:
+ *  If +n+ is zero, returns a new empty \Array; +self+ is unmodified:
  *    a = [:foo, 'bar', 2]
  *    a.shift(0) # => []
  *    a # => [:foo, 'bar', 2]
@@ -3310,19 +3310,58 @@ rb_ary_rotate(VALUE ary, long cnt) https://github.com/ruby/ruby/blob/trunk/array.c#L3310
 
 /*
  *  call-seq:
- *     ary.rotate!(count=1)   -> ary
+ *    array.rotate! -> self
+ *    array.rotate!(count) -> self
  *
- *  Rotates +self+ in place so that the element at +count+ comes first, and
- *  returns +self+.
+ *  Rotates +self+ in place by moving elements from one end to the other; returns +self+.
  *
- *  If +count+ is negative then it rotates in the opposite direction, starting
- *  from the end of the array where +-1+ is the last element.
+ *  Argument +count+, if given, must be an
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
  *
- *     a = [ "a", "b", "c", "d" ]
- *     a.rotate!        #=> ["b", "c", "d", "a"]
- *     a                #=> ["b", "c", "d", "a"]
- *     a.rotate!(2)     #=> ["d", "a", "b", "c"]
- *     a.rotate!(-3)    #=> ["a", "b", "c", "d"]
+ *  ---
+ *
+ *  When no argument given, rotates the first element to the last position:
+ *    a = [:foo, 'bar', 2, 'bar']
+ *    a1 = a.rotate!
+ *    a1 # => ["bar", 2, "bar", :foo]
+ *    a1.equal?(a1) # => true # Retruned self
+ *
+ *  ---
+ *
+ *  When given a non-negative +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 % ary.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 +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 % ary.size</tt> as the count:
+ *    a = [:foo, 'bar', 2]
+ *    a.rotate!(-5)
+ *    a # => ["bar", 2, :foo]
+ *
+ *  ---
+ *
+ *  Raises an exception if +count+ is not an Integer-convertible object:
+ *    a = [:foo, 'bar', 2]
+ *    # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    a1 = a.rotate!(:foo)
  */
 
 static VALUE
@@ -3335,19 +3374,59 @@ rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L3374
 
 /*
  *  call-seq:
- *     ary.rotate(count=1)    -> new_ary
+ *    array.rotate -> new_array
+ *    array.rotate(count) -> new_array
  *
- *  Returns a new array by rotating +self+ so that the element at +count+ is
- *  the first element of the new array.
+ *  Returns a new \Array formed from +self+ with elements
+ *  rotated from one end to the other.
  *
- *  If +count+ is negative then it rotates in the opposite direction, starting
- *  from the end of +self+ where +-1+ is the last element.
+ *  Argument +count+, if given, must be an
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
  *
- *     a = [ "a", "b", "c", "d" ]
- *     a.rotate         #=> ["b", "c", "d", "a"]
- *     a                #=> ["a", "b", "c", "d"]
- *     a.rotate(2)      #=> ["c", "d", "a", "b"]
- *     a.rotate(-3)     #=> ["b", "c", "d", "a"]
+ *  ---
+ *  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 +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 % ary.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 +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 % ary.size</tt> as the count:
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.rotate(-5)
+ *    a1 # => ["bar", 2, :foo]
+ *
+ *  ---
+ *
+ *  Raises an exception if +count+ is not an Integer-convertible object:
+ *    a = [:foo, 'bar', 2]
+ *    # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    a1 = a.rotate(:foo)
  */
 
 static VALUE
@@ -3431,26 +3510,49 @@ sort_2(const void *ap, const void *bp, void *dummy) https://github.com/ruby/ruby/blob/trunk/array.c#L3510
 
 /*
  *  call-seq:
- *     ary.sort!                   -> ary
- *     ary.sort! {|a, b| block}    -> ary
+ *    array.sort! -> self
+ *    array.sort! {|a, b| ... } -> self
+ *
+ *  Returns +self+ with its elements sorted in place.
  *
- *  Sorts +self+ in place.
+ *  ---
  *
- *  Comparisons for the sort will be done using the <code><=></code> operator
- *  or using an optional code block.
+ *  With no block, compares elements using operator <tt><=></tt>
+ *  (see Comparable):
+ *    a = 'abcde'.split('').shuffle
+ *    a # => ["e", "b", "d", "a", "c"]
+ *    a.sort!
+ *    a # => ["a", "b", "c", "d", "e"]
  *
- *  The block must implement a comparison between +a+ and +b+ and return
- *  an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+
- *  are equivalent, or an integer greater than 0 when +a+ follows +b+.
+ *  ---
  *
- *  The result is not guaranteed to be stable.  When the comparison of two
- *  elements returns +0+, the order of the elements is unpredictable.
+ *  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 }
+ *    a # => ["a", "b", "c", "d", "e"]
+ *    a.sort! {|a, b| b <=> a }
+ *    a # => ["e", "d", "c", "b", "a"]
+ *
+ *  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"]
  *
- *     ary = [ "d", "a", "e", "c", "b" ]
- *     ary.sort!                     #=> ["a", "b", "c", "d", "e"]
- *     ary.sort! {|a, b| b <=> a}    #=> ["e", "d", "c", "b", "a"]
+ *  ---
  *
- *  See also Enumerable#sort_by.
+ *  Raises an exception if the block returns a non-Integer:
+ *    a = 'abcde'.split('').shuffle
+ *    # Raises ArgumentError (comparison of Symbol with 0 failed):
+ *    a1 = a.sort! {|a, b| :foo }
  */
 
 VALUE
@@ -3515,31 +3617,51 @@ rb_ary_sort_bang(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L3617
 
 /*
  *  call-seq:
- *     ary.sort                   -> new_ary
- *     ary.sort {|a, b| block}    -> new_ary
+ *    array.sort -> new_array
+ *    array.sort {|a, b| ... } -> new_array
  *
- *  Returns a new array created by sorting +self+.
+ *  Returns a new \Array whose elements are those from +self+, sorted.
  *
- *  Comparisons for the sort will be done using the <code><=></code> operator
- *  or using an optional code block.
+ *  See also Enumerable#sort_by.
  *
- *  The block must implement a comparison between +a+ and +b+ and return
- *  an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+
- *  are equivalent, or an integer greater than 0 when +a+ follows +b+.
+ *  ---
  *
- *  The result is not guaranteed to be stable.  When the comparison of two
- *  elements returns +0+, the order of the elements is unpredictable.
+ *  With no block, compares elements using operator <tt><=></tt>
+ *  (see Comparable):
+ *    a = 'abcde'.split('').shuffle
+ *    a # => ["e", "b", "d", "a", "c"]
+ *    a1 = a.sort
+ *    a1 # => ["a", "b", "c", "d", "e"]
  *
- *     ary = [ "d", "a", "e", "c", "b" ]
- *     ary.sort                     #=> ["a", "b", "c", "d", "e"]
- *     ary.sort {|a, b| b <=> a}    #=> ["e", "d", "c", "b", "a"]
+ *  ---
  *
- *  To produce the reverse order, the following can also be used
- *  (and may be faster):
+ *  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 }
+ *    a1 # => ["a", "b", "c", "d", "e"]
+ *    a2 = a.sort {|a, b| b <=> a }
+ *    a2 # => ["e", "d", "c", "b", "a"]
+ *
+ *  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  (... truncated)

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