rbs 2.0.0 → 2.1.0

data/core/array.rbs

@@ -1,21 +1,54 @@
-# Arrays are ordered, integer-indexed collections of any object.
+# <!-- rdoc-file=array.c -->
+# An Array is an ordered, integer-indexed collection of objects, called
+# *elements*.  Any object may be an Array element.
+#
+# ## Array Indexes
+#
+# Array indexing starts at 0, as in C or Java.
+#
+# A positive index is an offset from the first element:
+# *   Index 0 indicates the first element.
+# *   Index 1 indicates the second element.
+# *   ...
+#
+#
+# A negative index is an offset, backwards, from the end of the array:
+# *   Index -1 indicates the last element.
+# *   Index -2 indicates the next-to-last element.
+# *   ...
+#
+#
+# A non-negative index is *in range* if it is smaller than the size of the
+# array.  For a 3-element array:
+# *   Indexes 0 through 2 are in range.
+# *   Index 3 is out of range.
+#
+#
+# A negative index is *in range* if its absolute value is not larger than the
+# size of the array.  For a 3-element array:
+# *   Indexes -1 through -3 are in range.
+# *   Index -4 is out of range.
 #
-# Array indexing starts at 0, as in C or Java.  A negative index is assumed to
-# be relative to the end of the array---that is, an index of -1 indicates the
-# last element of the array, -2 is the next to last element in the array, and so
-# on.
 #
 # ## Creating Arrays
 #
-# A new array can be created by using the literal constructor `[]`.  Arrays can
-# contain different types of objects.  For example, the array below contains an
-# Integer, a String and a Float:
+# You can create an Array object explicitly with:
+#
+# *   An [array literal](doc/syntax/literals_rdoc.html#label-Array+Literals).
+#
+#
+# You can convert certain objects to Arrays with:
+#
+# *   Method [Array](Kernel.html#method-i-Array).
+#
+#
+# An Array can contain different types of objects.  For example, the array below
+# contains an Integer, a String and a Float:
 #
 #     ary = [1, "two", 3.0] #=> [1, "two", 3.0]
 #
-# An array can also be created by explicitly calling Array.new with zero, one
-# (the initial size of the Array) or two arguments (the initial size and a
-# default object).
+# An array can also be created by calling Array.new with zero, one (the initial
+# size of the Array) or two arguments (the initial size and a default object).
 #
 #     ary = Array.new    #=> []
 #     Array.new(3)       #=> [nil, nil, nil]
@@ -231,64 +264,356 @@
 #     arr = [1, 2, 3, 4, 5, 6]
 #     arr.keep_if {|a| a < 4}   #=> [1, 2, 3]
 #     arr                       #=> [1, 2, 3]
-# for pack.c
 #
+# ## What's Here
+#
+# First, what's elsewhere. Class Array:
+#
+# *   Inherits from [class
+#     Object](Object.html#class-Object-label-What-27s+Here).
+# *   Includes [module
+#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
+#     provides dozens of additional methods.
+#
+#
+# Here, class Array provides methods that are useful for:
+#
+# *   [Creating an Array](#class-Array-label-Methods+for+Creating+an+Array)
+# *   [Querying](#class-Array-label-Methods+for+Querying)
+# *   [Comparing](#class-Array-label-Methods+for+Comparing)
+# *   [Fetching](#class-Array-label-Methods+for+Fetching)
+# *   [Assigning](#class-Array-label-Methods+for+Assigning)
+# *   [Deleting](#class-Array-label-Methods+for+Deleting)
+# *   [Combining](#class-Array-label-Methods+for+Combining)
+# *   [Iterating](#class-Array-label-Methods+for+Iterating)
+# *   [Converting](#class-Array-label-Methods+for+Converting)
+# *   [And more....](#class-Array-label-Other+Methods)
+#
+#
+# ### Methods for Creating an Array
+#
+# ::[]
+# :   Returns a new array populated with given objects.
+# ::new
+# :   Returns a new array.
+# ::try_convert
+# :   Returns a new array created from a given object.
+#
+#
+# ### Methods for Querying
+#
+# #length, #size
+# :   Returns the count of elements.
+# #include?
+# :   Returns whether any element `==` a given object.
+# #empty?
+# :   Returns whether there are no elements.
+# #all?
+# :   Returns whether all elements meet a given criterion.
+# #any?
+# :   Returns whether any element meets a given criterion.
+# #none?
+# :   Returns whether no element `==` a given object.
+# #one?
+# :   Returns whether exactly one element `==` a given object.
+# #count
+# :   Returns the count of elements that meet a given criterion.
+# #find_index, #index
+# :   Returns the index of the first element that meets a given criterion.
+# #rindex
+# :   Returns the index of the last element that meets a given criterion.
+# #hash
+# :   Returns the integer hash code.
+#
+#
+# ### Methods for Comparing
+# [#<=>](#method-i-3C-3D-3E)
+# :   Returns -1, 0, or 1 as `self` is less than, equal to, or greater than a
+#     given object.
+# [#==](#method-i-3D-3D)
+# :   Returns whether each element in `self` is `==` to the corresponding
+#     element in a given object.
+# #eql?
+# :   Returns whether each element in `self` is `eql?` to the corresponding
+#     element in a given object.
+#
+#
+# ### Methods for Fetching
+#
+# These methods do not modify `self`.
+#
+# #[]
+# :   Returns one or more elements.
+# #fetch
+# :   Returns the element at a given offset.
+# #first
+# :   Returns one or more leading elements.
+# #last
+# :   Returns one or more trailing elements.
+# #max
+# :   Returns one or more maximum-valued elements, as determined by `<=>` or a
+#     given block.
+# #max
+# :   Returns one or more minimum-valued elements, as determined by `<=>` or a
+#     given block.
+# #minmax
+# :   Returns the minimum-valued and maximum-valued elements, as determined by
+#     `<=>` or a given block.
+# #assoc
+# :   Returns the first element that is an array whose first element `==` a
+#     given object.
+# #rassoc
+# :   Returns the first element that is an array whose second element `==` a
+#     given object.
+# #at
+# :   Returns the element at a given offset.
+# #values_at
+# :   Returns the elements at given offsets.
+# #dig
+# :   Returns the object in nested objects that is specified by a given index
+#     and additional arguments.
+# #drop
+# :   Returns trailing elements as determined by a given index.
+# #take
+# :   Returns leading elements as determined by a given index.
+# #drop_while
+# :   Returns trailing elements as determined by a given block.
+# #take_while
+# :   Returns leading elements as determined by a given block.
+# #slice
+# :   Returns consecutive elements as determined by a given argument.
+# #sort
+# :   Returns all elements in an order determined by `<=>` or a given block.
+# #reverse
+# :   Returns all elements in reverse order.
+# #compact
+# :   Returns an array containing all non-`nil` elements.
+# #select, #filter
+# :   Returns an array containing elements selected by a given block.
+# #uniq
+# :   Returns an array containing non-duplicate elements.
+# #rotate
+# :   Returns all elements with some rotated from one end to the other.
+# #bsearch
+# :   Returns an element selected via a binary search as determined by a given
+#     block.
+# #bsearch_index
+# :   Returns the index of an element selected via a binary search as determined
+#     by a given block.
+# #sample
+# :   Returns one or more random elements.
+# #shuffle
+# :   Returns elements in a random order.
+#
+#
+# ### Methods for Assigning
+#
+# These methods add, replace, or reorder elements in `self`.
+#
+# #[]=
+# :   Assigns specified elements with a given object.
+# #push, #append, #<<
+# :   Appends trailing elements.
+# #unshift, #prepend
+# :   Prepends leading elements.
+# #insert
+# :   Inserts given objects at a given offset; does not replace elements.
+# #concat
+# :   Appends all elements from given arrays.
+# #fill
+# :   Replaces specified elements with specified objects.
+# #replace
+# :   Replaces the content of `self` with the content of a given array.
+# #reverse!
+# :   Replaces `self` with its elements reversed.
+# #rotate!
+# :   Replaces `self` with its elements rotated.
+# #shuffle!
+# :   Replaces `self` with its elements in random order.
+# #sort!
+# :   Replaces `self` with its elements sorted, as determined by `<=>` or a
+#     given block.
+# #sort_by!
+# :   Replaces `self` with its elements sorted, as determined by a given block.
+#
+#
+# ### Methods for Deleting
+#
+# Each of these methods removes elements from `self`:
+#
+# #pop
+# :   Removes and returns the last element.
+# #shift
+# :   Removes and returns the first element.
+# #compact!
+# :   Removes all non-`nil` elements.
+# #delete
+# :   Removes elements equal to a given object.
+# #delete_at
+# :   Removes the element at a given offset.
+# #delete_if
+# :   Removes elements specified by a given block.
+# #keep_if
+# :   Removes elements not specified by a given block.
+# #reject!
+# :   Removes elements specified by a given block.
+# #select!, #filter!
+# :   Removes elements not specified by a given block.
+# #slice!
+# :   Removes and returns a sequence of elements.
+# #uniq!
+# :   Removes duplicates.
+#
+#
+# ### Methods for Combining
+#
+# [#&](#method-i-26)
+# :   Returns an array containing elements found both in `self` and a given
+#     array.
+# #intersection
+# :   Returns an array containing elements found both in `self` and in each
+#     given array.
+# #+
+# :   Returns an array containing all elements of `self` followed by all
+#     elements of a given array.
+# #-
+# :   Returns an array containiing all elements of `self` that are not found in
+#     a given array.
+# [#|](#method-i-7C)
+# :   Returns an array containing all elements of `self` and all elements of a
+#     given array, duplicates removed.
+# #union
+# :   Returns an array containing all elements of `self` and all elements of
+#     given arrays, duplicates removed.
+# #difference
+# :   Returns an array containing all elements of `self` that are not found in
+#     any of the given arrays..
+# #product
+# :   Returns or yields all combinations of elements from `self` and given
+#     arrays.
+#
+#
+# ### Methods for Iterating
+#
+# #each
+# :   Passes each element to a given block.
+# #reverse_each
+# :   Passes each element, in reverse order, to a given block.
+# #each_index
+# :   Passes each element index to a given block.
+# #cycle
+# :   Calls a given block with each element, then does so again, for a specified
+#     number of times, or forever.
+# #combination
+# :   Calls a given block with combinations of elements of `self`; a combination
+#     does not use the same element more than once.
+# #permutation
+# :   Calls a given block with permutations of elements of `self`; a permutation
+#     does not use the same element more than once.
+# #repeated_combination
+# :   Calls a given block with combinations of elements of `self`; a combination
+#     may use the same element more than once.
+# #repeated_permutation
+# :   Calls a given block with permutations of elements of `self`; a permutation
+#     may use the same element more than once.
+#
+#
+# ### Methods for Converting
+#
+# #map, #collect
+# :   Returns an array containing the block return-value for each element.
+# #map!, #collect!
+# :   Replaces each element with a block return-value.
+# #flatten
+# :   Returns an array that is a recursive flattening of `self`.
+# #flatten!
+# :   Replaces each nested array in `self` with the elements from that array.
+# #inspect, #to_s
+# :   Returns a new String containing the elements.
+# #join
+# :   Returns a newsString containing the elements joined by the field
+#     separator.
+# #to_a
+# :   Returns `self` or a new array containing all elements.
+# #to_ary
+# :   Returns `self`.
+# #to_h
+# :   Returns a new hash formed from the elements.
+# #transpose
+# :   Transposes `self`, which must be an array of arrays.
+# #zip
+# :   Returns a new array of arrays containing `self` and given arrays; follow
+#     the link for details.
+#
+#
+# ### Other Methods
+#
+# #*
+# :   Returns one of the following:
+#     *   With integer argument `n`, a new array that is the concatenation of
+#         `n` copies of `self`.
+#     *   With string argument `field_separator`, a new string that is
+#         equivalent to `join(field_separator)`.
+#
+# #abbrev
+# :   Returns a hash of unambiguous abbreviations for elements.
+# #pack
+# :   Packs the elements into a binary sequence.
+# #sum
+# :   Returns a sum of elements according to either `+` or a given block.
+#
+%a{annotate:rdoc:source:from=array.c}
 class Array[unchecked out Elem] < Object
   include Enumerable[Elem]
 
-  # Returns a new array.
-  #
-  # In the first form, if no arguments are sent, the new array will be empty. When
-  # a `size` and an optional `default` are sent, an array is created with `size`
-  # copies of `default`.  Take notice that all elements will reference the same
-  # object `default`.
-  #
-  # The second form creates a copy of the array passed as a parameter (the array
-  # is generated by calling to_ary on the parameter).
-  #
-  #     first_array = ["Matz", "Guido"]
-  #
-  #     second_array = Array.new(first_array) #=> ["Matz", "Guido"]
-  #
-  #     first_array.equal? second_array       #=> false
-  #
-  # In the last form, an array of the given size is created.  Each element in this
-  # array is created by passing the element's index to the given block and storing
-  # the return value.
-  #
-  #     Array.new(3) {|index| index ** 2}
-  #     # => [0, 1, 4]
-  #
-  # ## Common gotchas
-  #
-  # When sending the second parameter, the same object will be used as the value
-  # for all the array elements:
-  #
-  #     a = Array.new(2, Hash.new)
-  #     # => [{}, {}]
-  #
-  #     a[0]['cat'] = 'feline'
-  #     a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]
-  #
-  #     a[1]['cat'] = 'Felix'
-  #     a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]
-  #
-  # Since all the Array elements store the same hash, changes to one of them will
-  # affect them all.
-  #
-  # If multiple copies are what you want, you should use the block version which
-  # uses the result of that block each time an element of the array needs to be
-  # initialized:
-  #
-  #     a = Array.new(2) {Hash.new}
-  #     a[0]['cat'] = 'feline'
-  #     a # => [{"cat"=>"feline"}, {}]
+  # <!--
+  #   rdoc-file=array.c
+  #   - Array.new -> new_empty_array
+  #   - Array.new(array) -> new_array
+  #   - Array.new(size) -> new_array
+  #   - Array.new(size, default_value) -> new_array
+  #   - Array.new(size) {|index| ... } -> new_array
+  # -->
+  # Returns a new Array.
+  #
+  # With no block and no arguments, returns a new empty Array object.
+  #
+  # 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]
+  #
+  # 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']
+  #
+  # With a block and argument `size`, 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"]
+  #
+  # Raises ArgumentError if `size` is negative.
+  #
+  # With a block and no argument, or a single argument `0`, ignores the block and
+  # returns a new empty Array.
   #
   def initialize: () -> void
                 | (::Array[Elem] ary) -> void
                 | (int size, ?Elem val) -> void
                 | (int size) { (::Integer index) -> Elem } -> void
 
+  # <!--
+  #   rdoc-file=array.c
+  #   - [](*args)
+  # -->
   # Returns a new array populated with the given objects.
   #
   #     Array.[]( 1, 'a', /^A/)  # => [1, "a", /^A/]
@@ -297,190 +622,336 @@ class Array[unchecked out Elem] < Object
   #
   def self.[]: [U] (*U) -> ::Array[U]
 
-  # Tries to convert `obj` into an array, using the `to_ary` method.  Returns the
-  # converted array or `nil` if `obj` cannot be converted. This method can be used
-  # to check if an argument is an array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - Array.try_convert(object) -> object, new_array, or nil
+  # -->
+  # If `object` is an Array object, returns `object`.
+  #
+  # Otherwise if `object` responds to `:to_ary`, calls `object.to_ary` and returns
+  # the result.
   #
-  #     Array.try_convert([1])   #=> [1]
-  #     Array.try_convert("1")   #=> nil
+  # Returns `nil` if `object` does not respond to `:to_ary`
   #
-  #     if tmp = Array.try_convert(arg)
-  #       # the argument is an array
-  #     elsif tmp = String.try_convert(arg)
-  #       # the argument is a string
-  #     end
+  # Raises an exception unless `object.to_ary` returns an Array object.
   #
   def self.try_convert: [U] (untyped) -> ::Array[U]?
 
   public
 
-  # Set Intersection --- Returns a new array containing unique elements common to
-  # the two arrays. The order is preserved from the original array.
-  #
-  # It compares elements using their #hash and #eql? methods for efficiency.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array & other_array -> new_array
+  # -->
+  # Returns a new Array containing each element found in both `array` and Array
+  # `other_array`; duplicates are omitted; items are compared using `eql?`:
+  #     [0, 1, 2, 3] & [1, 2] # => [1, 2]
+  #     [0, 1, 0, 1] & [0, 1] # => [0, 1]
   #
-  #     [ 1, 1, 3, 5 ] & [ 3, 2, 1 ]                 #=> [ 1, 3 ]
-  #     [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ]   #=> [ 'a', 'b' ]
+  # Preserves order from `array`:
+  #     [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
   #
-  # See also Array#uniq.
+  # Related: Array#intersection.
   #
   def &: (::Array[untyped] | _ToAry[untyped]) -> ::Array[Elem]
 
-  # Repetition --- With a String argument, equivalent to `ary.join(str)`.
-  #
-  # Otherwise, returns a new array built by concatenating the `int` copies of
-  # `self`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array * n -> new_array
+  #   - array * string_separator -> new_string
+  # -->
+  # 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"]
   #
-  #     [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
-  #     [ 1, 2, 3 ] * ","  #=> "1,2,3"
+  # When String argument `string_separator` is given, equivalent to
+  # `array.join(string_separator)`:
+  #     [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
   #
   def *: (string str) -> ::String
        | (int int) -> ::Array[Elem]
 
-  # Concatenation --- Returns a new array built by concatenating the two arrays
-  # together to produce a third array.
-  #
-  #     [ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
-  #     a = [ "a", "b", "c" ]
-  #     c = a + [ "d", "e", "f" ]
-  #     c                         #=> [ "a", "b", "c", "d", "e", "f" ]
-  #     a                         #=> [ "a", "b", "c" ]
-  #
-  # Note that
-  #     x += y
-  #
-  # is the same as
-  #     x = x + y
+  # <!--
+  #   rdoc-file=array.c
+  #   - array + other_array -> new_array
+  # -->
+  # 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]
   #
-  # This means that it produces a new array. As a consequence, repeated use of
-  # `+=` on arrays can be quite inefficient.
-  #
-  # See also Array#concat.
+  # Related: #concat.
   #
   def +: [U] (_ToAry[U]) -> ::Array[Elem | U]
 
-  # Array Difference
-  #
-  # Returns a new array that is a copy of the original array, removing all
-  # occurrences of any item that also appear in `other_ary`. The order is
-  # preserved from the original array.
-  #
-  # It compares elements using their #hash and #eql? methods for efficiency.
-  #
-  #     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
-  #
-  # Note that while 1 and 2 were only present once in the array argument, and were
-  # present twice in the receiver array, all occurrences of each Integer are
-  # removed in the returned array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array - other_array -> new_array
+  # -->
+  # Returns a new Array containing only those elements from `array` that are not
+  # found in Array `other_array`; items are compared using `eql?`; 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]
   #
-  # If you need set-like behavior, see the library class Set.
-  #
-  # See also Array#difference.
+  # Related: Array#difference.
   #
   def -: (_ToAry[untyped]) -> ::Array[Elem]
 
-  # Append---Pushes the given object on to the end of this array. This expression
-  # returns the array itself, so several appends may be chained together.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array << object -> self
+  # -->
+  # Appends `object` to `self`; returns `self`:
+  #     a = [:foo, 'bar', 2]
+  #     a << :baz # => [:foo, "bar", 2, :baz]
   #
-  #     a = [ 1, 2 ]
-  #     a << "c" << "d" << [ 3, 4 ]
-  #             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
-  #     a
-  #             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
+  # 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]]
   #
   def <<: (Elem) -> self
 
-  # Comparison --- Returns an integer (`-1`, `0`, or `+1`) if this array is less
-  # than, equal to, or greater than `other_ary`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array <=> other_array -> -1, 0, or 1
+  # -->
+  # Returns -1, 0, or 1 as `self` is less than, equal to, or greater than
+  # `other_array`. For each index `i` in `self`, evaluates `result = self[i] <=>
+  # other_array[i]`.
   #
-  # Each object in each array is compared (using the <=> operator).
+  # Returns -1 if any result is -1:
+  #     [0, 1, 2] <=> [0, 1, 3] # => -1
   #
-  # Arrays are compared in an "element-wise" manner; the first element of `ary` is
-  # compared with the first one of `other_ary` using the <=> operator, then each
-  # of the second elements, etc... As soon as the result of any such comparison is
-  # non zero (i.e. the two corresponding elements are not equal), that result is
-  # returned for the whole array comparison.
+  # Returns 1 if any result is 1:
+  #     [0, 1, 2] <=> [0, 1, 1] # => 1
   #
-  # If all the elements are equal, then the result is based on a comparison of the
-  # array lengths. Thus, two arrays are "equal" according to Array#<=> if, and
-  # only if, they have the same length and the value of each element is equal to
-  # the value of the corresponding element in the other array.
+  # When all results are zero:
+  # *   Returns -1 if `array` is smaller than `other_array`:
+  #         [0, 1, 2] <=> [0, 1, 2, 3] # => -1
   #
-  # `nil` is returned if the `other_ary` is not an array or if the comparison of
-  # two elements returned `nil`.
+  # *   Returns 1 if `array` is larger than `other_array`:
+  #         [0, 1, 2] <=> [0, 1] # => 1
   #
-  #     [ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
-  #     [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
-  #     [ 1, 2 ]             <=> [ 1, :two ]         #=> nil
+  # *   Returns 0 if `array` and `other_array` are the same size:
+  #         [0, 1, 2] <=> [0, 1, 2] # => 0
   #
   def <=>: (untyped) -> ::Integer?
 
-  # Equality --- Two arrays are equal if they contain the same number of elements
-  # and if each element is equal to (according to Object#==) the corresponding
-  # element in `other_ary`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array == other_array -> true or false
+  # -->
+  # Returns `true` if both `array.size == other_array.size` and for each index `i`
+  # in `array`, `array[i] == other_array[i]`:
+  #     a0 = [:foo, 'bar', 2]
+  #     a1 = [:foo, 'bar', 2.0]
+  #     a1 == a0 # => true
+  #     [] == [] # => true
+  #
+  # Otherwise, returns `false`.
   #
-  #     [ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
-  #     [ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
-  #     [ "a", "c", 7 ] == [ "a", "d", "f" ]   #=> false
+  # This method is different from method Array#eql?, which compares elements using
+  # `Object#eql?`.
   #
   def ==: (untyped other) -> bool
 
-  # Element Reference --- Returns the element at `index`, or returns a subarray
-  # starting at the `start` index and continuing for `length` elements, or returns
-  # a subarray specified by `range` of indices.
-  #
-  # Negative indices count backward from the end of the array (-1 is the last
-  # element).  For `start` and `range` cases the starting index is just before an
-  # element.  Additionally, an empty array is returned when the starting index for
-  # an element range is at the end of the array.
-  #
-  # Returns `nil` if the index (or starting index) are out of range.
-  #
-  #     a = [ "a", "b", "c", "d", "e" ]
-  #     a[2] +  a[0] + a[1]    #=> "cab"
-  #     a[6]                   #=> nil
-  #     a[1, 2]                #=> [ "b", "c" ]
-  #     a[1..3]                #=> [ "b", "c", "d" ]
-  #     a[4..7]                #=> [ "e" ]
-  #     a[6..10]               #=> nil
-  #     a[-3, 3]               #=> [ "c", "d", "e" ]
-  #     # special cases
-  #     a[5]                   #=> nil
-  #     a[6, 1]                #=> nil
-  #     a[5, 1]                #=> []
-  #     a[5..10]               #=> []
+  # <!--
+  #   rdoc-file=array.c
+  #   - array[index] -> object or nil
+  #   - array[start, length] -> object or nil
+  #   - array[range] -> object or nil
+  #   - array[aseq] -> object or nil
+  #   - array.slice(index) -> object or nil
+  #   - array.slice(start, length) -> object or nil
+  #   - array.slice(range) -> object or nil
+  #   - array.slice(aseq) -> object or nil
+  # -->
+  # 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"
+  #
+  # If `index` is out of range, returns `nil`.
+  #
+  # 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 `start + length` is greater than `self.length`, returns all elements from
+  # offset `start` to the end:
+  #     a = [:foo, 'bar', 2]
+  #     a[0, 4] # => [:foo, "bar", 2]
+  #     a[1, 3] # => ["bar", 2]
+  #     a[2, 2] # => [2]
+  #
+  # If `start == self.size` and `length >= 0`, returns a new empty Array.
+  #
+  # If `length` is negative, returns `nil`.
+  #
+  # When a single Range argument `range` is given, treats `range.min` as `start`
+  # above and `range.size` as `length` above:
+  #     a = [:foo, 'bar', 2]
+  #     a[0..1] # => [:foo, "bar"]
+  #     a[1..2] # => ["bar", 2]
+  #
+  # Special case: If `range.start == a.size`, returns a new empty Array.
+  #
+  # If `range.end` 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 `range.start` 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 `range.start` is larger than the array size, returns `nil`.
+  #     a = [:foo, 'bar', 2]
+  #     a[4..1] # => nil
+  #     a[4..0] # => nil
+  #     a[4..-1] # => nil
+  #
+  # 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)
+  #     a[(7..).step(2)]
+  #     # RangeError (((7..).step(2)) out of range)
+  #
+  # 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]
+  #
+  # Array#slice is an alias for Array#[].
   #
   def []: (int index) -> Elem
         | (int start, int length) -> ::Array[Elem]?
         | (::Range[::Integer?] range) -> ::Array[Elem]?
 
-  # Element Assignment --- Sets the element at `index`, or replaces a subarray
-  # from the `start` index for `length` elements, or replaces a subarray specified
-  # by the `range` of indices.
-  #
-  # If indices are greater than the current capacity of the array, the array grows
-  # automatically.  Elements are inserted into the array at `start` if `length` is
-  # zero.
-  #
-  # Negative indices will count backward from the end of the array.  For `start`
-  # and `range` cases the starting index is just before an element.
-  #
-  # An IndexError is raised if a negative index points past the beginning of the
-  # array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array[index] = object -> object
+  #   - array[start, length] = object -> object
+  #   - array[range] = object -> object
+  # -->
+  # Assigns elements in `self`; returns the given `object`.
   #
-  # See also Array#push, and Array#unshift.
+  # When Integer argument `index` is given, assigns `object` to an element in
+  # `self`.
   #
-  #     a = Array.new
-  #     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
-  #     a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
-  #     a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
-  #     a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
-  #     a[0..2] = "A"               #=> ["A", "4"]
-  #     a[-1]   = "Z"               #=> ["A", "Z"]
-  #     a[1..-1] = nil              #=> ["A", nil]
-  #     a[1..-1] = []               #=> ["A"]
-  #     a[0, 0] = [ 1, 2 ]          #=> [1, 2, "A"]
-  #     a[3, 0] = "B"               #=> [1, 2, "A", "B"]
+  # 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 `self.length`, 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"]
+  #
+  # When Integer arguments `start` and `length` are given and `object` is not an
+  # Array, removes `length - 1` 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"]
+  #
+  # If `start` is non-negative and outside the array (` >= self.size`), 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"]
+  #
+  # When Range argument `range` is given and `object` is an Array, removes `length
+  # - 1` elements beginning at offset `start`, and assigns `object` at offset
+  # `start`:
+  #     a = [:foo, 'bar', 2]
+  #     a[0..1] = 'foo' # => "foo"
+  #     a # => ["foo", 2]
+  #
+  # if `range.begin` 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 `range.begin`, assigns `object` at offset
+  # `range.begin`, and ignores `length`:
+  #     a = [:foo, 'bar', 2]
+  #     a[6..50] = 'foo' # => "foo"
+  #     a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
+  #
+  # If `range.end` 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 `range.end` is negative, assigns `object` at offset `start`, retains
+  # `range.end.abs -1` elements past that, and removes those beyond:
+  #     a = [:foo, 'bar', 2]
+  #     a[1..-1] = 'foo' # => "foo"
+  #     a # => [:foo, "foo"]
+  #     a = [:foo, 'bar', 2]
+  #     a[1..-2] = 'foo' # => "foo"
+  #     a # => [:foo, "foo", 2]
+  #     a = [:foo, 'bar', 2]
+  #     a[1..-3] = 'foo' # => "foo"
+  #     a # => [:foo, "foo", "bar", 2]
+  #     a = [:foo, 'bar', 2]
+  #
+  # If `range.end` 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"]
   #
   def []=: (int index, Elem obj) -> Elem
          | (int start, int length, Elem obj) -> Elem
@@ -490,425 +961,790 @@ class Array[unchecked out Elem] < Object
          | (::Range[::Integer?], ::Array[Elem]) -> ::Array[Elem]
          | (::Range[::Integer?], nil) -> nil
 
-  # See also Enumerable#all?
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.all? -> true or false
+  #   - array.all? {|element| ... } -> true or false
+  #   - array.all?(obj) -> true or false
+  # -->
+  # Returns `true` if all elements of `self` meet a given criterion.
+  #
+  # 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 `obj.===` every element, `false`
+  # otherwise:
+  #     ['food', 'fool', 'foot'].all?(/foo/) # => true
+  #     ['food', 'drink'].all?(/bar/) # => false
+  #     [].all?(/foo/) # => true
+  #     [0, 0, 0].all?(0) # => true
+  #     [0, 1, 2].all?(1) # => false
+  #
+  # Related: Enumerable#all?
   #
   def all?: () -> bool
           | (_Pattern[Elem] pattern) -> bool
           | () { (Elem obj) -> boolish } -> bool
 
-  # See also Enumerable#any?
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.any? -> true or false
+  #   - array.any? {|element| ... } -> true or false
+  #   - array.any?(obj) -> true or false
+  # -->
+  # Returns `true` if any element of `self` meets a given criterion.
+  #
+  # 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`.`===` any element, `false`
+  # otherwise:
+  #     ['food', 'drink'].any?(/foo/) # => true
+  #     ['food', 'drink'].any?(/bar/) # => false
+  #     [].any?(/foo/) # => false
+  #     [0, 1, 2].any?(1) # => true
+  #     [0, 1, 2].any?(3) # => false
+  #
+  # Related: Enumerable#any?
   #
   alias any? all?
 
-  alias append push
-
-  # Searches through an array whose elements are also arrays comparing `obj` with
-  # the first element of each contained array using `obj.==`.
+  # <!-- rdoc-file=array.c -->
+  # Appends trailing elements.
   #
-  # Returns the first contained array that matches (that is, the first associated
-  # array), or `nil` if no match is found.
+  # Appends each argument in `objects` to `self`;  returns `self`:
+  #     a = [:foo, 'bar', 2]
+  #     a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
   #
-  # See also Array#rassoc
+  # 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]]
   #
-  #     s1 = [ "colors", "red", "blue", "green" ]
-  #     s2 = [ "letters", "a", "b", "c" ]
-  #     s3 = "foo"
-  #     a  = [ s1, s2, s3 ]
-  #     a.assoc("letters")  #=> [ "letters", "a", "b", "c" ]
-  #     a.assoc("foo")      #=> nil
+  # Array#append is an alias for Array#push.
   #
-  def assoc: (untyped) -> ::Array[untyped]?
-
-  # Returns the element at `index`. A negative index counts from the end of
-  # `self`. Returns `nil` if the index is out of range. See also Array#[].
+  # Related: #pop, #shift, #unshift.
   #
-  #     a = [ "a", "b", "c", "d", "e" ]
-  #     a.at(0)     #=> "a"
-  #     a.at(-1)    #=> "e"
-  #
-  def at: (int index) -> Elem?
+  alias append push
 
-  # By using binary search, finds a value from this array which meets the given
-  # condition in O(log n) where n is the size of the array.
-  #
-  # You can use this method in two modes: a find-minimum mode and a find-any mode.
-  #  In either case, the elements of the array must be monotone (or sorted) with
-  # respect to the block.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.assoc(obj) -> found_array or nil
+  # -->
+  # Returns the first element in `self` that is an Array whose first element `==`
+  # `obj`:
+  #     a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
+  #     a.assoc(4) # => [4, 5, 6]
   #
-  # In find-minimum mode (this is a good choice for typical use cases), the block
-  # must always return true or false, and there must be an index i (0 <= i <=
-  # ary.size) so that:
+  # Returns `nil` if no such element is found.
   #
-  # *   the block returns false for any element whose index is less than i, and
-  # *   the block returns true for any element whose index is greater than or
-  #     equal to i.
+  # Related: #rassoc.
   #
+  def assoc: (untyped) -> ::Array[untyped]?
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.at(index) -> object
+  # -->
+  # Returns the element at Integer offset `index`; does not modify `self`.
+  #     a = [:foo, 'bar', 2]
+  #     a.at(0) # => :foo
+  #     a.at(2) # => 2
   #
-  # This method returns the i-th element.  If i is equal to ary.size, it returns
-  # nil.
-  #
-  #     ary = [0, 4, 7, 10, 12]
-  #     ary.bsearch {|x| x >=   4 } #=> 4
-  #     ary.bsearch {|x| x >=   6 } #=> 7
-  #     ary.bsearch {|x| x >=  -1 } #=> 0
-  #     ary.bsearch {|x| x >= 100 } #=> nil
-  #
-  # In find-any mode (this behaves like libc's bsearch(3)), the block must always
-  # return a number, and there must be two indices i and j (0 <= i <= j <=
-  # ary.size) so that:
-  #
-  # *   the block returns a positive number for [ary](k) if 0 <= k < i,
-  # *   the block returns zero for [ary](k) if i <= k < j, and
-  # *   the block returns a negative number for [ary](k) if j <= k < ary.size.
-  #
-  #
-  # Under this condition, this method returns any element whose index is within
-  # i...j.  If i is equal to j (i.e., there is no element that satisfies the
-  # block), this method returns nil.
-  #
-  #     ary = [0, 4, 7, 10, 12]
-  #     # try to find v such that 4 <= v < 8
-  #     ary.bsearch {|x| 1 - x / 4 } #=> 4 or 7
-  #     # try to find v such that 8 <= v < 10
-  #     ary.bsearch {|x| 4 - x / 2 } #=> nil
+  def at: (int index) -> Elem?
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.bsearch {|element| ... } -> object
+  #   - array.bsearch -> new_enumerator
+  # -->
+  # Returns an element from `self` selected by a binary search.
   #
-  # You must not mix the two modes at a time; the block must always return either
-  # true/false, or always return a number.  It is undefined which value is
-  # actually picked up at each iteration.
+  # See [Binary Searching](rdoc-ref:bsearch.rdoc).
   #
   def bsearch: () -> ::Enumerator[Elem, Elem?]
              | () { (Elem) -> (true | false) } -> Elem?
              | () { (Elem) -> ::Integer } -> Elem?
 
-  # By using binary search, finds an index of a value from this array which meets
-  # the given condition in O(log n) where n is the size of the array.
-  #
-  # It supports two modes, depending on the nature of the block. They are exactly
-  # the same as in the case of the #bsearch method, with the only difference being
-  # that this method returns the index of the element instead of the element
-  # itself. For more details consult the documentation for #bsearch.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.bsearch_index {|element| ... } -> integer or nil
+  #   - array.bsearch_index -> new_enumerator
+  # -->
+  # Searches `self` as described at method #bsearch, but returns the *index* of
+  # the found element instead of the element itself.
   #
   def bsearch_index: () { (Elem) -> (true | false) } -> ::Integer?
                    | () { (Elem) -> ::Integer } -> ::Integer?
 
-  # Removes all elements from `self`.
-  #
-  #     a = [ "a", "b", "c", "d", "e" ]
-  #     a.clear    #=> [ ]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.clear -> self
+  # -->
+  # Removes all elements from `self`:
+  #     a = [:foo, 'bar', 2]
+  #     a.clear # => []
   #
   def clear: () -> self
 
-  # Invokes the given block once for each element of `self`.
-  #
-  # Creates a new array containing the values returned by the block.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.map {|element| ... } -> new_array
+  #   - array.map -> new_enumerator
+  # -->
+  # 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]
   #
-  # See also Enumerable#collect.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2]
+  #     a1 = a.map
+  #     a1 # => #<Enumerator: [:foo, "bar", 2]:map>
   #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  #     a = [ "a", "b", "c", "d" ]
-  #     a.collect {|x| x + "!"}           #=> ["a!", "b!", "c!", "d!"]
-  #     a.map.with_index {|x, i| x * i}   #=> ["", "b", "cc", "ddd"]
-  #     a                                 #=> ["a", "b", "c", "d"]
+  # Array#collect is an alias for Array#map.
   #
   def collect: [U] () { (Elem item) -> U } -> ::Array[U]
              | () -> ::Enumerator[Elem, ::Array[untyped]]
 
-  # Invokes the given block once for each element of `self`, replacing the element
-  # with the value returned by the block.
-  #
-  # See also Enumerable#collect.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.map! {|element| ... } -> self
+  #   - array.map! -> new_enumerator
+  # -->
+  # 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]
   #
-  # If no block is given, an Enumerator is returned instead.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2]
+  #     a1 = a.map!
+  #     a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
   #
-  #     a = [ "a", "b", "c", "d" ]
-  #     a.map! {|x| x + "!" }
-  #     a #=>  [ "a!", "b!", "c!", "d!" ]
-  #     a.collect!.with_index {|x, i| x[0...i] }
-  #     a #=>  ["", "b", "c!", "d!"]
+  # Array#collect! is an alias for Array#map!.
   #
-  # collect! is monomorphic because of RBS limitation.
   def collect!: () { (Elem item) -> Elem } -> self
               | () -> ::Enumerator[Elem, self]
 
-  # When invoked with a block, yields all combinations of length `n` of elements
-  # from the array and then returns the array itself.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.combination(n) {|element| ... } -> self
+  #   - array.combination(n) -> new_enumerator
+  # -->
+  # Calls the block, if given, with combinations of elements of `self`; returns
+  # `self`. The order of combinations is indeterminate.
   #
-  # The implementation makes no guarantees about the order in which the
-  # combinations are yielded.
+  # When a block and an in-range positive Integer argument `n` (`0 < n <=
+  # self.size`) are given, calls the block with all `n`-tuple combinations of
+  # `self`.
   #
-  # If no block is given, an Enumerator is returned instead.
+  # Example:
+  #     a = [0, 1, 2]
+  #     a.combination(2) {|combination| p combination }
   #
-  # Examples:
+  # Output:
+  #     [0, 1]
+  #     [0, 2]
+  #     [1, 2]
+  #
+  # Another example:
+  #     a = [0, 1, 2]
+  #     a.combination(3) {|combination| p combination }
+  #
+  # Output:
+  #     [0, 1, 2]
   #
-  #     a = [1, 2, 3, 4]
-  #     a.combination(1).to_a  #=> [[1],[2],[3],[4]]
-  #     a.combination(2).to_a  #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
-  #     a.combination(3).to_a  #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
-  #     a.combination(4).to_a  #=> [[1,2,3,4]]
-  #     a.combination(0).to_a  #=> [[]] # one combination of length 0
-  #     a.combination(5).to_a  #=> []   # no combinations of length 5
+  # 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 `self.size`), 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)>
   #
   def combination: (int n) { (::Array[Elem]) -> void } -> self
                  | (int n) -> ::Enumerator[::Array[Elem], self]
 
-  # Returns a copy of `self` with all `nil` elements removed.
-  #
-  #     [ "a", nil, "b", nil, "c", nil ].compact
-  #                       #=> [ "a", "b", "c" ]
+  # <!--
+  #   rdoc-file=array.c
+  #   - 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]
   #
   def compact: () -> ::Array[Elem]
 
-  # Removes `nil` elements from the array.
-  #
-  # Returns `nil` if no changes were made, otherwise returns the array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.compact! -> self or nil
+  # -->
+  # Removes all `nil` elements from `self`.
   #
-  #     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
-  #     [ "a", "b", "c" ].compact!           #=> nil
+  # Returns `self` if any elements removed, otherwise `nil`.
   #
   def compact!: () -> self?
 
-  # Appends the elements of `other_ary`s to `self`.
-  #
-  #     [ "a", "b" ].concat( ["c", "d"])   #=> [ "a", "b", "c", "d" ]
-  #     [ "a" ].concat( ["b"], ["c", "d"]) #=> [ "a", "b", "c", "d" ]
-  #     [ "a" ].concat #=> [ "a" ]
-  #
-  #     a = [ 1, 2, 3 ]
-  #     a.concat( [ 4, 5 ])
-  #     a                                 #=> [ 1, 2, 3, 4, 5 ]
-  #
-  #     a = [ 1, 2 ]
-  #     a.concat(a, a)                    #=> [1, 2, 1, 2, 1, 2]
-  #
-  # See also Array#+.
+  # <!--
+  #   rdoc-file=array.c
+  #   - 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]
   #
   def concat: (*::Array[Elem] arrays) -> self
 
-  # Returns the number of elements.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.count -> an_integer
+  #   - array.count(obj) -> an_integer
+  #   - array.count {|element| ... } -> an_integer
+  # -->
+  # Returns a count of specified elements.
   #
-  # If an argument is given, counts the number of elements which equal `obj` using
-  # `==`.
+  # With no argument and no block, returns the count of all elements:
+  #     [0, 1, 2].count # => 3
+  #     [].count # => 0
   #
-  # If a block is given, counts the number of elements for which the block returns
-  # a true value.
+  # With argument `obj`, returns the count of elements `==` to `obj`:
+  #     [0, 1, 2, 0.0].count(0) # => 2
+  #     [0, 1, 2].count(3) # => 0
   #
-  #     ary = [1, 2, 4, 2]
-  #     ary.count                  #=> 4
-  #     ary.count(2)               #=> 2
-  #     ary.count {|x| x%2 == 0}   #=> 3
+  # 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 `==` to `obj`:
   #
   def count: () -> ::Integer
            | (Elem obj) -> ::Integer
            | () { (Elem) -> boolish } -> ::Integer
 
-  # Calls the given block for each element `n` times or forever if `nil` is given.
-  #
-  # Does nothing if a non-positive number is given or the array is empty.
-  #
-  # Returns `nil` if the loop has finished without getting interrupted.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  #     a = ["a", "b", "c"]
-  #     a.cycle {|x| puts x}       # print, a, b, c, a, b, c,.. forever.
-  #     a.cycle(2) {|x| puts x}    # print, a, b, c, a, b, c.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.cycle {|element| ... } -> nil
+  #   - array.cycle(count) {|element| ... } -> nil
+  #   - array.cycle -> new_enumerator
+  #   - array.cycle(count) -> new_enumerator
+  # -->
+  # 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 }
+  #
+  # When no block is given, returns a new Enumerator:
+  #
+  #     [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]
   #
   def cycle: (?int? n) { (Elem) -> void } -> nil
            | (?int? n) -> ::Enumerator[Elem, nil]
 
+  # <!--
+  #   rdoc-file=array.c
+  #   - deconstruct()
+  # -->
+  #
   def deconstruct: () -> self
 
-  # Deletes all items from `self` that are equal to `obj`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.delete(obj) -> deleted_object
+  #   - array.delete(obj) {|nosuch| ... } -> deleted_object or block_return
+  # -->
+  # Removes zero or more elements from `self`; returns `self`.
+  #
+  # When no block is given, removes from `self` each element `ele` such that `ele
+  # == obj`; returns the last deleted element:
+  #     s1 = 'bar'; s2 = 'bar'
+  #     a = [:foo, s1, 2, s2]
+  #     a.delete('bar') # => "bar"
+  #     a # => [:foo, 2]
   #
-  # Returns the last deleted item, or `nil` if no matching item is found.
+  # Returns `nil` if no elements removed.
   #
-  # If the optional code block is given, the result of the block is returned if
-  # the item is not found.  (To remove `nil` elements and get an informative
-  # return value, use Array#compact!)
+  # When a block is given, removes from `self` each element `ele` such that `ele
+  # == obj`.
   #
-  #     a = [ "a", "b", "b", "b", "c" ]
-  #     a.delete("b")                   #=> "b"
-  #     a                               #=> ["a", "c"]
-  #     a.delete("z")                   #=> nil
-  #     a.delete("z") {"not found"}     #=> "not found"
+  # 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"
   #
   def delete: (Elem obj) -> Elem?
             | [S, T] (S obj) { (S) -> T } -> (Elem | T)
 
-  # Deletes the element at the specified `index`, returning that element, or `nil`
-  # if the `index` is out of range.
-  #
-  # See also Array#slice!
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.delete_at(index) -> deleted_object or nil
+  # -->
+  # Deletes an element from `self`, per the given Integer `index`.
   #
-  #     a = ["ant", "bat", "cat", "dog"]
-  #     a.delete_at(2)    #=> "cat"
-  #     a                 #=> ["ant", "bat", "dog"]
-  #     a.delete_at(99)   #=> nil
+  # When `index` is non-negative, deletes the element at offset `index`:
+  #     a = [:foo, 'bar', 2]
+  #     a.delete_at(1) # => "bar"
+  #     a # => [:foo, 2]
   #
-  def delete_at: (int index) -> Elem?
-
-  # Deletes every element of `self` for which block evaluates to `true`.
+  # If index is too large, returns `nil`.
   #
-  # The array is changed instantly every time the block is called, not after the
-  # iteration is over.
+  # When `index` is negative, counts backward from the end of the array:
+  #     a = [:foo, 'bar', 2]
+  #     a.delete_at(-2) # => "bar"
+  #     a # => [:foo, 2]
   #
-  # See also Array#reject!
+  # If `index` is too small (far from zero), returns nil.
   #
-  # If no block is given, an Enumerator is returned instead.
+  def delete_at: (int index) -> Elem?
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.delete_if {|element| ... } -> self
+  #   - array.delete_if -> Enumerator
+  # -->
+  # 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]
   #
-  #     scores = [ 97, 42, 75 ]
-  #     scores.delete_if {|score| score < 80 }   #=> [97]
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2]
+  #     a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>
   #
   def delete_if: () { (Elem item) -> boolish } -> self
                | () -> ::Enumerator[Elem, self]
 
-  # Array Difference
-  #
-  # Returns a new array that is a copy of the original array, removing all
-  # occurrences of any item that also appear in `other_ary`. The order is
-  # preserved from the original array.
-  #
-  # It compares elements using their #hash and #eql? methods for efficiency.
-  #
-  #     [ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ])     #=> [ 3, 3, 5 ]
-  #
-  # Note that while 1 and 2 were only present once in the array argument, and were
-  # present twice in the receiver array, all occurrences of each Integer are
-  # removed in the returned array.
-  #
-  # Multiple array arguments can be supplied and all occurrences of any element in
-  # those supplied arrays that match the receiver will be removed from the
-  # returned array.
-  #
-  #     [ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ])  #=> [ :s, "yep" ]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.difference(*other_arrays) -> new_array
+  # -->
+  # 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 `eql?`;
+  # 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]
   #
-  # If you need set-like behavior, see the library class Set.
+  # Returns a copy of `self` if no arguments given.
   #
-  # See also Array#-.
+  # Related: Array#-.
   #
   def difference: (*::Array[untyped] arrays) -> ::Array[Elem]
 
-  # Extracts the nested value specified by the sequence of *idx* objects by
-  # calling `dig` at each step, returning `nil` if any intermediate step is `nil`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.dig(index, *identifiers) -> object
+  # -->
+  # Finds and returns the object in nested objects that is specified by `index`
+  # and `identifiers`. The nested objects may be instances of various classes. See
+  # [Dig Methods](rdoc-ref:dig_methods.rdoc).
   #
-  #     a = [[1, [2, 3]]]
-  #
-  #     a.dig(0, 1, 1)                    #=> 3
-  #     a.dig(1, 2, 3)                    #=> nil
-  #     a.dig(0, 0, 0)                    #=> TypeError: Integer does not have #dig method
-  #     [42, {foo: :bar}].dig(1, :foo)    #=> :bar
+  # 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
   #
   def dig: (int idx) -> Elem?
          | (int idx, untyped, *untyped) -> untyped
 
-  # Drops first `n` elements from `ary` and returns the rest of the elements in an
-  # array.
-  #
-  # If a negative number is given, raises an ArgumentError.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.drop(n) -> new_array
+  # -->
+  # Returns a new Array containing all but the first `n` element of `self`, where
+  # `n` is a non-negative Integer; does not modify `self`.
   #
-  # See also Array#take
-  #
-  #     a = [1, 2, 3, 4, 5, 0]
-  #     a.drop(3)             #=> [4, 5, 0]
+  # 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]
   #
   def drop: (int n) -> ::Array[Elem]
 
-  # Drops elements up to, but not including, the first element for which the block
-  # returns `nil` or `false` and returns an array containing the remaining
-  # elements.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.drop_while {|element| ... } -> new_array
+  #   - array.drop_while -> new_enumerator
+  # -->
+  # Returns a new Array containing zero or more trailing elements of `self`; does
+  # not modify `self`.
   #
-  # If no block is given, an Enumerator is returned instead.
+  # 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]
   #
-  # See also Array#take_while
-  #
-  #     a = [1, 2, 3, 4, 5, 0]
-  #     a.drop_while {|i| i < 3 }   #=> [3, 4, 5, 0]
+  # With no block given, returns a new Enumerator:
+  #     [0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while>
   #
   def drop_while: () { (Elem obj) -> boolish } -> ::Array[Elem]
                 | () -> ::Enumerator[Elem, ::Array[Elem]]
 
-  # Calls the given block once for each element in `self`, passing that element as
-  # a parameter.  Returns the array itself.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.each {|element| ... } -> self
+  #   - array.each -> Enumerator
+  # -->
+  # Iterates over array elements.
   #
-  # If no block is given, an Enumerator is returned.
+  # 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}" }
   #
-  #     a = [ "a", "b", "c" ]
-  #     a.each {|x| print x, " -- " }
+  # 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
   #
-  # produces:
+  # 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}" }
   #
-  #     a -- b -- c --
+  # Output:
+  #     Symbol foo
+  #     String bar
+  #     Integer 2
+  #
+  # Related: #each_index, #reverse_each.
   #
   def each: () -> ::Enumerator[Elem, self]
           | () { (Elem item) -> void } -> self
 
-  # Same as Array#each, but passes the `index` of the element instead of the
-  # element itself.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.each_index {|index| ... } -> self
+  #   - array.each_index -> Enumerator
+  # -->
+  # Iterates over array indexes.
   #
-  # An Enumerator is returned if no block is given.
+  # 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]}" }
   #
-  #     a = [ "a", "b", "c" ]
-  #     a.each_index {|x| print x, " -- " }
+  # 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]}"}
   #
-  # produces:
+  # Output:
+  #     0 foo
+  #     1 bar
+  #     2 2
   #
-  #     0 -- 1 -- 2 --
+  # Related: #each, #reverse_each.
   #
   def each_index: () { (::Integer index) -> void } -> self
                 | () -> ::Enumerator[::Integer, self]
 
-  # Returns `true` if `self` contains no elements.
-  #
-  #     [].empty?   #=> true
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.empty?  -> true or false
+  # -->
+  # Returns `true` if the count of elements in `self` is zero, `false` otherwise.
   #
   def empty?: () -> bool
 
-  # Returns `true` if `self` and `other` are the same object, or are both arrays
-  # with the same content (according to Object#eql?).
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.eql? other_array -> true or false
+  # -->
+  # Returns `true` if `self` and `other_array` are the same size, and if, for each
+  # index `i` in `self`, `self[i].eql? other_array[i]`:
+  #     a0 = [:foo, 'bar', 2]
+  #     a1 = [:foo, 'bar', 2]
+  #     a1.eql?(a0) # => true
   #
-  def eql?: (untyped other) -> bool
-
-  # Tries to return the element at position `index`, but throws an IndexError
-  # exception if the referenced `index` lies outside of the array bounds.  This
-  # error can be prevented by supplying a second argument, which will act as a
-  # `default` value.
+  # Otherwise, returns `false`.
   #
-  # Alternatively, if a block is given it will only be executed when an invalid
-  # `index` is referenced.
+  # This method is different from method [Array#==](#method-i-3D-3D), which
+  # compares using method `Object#==`.
   #
-  # Negative values of `index` count from the end of the array.
-  #
-  #     a = [ 11, 22, 33, 44 ]
-  #     a.fetch(1)               #=> 22
-  #     a.fetch(-1)              #=> 44
-  #     a.fetch(4, 'cat')        #=> "cat"
-  #     a.fetch(100) {|i| puts "#{i} is out of bounds"}
-  #                              #=> "100 is out of bounds"
+  def eql?: (untyped other) -> bool
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.fetch(index) -> element
+  #   - array.fetch(index, default_value) -> element
+  #   - array.fetch(index) {|index| ... } -> element
+  # -->
+  # 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"
+  #
+  # If `index` is negative, counts from the end of the array:
+  #     a = [:foo, 'bar', 2]
+  #     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"
   #
   def fetch: (int index) -> Elem
            | [T] (int index, T default) -> (Elem | T)
            | [T] (int index) { (int index) -> T } -> (Elem | T)
 
-  # The first three forms set the selected elements of `self` (which may be the
-  # entire array) to `obj`.
-  #
-  # A `start` of `nil` is equivalent to zero.
-  #
-  # A `length` of `nil` is equivalent to the length of the array.
-  #
-  # The last three forms fill the array with the value of the given block, which
-  # is passed the absolute index of each element to be filled.
-  #
-  # Negative values of `start` count from the end of the array, where `-1` is the
-  # last element.
-  #
-  #     a = [ "a", "b", "c", "d" ]
-  #     a.fill("x")              #=> ["x", "x", "x", "x"]
-  #     a.fill("z", 2, 2)        #=> ["x", "x", "z", "z"]
-  #     a.fill("y", 0..1)        #=> ["y", "y", "z", "z"]
-  #     a.fill {|i| i*i}         #=> [0, 1, 4, 9]
-  #     a.fill(-2) {|i| i*i*i}   #=> [0, 1, 8, 27]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.fill(obj) -> self
+  #   - array.fill(obj, start) -> self
+  #   - array.fill(obj, start, length) -> self
+  #   - array.fill(obj, range) -> self
+  #   - array.fill {|index| ... } -> self
+  #   - array.fill(start) {|index| ... } -> self
+  #   - array.fill(start, length) {|index| ... } -> self
+  #   - array.fill(range) {|index| ... } -> self
+  # -->
+  # 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]
+  #
+  # With arguments `obj` and Integer `start`, and no block given, replaces
+  # elements based on the given start.
+  #
+  # If `start` is in range (`0 <= start < array.size`), 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 (`start >= array.size`), 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 `start +
+  # array.size`):
+  #     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']
+  #     a.fill(:X, -50) # => [:X, :X, :X, :X]
+  #
+  # With arguments `obj`, Integer `start`, and Integer `length`, and no block
+  # given, 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 (`start >= array.size`), 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"]
+  #
+  # With arguments `obj` and Range `range`, and no block given, replaces elements
+  # based on the given range.
+  #
+  # If the range is positive and ascending (`0 < range.begin <= range.end`),
+  # replaces elements from `range.begin` to `range.end`:
+  #     a = ['a', 'b', 'c', 'd']
+  #     a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]
+  #
+  # If `range.first` is negative, replaces no elements:
+  #     a = ['a', 'b', 'c', 'd']
+  #     a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]
+  #
+  # If `range.last` 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']
+  #     a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]
+  #
+  # If `range.last` and `range.last` 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']
+  #     a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]
+  #
+  # 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:
+  #
+  # If start is in range (`0 <= start < array.size`), 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(`start >= array.size`), 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 (`start <= -array.size`, 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']
+  #     a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
+  #
+  # With arguments `start` and `length`, and a block given, calls the block for
+  # each index specified by start length; 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 (`start >= array.size`), 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"]
+  #
+  # With arguments `obj` and `range`, and a block given, calls the block with each
+  # index in the given range; replaces the corresponding element with the block's
+  # return value.
+  #
+  # If the range is positive and ascending (`range 0 < range.begin <= range.end`,
+  # replaces elements from `range.begin` to `range.end`:
+  #     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 `range.last` 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']
+  #     a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]
+  #
+  # If `range.first` and `range.last` 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"]
   #
   def fill: (Elem obj) -> self
           | (Elem obj, int? start, ?int? length) -> self
@@ -916,299 +1752,592 @@ class Array[unchecked out Elem] < Object
           | (?int? start, ?int? length) { (::Integer index) -> Elem } -> self
           | (::Range[::Integer] range) { (::Integer index) -> Elem } -> self
 
-  # Returns a new array containing all elements of `ary` for which the given
-  # `block` returns a true value.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  #     [1,2,3,4,5].select {|num| num.even? }     #=> [2, 4]
-  #
-  #     a = %w[ a b c d e f ]
-  #     a.select {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]
+  # <!-- rdoc-file=array.c -->
+  # 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]
   #
-  # See also Enumerable#select.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2, :bam]
+  #     a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
   #
   # Array#filter is an alias for Array#select.
   #
   def filter: () { (Elem item) -> boolish } -> ::Array[Elem]
             | () -> ::Enumerator[Elem, ::Array[Elem]]
 
-  # Invokes the given block passing in successive elements from `self`, deleting
-  # elements for which the block returns a `false` value.
+  # <!-- rdoc-file=array.c -->
+  # Calls the block, if given  with each element of `self`; removes from `self`
+  # those elements for which the block returns `false` or `nil`.
   #
-  # The array may not be changed instantly every time the block is called.
+  # Returns `self` if any elements were removed:
+  #     a = [:foo, 'bar', 2, :bam]
+  #     a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
   #
-  # If changes were made, it will return `self`, otherwise it returns `nil`.
+  # Returns `nil` if no elements were removed.
   #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  # See also Array#keep_if.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2, :bam]
+  #     a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
   #
   # Array#filter! is an alias for Array#select!.
   #
   def filter!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
-  # Returns the *index* of the first object in `ary` such that the object is `==`
-  # to `obj`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.index(object) -> integer or nil
+  #   - array.index {|element| ... } -> integer or nil
+  #   - array.index -> new_enumerator
+  # -->
+  # Returns the index of a specified element.
   #
-  # If a block is given instead of an argument, returns the *index* of the first
-  # object for which the block returns `true`.  Returns `nil` if no match is
-  # found.
+  # When argument `object` is given but no block, returns the index of the first
+  # element `element` for which `object == element`:
+  #     a = [:foo, 'bar', 2, 'bar']
+  #     a.index('bar') # => 1
   #
-  # See also Array#rindex.
+  # Returns `nil` if no such element found.
   #
-  # An Enumerator is returned if neither a block nor argument is given.
+  # 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 = [ "a", "b", "c" ]
-  #     a.index("b")              #=> 1
-  #     a.index("z")              #=> nil
-  #     a.index {|x| x == "b"}    #=> 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
+  #
+  # Array#find_index is an alias for Array#index.
+  #
+  # Related: #rindex.
   #
   def find_index: (untyped obj) -> ::Integer?
                 | () { (Elem item) -> boolish } -> ::Integer?
                 | () -> ::Enumerator[Elem, ::Integer?]
 
-  # Returns the first element, or the first `n` elements, of the array. If the
-  # array is empty, the first form returns `nil`, and the second form returns an
-  # empty array. See also Array#last for the opposite effect.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.first -> object or nil
+  #   - array.first(n) -> new_array
+  # -->
+  # Returns elements from `self`; does not modify `self`.
   #
-  #     a = [ "q", "r", "s", "t" ]
-  #     a.first     #=> "q"
-  #     a.first(2)  #=> ["q", "r"]
+  # When no argument is given, returns the first element:
+  #     a = [:foo, 'bar', 2]
+  #     a.first # => :foo
+  #     a # => [:foo, "bar", 2]
   #
-  def first: () -> Elem?
-           | (int n) -> ::Array[Elem]
-
-  # Returns a new array that is a one-dimensional flattening of `self`
-  # (recursively).
+  # If `self` is empty, returns `nil`.
   #
-  # That is, for every element that is an array, extract its elements into the 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"]
   #
-  # The optional `level` argument determines the level of recursion to flatten.
+  # If `n >= array.size`, returns all elements:
+  #     a = [:foo, 'bar', 2]
+  #     a.first(50) # => [:foo, "bar", 2]
   #
-  #     s = [ 1, 2, 3 ]           #=> [1, 2, 3]
-  #     t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
-  #     a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
-  #     a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
-  #     a = [ 1, 2, [3, [4, 5] ] ]
-  #     a.flatten(1)              #=> [1, 2, 3, [4, 5]]
+  # If `n == 0` returns an new empty Array:
+  #     a = [:foo, 'bar', 2]
+  #     a.first(0) # []
   #
-  def flatten: (?int level) -> ::Array[untyped]
-
-  # Flattens `self` in place.
+  # Related: #last.
   #
-  # Returns `nil` if no modifications were made (i.e., the array contains no
-  # subarrays.)
-  #
-  # The optional `level` argument determines the level of recursion to flatten.
+  def first: () -> Elem?
+           | (int n) -> ::Array[Elem]
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.flatten -> new_array
+  #   - array.flatten(level) -> new_array
+  # -->
+  # Returns a new Array that is a recursive flattening of `self`:
+  # *   Each non-Array element is unchanged.
+  # *   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 ]
+  #     a.flatten(1) # => [0, 1, [2, 3], 4, 5]
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     a.flatten(2) # => [0, 1, 2, 3, 4, 5]
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     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]
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
+  #     [0, 1, 2].flatten(-1) # => [0, 1, 2]
   #
-  #     a = [ 1, 2, [3, [4, 5] ] ]
-  #     a.flatten!   #=> [1, 2, 3, 4, 5]
-  #     a.flatten!   #=> nil
-  #     a            #=> [1, 2, 3, 4, 5]
-  #     a = [ 1, 2, [3, [4, 5] ] ]
-  #     a.flatten!(1) #=> [1, 2, 3, [4, 5]]
+  def flatten: (?int level) -> ::Array[untyped]
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.flatten! -> self or nil
+  #   - array.flatten!(level) -> self or nil
+  # -->
+  # Replaces each nested Array in `self` with the elements from that Array;
+  # 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 ]
+  #     a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
+  #     [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
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
+  #     a = [ 0, [ 1, [2, 3], 4 ], 5 ]
+  #     a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
+  #     [0, 1, 2].flatten!(-1) # => nil
   #
   def flatten!: (?int level) -> self?
 
-  # Compute a hash-code for this array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.hash -> integer
+  # -->
+  # Returns the integer hash value for `self`.
   #
   # Two arrays with the same content will have the same hash code (and will
-  # compare using #eql?).
-  #
-  # See also Object#hash.
+  # compare using eql?):
+  #     [0, 1, 2].hash == [0, 1, 2].hash # => true
+  #     [0, 1, 2].hash == [0, 1, 3].hash # => false
   #
   def hash: () -> ::Integer
 
-  # Returns `true` if the given `object` is present in `self` (that is, if any
-  # element `==` `object`), otherwise returns `false`.
-  #
-  #     a = [ "a", "b", "c" ]
-  #     a.include?("b")   #=> true
-  #     a.include?("z")   #=> false
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.include?(obj) -> true or false
+  # -->
+  # Returns `true` if for some index `i` in `self`, `obj == self[i]`; otherwise
+  # `false`:
+  #     [0, 1, 2].include?(2) # => true
+  #     [0, 1, 2].include?(3) # => false
   #
   def include?: (Elem object) -> bool
 
-  # Returns the *index* of the first object in `ary` such that the object is `==`
-  # to `obj`.
+  # <!-- rdoc-file=array.c -->
+  # Returns the index of a specified element.
   #
-  # If a block is given instead of an argument, returns the *index* of the first
-  # object for which the block returns `true`.  Returns `nil` if no match is
-  # found.
+  # When argument `object` is given but no block, returns the index of the first
+  # element `element` for which `object == element`:
+  #     a = [:foo, 'bar', 2, 'bar']
+  #     a.index('bar') # => 1
   #
-  # See also Array#rindex.
+  # Returns `nil` if no such element found.
   #
-  # An Enumerator is returned if neither a block nor argument is given.
+  # 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 = [ "a", "b", "c" ]
-  #     a.index("b")              #=> 1
-  #     a.index("z")              #=> nil
-  #     a.index {|x| x == "b"}    #=> 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
+  #
+  # Array#find_index is an alias for Array#index.
+  #
+  # Related: #rindex.
   #
   alias index find_index
 
-  # Inserts the given values before the element with the given `index`.
-  #
-  # Negative indices count backwards from the end of the array, where `-1` is the
-  # last element. If a negative index is used, the given values will be inserted
-  # after that element, so using an index of `-1` will insert the values at the
-  # end of the array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.insert(index, *objects) -> self
+  # -->
+  # Inserts given `objects` before or after the element at Integer index `offset`;
+  # returns `self`.
   #
-  #     a = %w{ a b c d }
-  #     a.insert(2, 99)         #=> ["a", "b", 99, "c", "d"]
-  #     a.insert(-2, 1, 2, 3)   #=> ["a", "b", 99, "c", 1, 2, 3, "d"]
+  # 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 (`index >= self.size`):
+  #     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)
+  #     a.insert(-50)
+  #     a # => [:foo, "bar", 2]
+  #
+  # When `index` is negative, inserts all given `objects` *after* the element at
+  # offset `index+self.size`:
+  #     a = [:foo, 'bar', 2]
+  #     a.insert(-2, :bat, :bam)
+  #     a # => [:foo, "bar", :bat, :bam, 2]
   #
   def insert: (int index, *Elem obj) -> self
 
-  # Creates a string representation of `self`, by calling #inspect on each
-  # element.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.inspect -> new_string
+  # -->
+  # Returns the new String formed by calling method `#inspect` on each array
+  # element:
+  #     a = [:foo, 'bar', 2]
+  #     a.inspect # => "[:foo, \"bar\", 2]"
   #
-  #     [ "a", "b", "c" ].to_s     #=> "[\"a\", \"b\", \"c\"]"
+  # Array#to_s is an alias for Array#inspect.
   #
   def inspect: () -> String
 
-  # Set Intersection --- Returns a new array containing unique elements common to
-  # `self` and `other_ary`s. Order is preserved from the original array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - 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`.
+  #
+  #     a = [ 1, 2, 3 ]
+  #     b = [ 3, 4, 5 ]
+  #     c = [ 5, 6, 7 ]
+  #     a.intersect?(b)   #=> true
+  #     a.intersect?(c)   #=> false
+  #
+  def intersect?: (_ToAry[untyped]) -> bool
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.intersection(*other_arrays) -> new_array
+  # -->
+  # 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 `eql?`:
+  #     [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]
   #
-  # It compares elements using their #hash and #eql? methods for efficiency.
+  # Preserves order from `self`:
+  #     [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
   #
-  #     [ 1, 1, 3, 5 ].intersection([ 3, 2, 1 ])                    # => [ 1, 3 ]
-  #     [ "a", "b", "z" ].intersection([ "a", "b", "c" ], [ "b" ])  # => [ "b" ]
-  #     [ "a" ].intersection #=> [ "a" ]
+  # Returns a copy of `self` if no arguments given.
   #
-  # See also Array#&.
+  # Related: Array#&.
   #
   def intersection: (*::Array[untyped] | _ToAry[untyped] other_ary) -> ::Array[Elem]
 
-  # Returns a string created by converting each element of the array to a string,
-  # separated by the given `separator`. If the `separator` is `nil`, it uses
-  # current `$,`. If both the `separator` and `$,` are `nil`, it uses an empty
-  # string.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.join ->new_string
+  #   - array.join(separator = $,) -> new_string
+  # -->
+  # Returns the new String formed by joining the array elements after conversion.
+  # For each element `element`
+  # *   Uses `element.to_s` if `element` is not a `kind_of?(Array)`.
+  # *   Uses recursive `element.join(separator)` if `element` is a
+  #     `kind_of?(Array)`.
   #
-  #     [ "a", "b", "c" ].join        #=> "abc"
-  #     [ "a", "b", "c" ].join("-")   #=> "a-b-c"
   #
-  # For nested arrays, join is applied recursively:
+  # With no argument, joins using the output field separator, `$,`:
+  #     a = [:foo, 'bar', 2]
+  #     $, # => nil
+  #     a.join # => "foobar2"
   #
-  #     [ "a", [1, 2, [:x, :y]], "b" ].join("-")   #=> "a-1-2-x-y-b"
+  # 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"
   #
   def join: (?string separator) -> String
 
-  # Deletes every element of `self` for which the given block evaluates to
-  # `false`, and returns `self`.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  #     a = %w[ a b c d e f ]
-  #     a.keep_if {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]
-  #     a                                  #=> ["a", "e"]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.keep_if {|element| ... } -> self
+  #   - array.keep_if -> new_enumeration
+  # -->
+  # 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]
   #
-  # See also Array#select!.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2, :bam]
+  #     a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>
   #
   def keep_if: () { (Elem item) -> boolish } -> self
              | () -> ::Enumerator[Elem, self]
 
-  # Returns the last element(s) of `self`. If the array is empty, the first form
-  # returns `nil`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.last  -> object or nil
+  #   - array.last(n) -> new_array
+  # -->
+  # 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]
+  #
+  # If `self` is empty, returns `nil`.
   #
-  # See also Array#first for the opposite effect.
+  # 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]
   #
-  #     a = [ "w", "x", "y", "z" ]
-  #     a.last     #=> "z"
-  #     a.last(2)  #=> ["y", "z"]
+  # If `n >= array.size`, returns all elements:
+  #     a = [:foo, 'bar', 2]
+  #     a.last(50) # => [:foo, "bar", 2]
+  #
+  # If `n == 0`, returns an new empty Array:
+  #     a = [:foo, 'bar', 2]
+  #     a.last(0) # []
+  #
+  # Related: #first.
   #
   def last: () -> Elem?
           | (int n) -> ::Array[Elem]
 
-  # Returns the number of elements in `self`. May be zero.
-  #
-  #     [ 1, 2, 3, 4, 5 ].length   #=> 5
-  #     [].length                  #=> 0
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.length -> an_integer
+  # -->
+  # Returns the count of elements in `self`.
   #
   def length: () -> ::Integer
 
-  # Invokes the given block once for each element of `self`.
-  #
-  # Creates a new array containing the values returned by the block.
+  # <!-- rdoc-file=array.c -->
+  # 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]
   #
-  # See also Enumerable#collect.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2]
+  #     a1 = a.map
+  #     a1 # => #<Enumerator: [:foo, "bar", 2]:map>
   #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  #     a = [ "a", "b", "c", "d" ]
-  #     a.collect {|x| x + "!"}           #=> ["a!", "b!", "c!", "d!"]
-  #     a.map.with_index {|x, i| x * i}   #=> ["", "b", "cc", "ddd"]
-  #     a                                 #=> ["a", "b", "c", "d"]
+  # Array#collect is an alias for Array#map.
   #
   alias map collect
 
-  # Invokes the given block once for each element of `self`, replacing the element
-  # with the value returned by the block.
-  #
-  # See also Enumerable#collect.
+  # <!-- rdoc-file=array.c -->
+  # 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]
   #
-  # If no block is given, an Enumerator is returned instead.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2]
+  #     a1 = a.map!
+  #     a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
   #
-  #     a = [ "a", "b", "c", "d" ]
-  #     a.map! {|x| x + "!" }
-  #     a #=>  [ "a!", "b!", "c!", "d!" ]
-  #     a.collect!.with_index {|x, i| x[0...i] }
-  #     a #=>  ["", "b", "c!", "d!"]
+  # Array#collect! is an alias for Array#map!.
   #
   alias map! collect!
 
-  # Returns the object in *ary* with the maximum value. The first form assumes all
-  # objects implement Comparable; the second uses the block to return *a <=> b*.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.max -> element
+  #   - array.max {|a, b| ... } -> element
+  #   - array.max(n) -> new_array
+  #   - 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`.
+  #
+  #
+  # When no block is given, each element in `self` must respond to method `<=>`
+  # with an Integer.
+  #
+  # With no argument and no block, returns the element in `self` having the
+  # maximum value per method `<=>`:
+  #     [0, 1, 2].max # => 2
   #
-  #     ary = %w(albatross dog horse)
-  #     ary.max                                   #=> "horse"
-  #     ary.max {|a, b| a.length <=> b.length}    #=> "albatross"
+  # With an argument Integer `n` and no block, returns a new Array with at most
+  # `n` elements, in descending order per method `<=>`:
+  #     [0, 1, 2, 3].max(3) # => [3, 2, 1]
+  #     [0, 1, 2, 3].max(6) # => [3, 2, 1, 0]
   #
-  # If the `n` argument is given, maximum `n` elements are returned as an array.
+  # When a block is given, the block must return an Integer.
   #
-  #     ary = %w[albatross dog horse]
-  #     ary.max(2)                                  #=> ["horse", "dog"]
-  #     ary.max(2) {|a, b| a.length <=> b.length }  #=> ["albatross", "horse"]
+  # With a block and no argument, calls the block `self.size-1` 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"]
   #
   def max: () -> Elem?
          | () { (Elem a, Elem b) -> ::Integer? } -> Elem?
          | (int n) -> ::Array[Elem]
          | (int n) { (Elem a, Elem b) -> ::Integer? } -> ::Array[Elem]
 
-  # Returns the object in *ary* with the minimum value. The first form assumes all
-  # objects implement Comparable; the second uses the block to return *a <=> b*.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.min -> element
+  #   - array.min { |a, b| ... } -> element
+  #   - array.min(n) -> new_array
+  #   - 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`.
+  #
+  #
+  # When no block is given, each element in `self` must respond to method `<=>`
+  # with an Integer.
+  #
+  # With no argument and no block, returns the element in `self` having the
+  # minimum value per method `<=>`:
+  #     [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 `<=>`:
+  #     [0, 1, 2, 3].min(3) # => [0, 1, 2]
+  #     [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
   #
-  #     ary = %w(albatross dog horse)
-  #     ary.min                                   #=> "albatross"
-  #     ary.min {|a, b| a.length <=> b.length}    #=> "dog"
+  # When a block is given, the block must return an Integer.
   #
-  # If the `n` argument is given, minimum `n` elements are returned as an array.
+  # With a block and no argument, calls the block `self.size-1` 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"
   #
-  #     ary = %w[albatross dog horse]
-  #     ary.min(2)                                  #=> ["albatross", "dog"]
-  #     ary.min(2) {|a, b| a.length <=> b.length }  #=> ["dog", "horse"]
+  # 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"]
   #
   alias min max
 
-  # Returns a two element array which contains the minimum and the maximum value
-  # in the array.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.minmax -> [min_val, max_val]
+  #   - array.minmax {|a, b| ... } -> [min_val, max_val]
+  # -->
+  # Returns a new 2-element Array containing the minimum and maximum values from
+  # `self`, either per method `<=>` or per a given block:.
   #
-  # Can be given an optional block to override the default comparison method `a
-  # <=> b`.
+  # When no block is given, each element in `self` must respond to method `<=>`
+  # with an Integer; returns a new 2-element Array containing the minimum and
+  # maximum values from `self`, per method `<=>`:
+  #     [0, 1, 2].minmax # => [0, 2]
+  #
+  # When a block is given, the block must return an Integer; the block is called
+  # `self.size-1` 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"]
   #
   def minmax: () -> [ Elem?, Elem? ]
             | () { (Elem a, Elem b) -> ::Integer? } -> [ Elem?, Elem? ]
 
-  # See also Enumerable#none?
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.none? -> true or false
+  #   - array.none? {|element| ... } -> true or false
+  #   - array.none?(obj) -> true or false
+  # -->
+  # Returns `true` if no element of `self` meet a given criterion.
+  #
+  # 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 `obj.===` no element, `false`
+  # otherwise:
+  #     ['food', 'drink'].none?(/bar/) # => true
+  #     ['food', 'drink'].none?(/foo/) # => false
+  #     [].none?(/foo/) # => true
+  #     [0, 1, 2].none?(3) # => true
+  #     [0, 1, 2].none?(1) # => false
+  #
+  # Related: Enumerable#none?
   #
   alias none? all?
 
-  # See also Enumerable#one?
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.one? -> true or false
+  #   - array.one? {|element| ... } -> true or false
+  #   - array.one?(obj) -> true or false
+  # -->
+  # Returns `true` if exactly one element of `self` meets a given criterion.
+  #
+  # 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
+  #     [].one? # => false
+  #
+  # 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 `obj.===` exactly one element,
+  # `false` otherwise:
+  #     [0, 1, 2].one?(0) # => true
+  #     [0, 0, 1].one?(0) # => false
+  #     [1, 1, 2].one?(0) # => false
+  #     ['food', 'drink'].one?(/bar/) # => false
+  #     ['food', 'drink'].one?(/foo/) # => true
+  #     [].one?(/foo/) # => false
+  #
+  # Related: Enumerable#one?
   #
   alias one? none?
 
+  # <!--
+  #   rdoc-file=pack.rb
+  #   - arr.pack( aTemplateString ) -> aBinaryString
+  #   - arr.pack( aTemplateString, buffer: aBufferString ) -> aBufferString
+  # -->
   # Packs the contents of *arr* into a binary sequence according to the directives
   # in *aTemplateString* (see the table below) Directives ``A,'' ``a,'' and ``Z''
   # may be followed by a count, which gives the width of the resulting field. The
@@ -1233,6 +2362,16 @@ class Array[unchecked out Elem] < Object
   # *offsetOfBuffer* are overwritten by the result. If it's shorter, the gap is
   # filled with ```\0`''.
   #
+  #     # packed data is appended by default
+  #     [255].pack("C", buffer:"foo".b) #=> "foo\xFF"
+  #
+  #     # "@0" (offset 0) specifies that packed data is filled from beginning.
+  #     # Also, original data after packed data is removed. ("oo" is removed.)
+  #     [255].pack("@0C", buffer:"foo".b) #=> "\xFF"
+  #
+  #     # If the offset is bigger than the original length, \x00 is filled.
+  #     [255].pack("@5C", buffer:"foo".b) #=> "foo\x00\x00\xFF"
+  #
   # Note that ``buffer:'' option does not guarantee not to allocate memory in
   # `pack`.  If the capacity of *aBufferString* is not enough, `pack` allocates
   # memory.
@@ -1277,14 +2416,14 @@ class Array[unchecked out Elem] < Object
   #     S> s> S!> s!> | Integer | same as the directives without ">" except
   #     L> l> L!> l!> |         | big endian
   #     I!> i!>       |         | (available since Ruby 1.9.3)
-  #     Q> q> Q!> q!> |         | "S>" is same as "n"
-  #     J> j> J!> j!> |         | "L>" is same as "N"
+  #     Q> q> Q!> q!> |         | "S>" is the same as "n"
+  #     J> j> J!> j!> |         | "L>" is the same as "N"
   #                   |         |
   #     S< s< S!< s!< | Integer | same as the directives without "<" except
   #     L< l< L!< l!< |         | little endian
   #     I!< i!<       |         | (available since Ruby 1.9.3)
-  #     Q< q< Q!< q!< |         | "S<" is same as "v"
-  #     J< j< J!< j!< |         | "L<" is same as "V"
+  #     Q< q< Q!< q!< |         | "S<" is the same as "v"
+  #     J< j< J!< j!< |         | "L<" is the same as "V"
   #                   |         |
   #     n             | Integer | 16-bit unsigned, network (big-endian) byte order
   #     N             | Integer | 32-bit unsigned, network (big-endian) byte order
@@ -1333,659 +2472,1300 @@ class Array[unchecked out Elem] < Object
   #
   def pack: (string fmt, ?buffer: String?) -> String
 
-  # When invoked with a block, yield all permutations of length `n` of the
-  # elements of the array, then return the array itself.
-  #
-  # If `n` is not specified, yield all permutations of all elements.
-  #
-  # The implementation makes no guarantees about the order in which the
-  # permutations are yielded.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  # Examples:
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.permutation {|element| ... } -> self
+  #   - array.permutation(n) {|element| ... } -> self
+  #   - array.permutation -> new_enumerator
+  #   - array.permutation(n) -> new_enumerator
+  # -->
+  # When invoked with a block, yield all permutations of elements of `self`;
+  # returns `self`. The order of permutations is indeterminate.
+  #
+  # When a block and an in-range positive Integer argument `n` (`0 < n <=
+  # self.size`) are given, calls the block with all `n`-tuple permutations of
+  # `self`.
   #
-  #     a = [1, 2, 3]
-  #     a.permutation.to_a    #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
-  #     a.permutation(1).to_a #=> [[1],[2],[3]]
-  #     a.permutation(2).to_a #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
-  #     a.permutation(3).to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
-  #     a.permutation(0).to_a #=> [[]] # one permutation of length 0
-  #     a.permutation(4).to_a #=> []   # no permutations of length 4
+  # 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]
+  #     [1, 2, 0]
+  #     [2, 0, 1]
+  #     [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 `self.size`), 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
+  # `a.permutation(a.size)`:
+  #     a = [0, 1, 2]
+  #     a.permutation {|permutation| p permutation }
+  #
+  # Output:
+  #     [0, 1, 2]
+  #     [0, 2, 1]
+  #     [1, 0, 2]
+  #     [1, 2, 0]
+  #     [2, 0, 1]
+  #     [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)>
   #
   def permutation: (?int n) -> ::Enumerator[::Array[Elem], ::Array[Elem]]
                  | (?int n) { (::Array[Elem] p) -> void } -> ::Array[Elem]
 
-  # Removes the last element from `self` and returns it, or `nil` if the array is
-  # empty.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.pop -> object or nil
+  #   - array.pop(n) -> new_array
+  # -->
+  # Removes and returns trailing elements.
+  #
+  # 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"]
+  #
+  # Returns `nil` if the array is empty.
   #
-  # If a number `n` is given, returns an array of the last `n` elements (or less)
-  # just like `array.slice!(-n, n)` does. See also Array#push for the opposite
-  # effect.
+  # 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]
   #
-  #     a = [ "a", "b", "c", "d" ]
-  #     a.pop     #=> "d"
-  #     a.pop(2)  #=> ["b", "c"]
-  #     a         #=> ["a"]
+  # If `n` is positive and out of range, removes and returns all elements:
+  #     a = [:foo, 'bar', 2]
+  #     a.pop(50) # => [:foo, "bar", 2]
+  #
+  # Related: #push, #shift, #unshift.
   #
   def pop: () -> Elem?
          | (int n) -> ::Array[Elem]
 
-  alias prepend unshift
-
-  # Returns an array of all combinations of elements from all arrays.
-  #
-  # The length of the returned array is the product of the length of `self` and
-  # the argument arrays.
+  # <!-- rdoc-file=array.c -->
+  # Prepends the given `objects` to `self`:
+  #     a = [:foo, 'bar', 2]
+  #     a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
   #
-  # If given a block, #product will yield all combinations and return `self`
-  # instead.
+  # Array#prepend is an alias for Array#unshift.
   #
-  #     [1,2,3].product([4,5])     #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
-  #     [1,2].product([1,2])       #=> [[1,1],[1,2],[2,1],[2,2]]
-  #     [1,2].product([3,4],[5,6]) #=> [[1,3,5],[1,3,6],[1,4,5],[1,4,6],
-  #                                #     [2,3,5],[2,3,6],[2,4,5],[2,4,6]]
-  #     [1,2].product()            #=> [[1],[2]]
-  #     [1,2].product([])          #=> []
+  # Related: #push, #pop, #shift.
   #
-  def product: () -> ::Array[[Elem]]
-             | [X] (::Array[X] other_ary) -> ::Array[[Elem, X]]
-             | [X, Y] (::Array[X] other_ary1, ::Array[Y] other_ary2) -> ::Array[[Elem, X, Y]]
+  alias prepend unshift
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.product(*other_arrays) -> new_array
+  #   - 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`.
+  # *   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]
+  #     p = a.product(a1)
+  #     p.size # => 6 # a.size * a1.size
+  #     p # => [[0, 3], [0, 4], [1, 3], [1, 4], [2, 3], [2, 4]]
+  #     p = a.product(a1, a2)
+  #     p.size # => 12 # a.size * a1.size * a2.size
+  #     p # => [[0, 3, 5], [0, 3, 6], [0, 4, 5], [0, 4, 6], [1, 3, 5], [1, 3, 6], [1, 4, 5], [1, 4, 6], [2, 3, 5], [2, 3, 6], [2, 4, 5], [2, 4, 6]]
+  #
+  # If any argument is an empty Array, returns an empty Array.
+  #
+  # 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]
+  #     [1, 4]
+  #     [2, 3]
+  #     [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]
+  #
+  def product: () -> ::Array[[ Elem ]]
+             | [X] (::Array[X] other_ary) -> ::Array[[ Elem, X ]]
+             | [X, Y] (::Array[X] other_ary1, ::Array[Y] other_ary2) -> ::Array[[ Elem, X, Y ]]
              | [U] (*::Array[U] other_arys) -> ::Array[::Array[Elem | U]]
 
-  # Append --- Pushes the given object(s) on to the end of this array. This
-  # expression returns the array itself, so several appends may be chained
-  # together. See also Array#pop for the opposite effect.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.push(*objects) -> self
+  # -->
+  # Appends trailing elements.
   #
-  #     a = [ "a", "b", "c" ]
-  #     a.push("d", "e", "f")
-  #             #=> ["a", "b", "c", "d", "e", "f"]
-  #     [1, 2, 3].push(4).push(5)
-  #             #=> [1, 2, 3, 4, 5]
+  # Appends each argument in `objects` to `self`;  returns `self`:
+  #     a = [:foo, 'bar', 2]
+  #     a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
   #
-  def push: (*Elem obj) -> self
-
-  # Searches through the array whose elements are also arrays.
+  # 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]]
+  #
+  # Array#append is an alias for Array#push.
   #
-  # Compares `obj` with the second element of each contained array using `obj.==`.
+  # Related: #pop, #shift, #unshift.
   #
-  # Returns the first contained array that matches `obj`.
+  def push: (*Elem obj) -> self
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.rassoc(obj) -> found_array or nil
+  # -->
+  # Returns the first element in `self` that is an Array whose second element `==`
+  # `obj`:
+  #     a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
+  #     a.rassoc(4) # => [2, 4]
   #
-  # See also Array#assoc.
+  # Returns `nil` if no such element is found.
   #
-  #     a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
-  #     a.rassoc("two")    #=> [2, "two"]
-  #     a.rassoc("four")   #=> nil
+  # Related: #assoc.
   #
   alias rassoc assoc
 
-  # Returns a new array containing the items in `self` for which the given block
-  # is not `true`. The ordering of non-rejected elements is maintained.
-  #
-  # See also Array#delete_if
-  #
-  # If no block is given, an Enumerator is returned instead.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.reject {|element| ... } -> new_array
+  #   - array.reject -> new_enumerator
+  # -->
+  # 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>
   #
   alias reject delete_if
 
-  # Deletes every element of `self` for which the block evaluates to `true`, if no
-  # changes were made returns `nil`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.reject! {|element| ... } -> self or nil
+  #   - array.reject! -> new_enumerator
+  # -->
+  # Removes each element for which the block returns a truthy value.
   #
-  # The array may not be changed instantly every time the block is called.
+  # Returns `self` if any elements removed:
+  #     a = [:foo, 'bar', 2, 'bat']
+  #     a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
   #
-  # See also Enumerable#reject and Array#delete_if.
+  # Returns `nil` if no elements removed.
   #
-  # If no block is given, an Enumerator is returned instead.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2]
+  #     a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>
   #
   def reject!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
-  # When invoked with a block, yields all repeated combinations of length `n` of
-  # elements from the array and then returns the array itself.
-  #
-  # The implementation makes no guarantees about the order in which the repeated
-  # combinations are yielded.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  # Examples:
-  #
-  #     a = [1, 2, 3]
-  #     a.repeated_combination(1).to_a  #=> [[1], [2], [3]]
-  #     a.repeated_combination(2).to_a  #=> [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
-  #     a.repeated_combination(3).to_a  #=> [[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],
-  #                                     #    [1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]
-  #     a.repeated_combination(4).to_a  #=> [[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],
-  #                                     #    [1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],
-  #                                     #    [2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]
-  #     a.repeated_combination(0).to_a  #=> [[]] # one combination of length 0
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.repeated_combination(n) {|combination| ... } -> self
+  #   - array.repeated_combination(n) -> new_enumerator
+  # -->
+  # Calls the block with each repeated combination of length `n` of the elements
+  # of `self`; each combination is an Array; returns `self`. The order of the
+  # combinations is indeterminate.
+  #
+  # When a block and a positive Integer argument `n` are given, calls the block
+  # with each `n`-tuple repeated combination of the elements of `self`. The number
+  # of combinations is `(n+1)(n+2)/2`.
+  #
+  # `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]
+  #     [1, 1]
+  #     [1, 2]
+  #     [2, 2]
+  #
+  # 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 # => [[]]
+  #     e = a.repeated_combination(1)
+  #     e.size # => 3
+  #     e.to_a # => [[0], [1], [2]]
+  #     e = a.repeated_combination(2)
+  #     e.size # => 6
+  #     e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
   #
   def repeated_combination: (int n) { (::Array[Elem] c) -> void } -> self
                           | (int n) -> ::Enumerator[::Array[Elem], self]
 
-  # When invoked with a block, yield all repeated permutations of length `n` of
-  # the elements of the array, then return the array itself.
-  #
-  # The implementation makes no guarantees about the order in which the repeated
-  # permutations are yielded.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  # Examples:
-  #
-  #     a = [1, 2]
-  #     a.repeated_permutation(1).to_a  #=> [[1], [2]]
-  #     a.repeated_permutation(2).to_a  #=> [[1,1],[1,2],[2,1],[2,2]]
-  #     a.repeated_permutation(3).to_a  #=> [[1,1,1],[1,1,2],[1,2,1],[1,2,2],
-  #                                     #    [2,1,1],[2,1,2],[2,2,1],[2,2,2]]
-  #     a.repeated_permutation(0).to_a  #=> [[]] # one permutation of length 0
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.repeated_permutation(n) {|permutation| ... } -> self
+  #   - array.repeated_permutation(n) -> new_enumerator
+  # -->
+  # Calls the block with each repeated permutation of length `n` of the elements
+  # of `self`; each permutation is an Array; returns `self`. The order of the
+  # permutations is indeterminate.
+  #
+  # When a block and a positive Integer argument `n` are given, calls the block
+  # with each `n`-tuple repeated permutation of the elements of `self`. The number
+  # of permutations is `self.size**n`.
+  #
+  # `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]
+  #     [1, 0]
+  #     [1, 1]
+  #     [1, 2]
+  #     [2, 0]
+  #     [2, 1]
+  #     [2, 2]
+  #
+  # 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 # => [[]]
+  #     e = a.repeated_permutation(1)
+  #     e.size # => 3
+  #     e.to_a # => [[0], [1], [2]]
+  #     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]]
   #
   def repeated_permutation: (int n) { (::Array[Elem] p) -> void } -> self
                           | (int n) -> ::Enumerator[::Array[Elem], self]
 
-  # Replaces the contents of `self` with the contents of `other_ary`, truncating
-  # or expanding if necessary.
-  #
-  #     a = [ "a", "b", "c", "d", "e" ]
-  #     a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
-  #     a                              #=> ["x", "y", "z"]
+  # <!-- rdoc-file=array.c -->
+  # 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]
   #
   def replace: (::Array[Elem]) -> self
 
-  # Returns a new array containing `self`'s elements in reverse order.
-  #
-  #     [ "a", "b", "c" ].reverse   #=> ["c", "b", "a"]
-  #     [ 1 ].reverse               #=> [1]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.reverse -> new_array
+  # -->
+  # Returns a new Array with the elements of `self` in reverse order.
+  #     a = ['foo', 'bar', 'two']
+  #     a1 = a.reverse
+  #     a1 # => ["two", "bar", "foo"]
   #
   def reverse: () -> ::Array[Elem]
 
-  # Reverses `self` in place.
-  #
-  #     a = [ "a", "b", "c" ]
-  #     a.reverse!       #=> ["c", "b", "a"]
-  #     a                #=> ["c", "b", "a"]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.reverse! -> self
+  # -->
+  # Reverses `self` in place:
+  #     a = ['foo', 'bar', 'two']
+  #     a.reverse! # => ["two", "bar", "foo"]
   #
   def reverse!: () -> ::Array[Elem]
 
-  # Same as Array#each, but traverses `self` in reverse order.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.reverse_each {|element| ... } -> self
+  #   - array.reverse_each -> Enumerator
+  # -->
+  # Iterates backwards over array elements.
   #
-  #     a = [ "a", "b", "c" ]
-  #     a.reverse_each {|x| print x, " " }
+  # 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') }
   #
-  # produces:
+  # Output:
+  #     2
+  #     bar
   #
-  #     c b a
+  # 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
+  #
+  # Related: #each, #each_index.
   #
   def reverse_each: () { (Elem item) -> void } -> self
                   | () -> ::Enumerator[Elem, self]
 
-  # Returns the *index* of the last object in `self` `==` to `obj`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.rindex(object) -> integer or nil
+  #   - array.rindex {|element| ... } -> integer or nil
+  #   - array.rindex -> new_enumerator
+  # -->
+  # Returns the index of the last element for which `object == element`.
+  #
+  # 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.
   #
-  # If a block is given instead of an argument, returns the *index* of the first
-  # object for which the block returns `true`, starting from the last object.
+  # 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
   #
-  # Returns `nil` if no match is found.
+  # Returns `nil` if the block never returns a truthy value.
   #
-  # See also Array#index.
+  # When neither an argument nor a block is given, returns a new Enumerator:
   #
-  # If neither block nor argument is given, an Enumerator is returned instead.
+  #     a = [:foo, 'bar', 2, 'bar']
+  #     e = a.rindex
+  #     e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
+  #     e.each {|element| element == 'bar' } # => 3
   #
-  #     a = [ "a", "b", "b", "b", "c" ]
-  #     a.rindex("b")             #=> 3
-  #     a.rindex("z")             #=> nil
-  #     a.rindex {|x| x == "b"}   #=> 3
+  # Related: #index.
   #
   def rindex: (untyped obj) -> ::Integer?
             | () { (Elem item) -> boolish } -> ::Integer?
             | () -> ::Enumerator[Elem, ::Integer?]
 
-  # Returns a new array by rotating `self` so that the element at `count` is the
-  # first element of the new array.
-  #
-  # If `count` is negative then it rotates in the opposite direction, starting
-  # from the end of `self` where `-1` is the last element.
-  #
-  #     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"]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.rotate -> new_array
+  #   - array.rotate(count) -> new_array
+  # -->
+  # Returns a new Array formed from `self` with elements rotated from one end to
+  # the other.
+  #
+  # 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 `count % array.size` 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 `count % array.size` as the count:
+  #     a = [:foo, 'bar', 2]
+  #     a1 = a.rotate(-5)
+  #     a1 # => ["bar", 2, :foo]
   #
   def rotate: (?int count) -> ::Array[Elem]
 
-  # Rotates `self` in place so that the element at `count` comes first, and
-  # 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.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.rotate! -> self
+  #   - array.rotate!(count) -> self
+  # -->
+  # Rotates `self` in place by moving elements from one end to the other; returns
+  # `self`.
   #
-  #     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']
+  #     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 `count % array.size` 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 `count % array.size` as the count:
+  #     a = [:foo, 'bar', 2]
+  #     a.rotate!(-5)
+  #     a # => ["bar", 2, :foo]
   #
   def rotate!: (?int count) -> self
 
-  # Choose a random element or `n` random elements from the array.
+  # <!--
+  #   rdoc-file=array.rb
+  #   - array.sample(random: Random) -> object
+  #   - array.sample(n, random: Random) -> new_ary
+  # -->
+  # Returns random elements from `self`.
   #
-  # The elements are chosen by using random and unique indices into the array in
-  # order to ensure that an element doesn't repeat itself unless the array already
-  # contained duplicate elements.
+  # When no arguments are given, returns a random element from `self`:
+  #     a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+  #     a.sample # => 3
+  #     a.sample # => 8
   #
-  # If the array is empty the first form returns `nil` and the second form returns
-  # an empty array.
+  # If `self` is empty, returns `nil`.
   #
-  #     a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
-  #     a.sample         #=> 7
-  #     a.sample(4)      #=> [6, 4, 2, 5]
+  # When argument `n` is given, returns a new Array containing `n` random elements
+  # from `self`:
+  #     a.sample(3) # => [8, 9, 2]
+  #     a.sample(6) # => [9, 6, 10, 3, 1, 4]
   #
-  # The optional `rng` argument will be used as the random number generator.
+  # Returns no more than `a.size` elements (because no new duplicates are
+  # introduced):
+  #     a.sample(a.size * 2) # => [6, 4, 1, 8, 5, 9, 10, 2, 3, 7]
   #
+  # But `self` may contain duplicates:
+  #     a = [1, 1, 1, 2, 2, 3]
+  #     a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2]
+  #
+  # The argument `n` must be a non-negative numeric value. The order of the result
+  # array is unrelated to the order of `self`. Returns a new empty Array if `self`
+  # is empty.
+  #
+  # The optional `random` argument will be used as the random number generator:
+  #     a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
   #     a.sample(random: Random.new(1))     #=> 6
   #     a.sample(4, random: Random.new(1))  #=> [6, 10, 9, 2]
   #
   def sample: (?random: _Rand rng) -> Elem?
             | (int n, ?random: _Rand rng) -> ::Array[Elem]
 
-  # Returns a new array containing all elements of `ary` for which the given
-  # `block` returns a true value.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  #     [1,2,3,4,5].select {|num| num.even? }     #=> [2, 4]
-  #
-  #     a = %w[ a b c d e f ]
-  #     a.select {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]
-  #
-  # See also Enumerable#select.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.select {|element| ... } -> new_array
+  #   - array.select -> new_enumerator
+  # -->
+  # 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>
   #
   # Array#filter is an alias for Array#select.
   #
   def select: () { (Elem item) -> boolish } -> ::Array[Elem]
             | () -> ::Enumerator[Elem, ::Array[Elem]]
 
-  # Invokes the given block passing in successive elements from `self`, deleting
-  # elements for which the block returns a `false` value.
-  #
-  # The array may not be changed instantly every time the block is called.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.select! {|element| ... } -> self or nil
+  #   - array.select! -> new_enumerator
+  # -->
+  # Calls the block, if given  with each element of `self`; removes from `self`
+  # those elements for which the block returns `false` or `nil`.
   #
-  # If changes were made, it will return `self`, otherwise it returns `nil`.
+  # Returns `self` if any elements were removed:
+  #     a = [:foo, 'bar', 2, :bam]
+  #     a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
   #
-  # If no block is given, an Enumerator is returned instead.
+  # Returns `nil` if no elements were removed.
   #
-  # See also Array#keep_if.
+  # Returns a new Enumerator if no block given:
+  #     a = [:foo, 'bar', 2, :bam]
+  #     a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
   #
   # Array#filter! is an alias for Array#select!.
   #
   def select!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
-  # Removes the first element of `self` and returns it (shifting all other
-  # elements down by one). Returns `nil` if the array is empty.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.shift -> object or nil
+  #   - array.shift(n) -> new_array
+  # -->
+  # 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]
+  #
+  # Returns `nil` if `self` is empty.
+  #
+  # 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 a number `n` is given, returns an array of the first `n` elements (or less)
-  # just like `array.slice!(0, n)` does. With `ary` containing only the remainder
-  # elements, not including what was shifted to `new_ary`. See also Array#unshift
-  # for the opposite effect.
+  # If `n` is as large as or larger than `self.length`, removes all elements;
+  # returns those elements in a new Array:
+  #     a = [:foo, 'bar', 2]
+  #     a.shift(3) # => [:foo, 'bar', 2]
   #
-  #     args = [ "-m", "-q", "filename" ]
-  #     args.shift     #=> "-m"
-  #     args           #=> ["-q", "filename"]
+  # If `n` is zero, returns a new empty Array; `self` is unmodified.
   #
-  #     args = [ "-m", "-q", "filename" ]
-  #     args.shift(2)  #=> ["-m", "-q"]
-  #     args           #=> ["filename"]
+  # Related: #push, #pop, #unshift.
   #
   def shift: () -> Elem?
            | (int n) -> ::Array[Elem]
 
+  # <!--
+  #   rdoc-file=array.rb
+  #   - array.shuffle(random: Random) -> new_ary
+  # -->
   # Returns a new array with elements of `self` shuffled.
+  #     a = [1, 2, 3] #=> [1, 2, 3]
+  #     a.shuffle     #=> [2, 3, 1]
+  #     a             #=> [1, 2, 3]
   #
-  #     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
-  #     a.shuffle                 #=> [2, 3, 1]
-  #     a                         #=> [1, 2, 3]
-  #
-  # The optional `rng` argument will be used as the random number generator.
-  #
+  # The optional `random` argument will be used as the random number generator:
   #     a.shuffle(random: Random.new(1))  #=> [1, 3, 2]
   #
   def shuffle: (?random: _Rand rng) -> ::Array[Elem]
 
-  # Shuffles elements in `self` in place.
-  #
-  #     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
-  #     a.shuffle!                #=> [2, 3, 1]
-  #     a                         #=> [2, 3, 1]
-  #
-  # The optional `rng` argument will be used as the random number generator.
+  # <!--
+  #   rdoc-file=array.rb
+  #   - array.shuffle!(random: Random) -> array
+  # -->
+  # Shuffles the elements of `self` in place.
+  #     a = [1, 2, 3] #=> [1, 2, 3]
+  #     a.shuffle!    #=> [2, 3, 1]
+  #     a             #=> [2, 3, 1]
   #
+  # The optional `random` argument will be used as the random number generator:
   #     a.shuffle!(random: Random.new(1))  #=> [1, 3, 2]
   #
   def shuffle!: (?random: _Rand rng) -> self
 
+  # <!-- rdoc-file=array.c -->
+  # Returns the count of elements in `self`.
+  #
   alias size length
 
-  # Element Reference --- Returns the element at `index`, or returns a subarray
-  # starting at the `start` index and continuing for `length` elements, or returns
-  # a subarray specified by `range` of indices.
-  #
-  # Negative indices count backward from the end of the array (-1 is the last
-  # element).  For `start` and `range` cases the starting index is just before an
-  # element.  Additionally, an empty array is returned when the starting index for
-  # an element range is at the end of the array.
-  #
-  # Returns `nil` if the index (or starting index) are out of range.
-  #
-  #     a = [ "a", "b", "c", "d", "e" ]
-  #     a[2] +  a[0] + a[1]    #=> "cab"
-  #     a[6]                   #=> nil
-  #     a[1, 2]                #=> [ "b", "c" ]
-  #     a[1..3]                #=> [ "b", "c", "d" ]
-  #     a[4..7]                #=> [ "e" ]
-  #     a[6..10]               #=> nil
-  #     a[-3, 3]               #=> [ "c", "d", "e" ]
-  #     # special cases
-  #     a[5]                   #=> nil
-  #     a[6, 1]                #=> nil
-  #     a[5, 1]                #=> []
-  #     a[5..10]               #=> []
+  # <!-- rdoc-file=array.c -->
+  # 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"
+  #
+  # If `index` is out of range, returns `nil`.
+  #
+  # 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 `start + length` is greater than `self.length`, returns all elements from
+  # offset `start` to the end:
+  #     a = [:foo, 'bar', 2]
+  #     a[0, 4] # => [:foo, "bar", 2]
+  #     a[1, 3] # => ["bar", 2]
+  #     a[2, 2] # => [2]
+  #
+  # If `start == self.size` and `length >= 0`, returns a new empty Array.
+  #
+  # If `length` is negative, returns `nil`.
+  #
+  # When a single Range argument `range` is given, treats `range.min` as `start`
+  # above and `range.size` as `length` above:
+  #     a = [:foo, 'bar', 2]
+  #     a[0..1] # => [:foo, "bar"]
+  #     a[1..2] # => ["bar", 2]
+  #
+  # Special case: If `range.start == a.size`, returns a new empty Array.
+  #
+  # If `range.end` 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 `range.start` 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 `range.start` is larger than the array size, returns `nil`.
+  #     a = [:foo, 'bar', 2]
+  #     a[4..1] # => nil
+  #     a[4..0] # => nil
+  #     a[4..-1] # => nil
+  #
+  # 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)
+  #     a[(7..).step(2)]
+  #     # RangeError (((7..).step(2)) out of range)
+  #
+  # 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]
+  #
+  # Array#slice is an alias for Array#[].
   #
   def slice: (int index) -> Elem?
            | (int start, int length) -> ::Array[Elem]?
            | (::Range[::Integer] range) -> ::Array[Elem]?
 
-  # Deletes the element(s) given by an `index` (optionally up to `length`
-  # elements) or by a `range`.
-  #
-  # Returns the deleted object (or objects), or `nil` if the `index` is out of
-  # range.
-  #
-  #     a = [ "a", "b", "c" ]
-  #     a.slice!(1)     #=> "b"
-  #     a               #=> ["a", "c"]
-  #     a.slice!(-1)    #=> "c"
-  #     a               #=> ["a"]
-  #     a.slice!(100)   #=> nil
-  #     a               #=> ["a"]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.slice!(n) -> object or nil
+  #   - array.slice!(start, length) -> new_array or nil
+  #   - array.slice!(range) -> new_array or nil
+  # -->
+  # Removes and returns elements from `self`.
+  #
+  # 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"]
+  #
+  # If `n` is out of range, returns `nil`.
+  #
+  # 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 `start + length` 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]
+  #
+  # If `start == a.size` and `length` is non-negative, returns a new empty Array.
+  #
+  # If `length` is negative, returns `nil`.
+  #
+  # When the only argument is a Range object `range`, treats `range.min` as
+  # `start` above and `range.size` as `length` above:
+  #     a = [:foo, 'bar', 2]
+  #      a.slice!(1..2) # => ["bar", 2]
+  #     a # => [:foo]
+  #
+  # If `range.start == a.size`, returns a new empty Array.
+  #
+  # If `range.start` is larger than the array size, returns `nil`.
+  #
+  # If `range.end` is negative, counts backwards from the end of the array:
+  #     a = [:foo, 'bar', 2]
+  #     a.slice!(0..-2) # => [:foo, "bar"]
+  #     a # => [2]
+  #
+  # If `range.start` 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]
   #
   def slice!: (int index) -> Elem?
             | (int start, int length) -> ::Array[Elem]?
             | (::Range[::Integer] range) -> ::Array[Elem]?
 
-  # Returns a new array created by sorting `self`.
-  #
-  # Comparisons for the sort will be done using the `<=>` operator or using an
-  # optional code block.
-  #
-  # 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.
-  #
-  #     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):
-  #
-  #     ary.sort.reverse!             #=> ["e", "d", "c", "b", "a"]
-  #
-  # See also Enumerable#sort_by.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.sort -> new_array
+  #   - array.sort {|a, b| ... } -> new_array
+  # -->
+  # Returns a new Array whose elements are those from `self`, sorted.
+  #
+  # With no block, compares elements using operator `<=>` (see Comparable):
+  #     a = 'abcde'.split('').shuffle
+  #     a # => ["e", "b", "d", "a", "c"]
+  #     a1 = a.sort
+  #     a1 # => ["a", "b", "c", "d", "e"]
+  #
+  # 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 = a.sort {|a, b| 0 }
+  #     a1 # =>  ["c", "e", "b", "d", "a"]
+  #
+  # Related: Enumerable#sort_by.
   #
   def sort: () -> ::Array[Elem]
           | () { (Elem a, Elem b) -> ::Integer } -> ::Array[Elem]
 
-  # Sorts `self` in place.
-  #
-  # Comparisons for the sort will be done using the `<=>` operator or using an
-  # optional code block.
-  #
-  # 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.
-  #
-  #     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.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.sort! -> self
+  #   - array.sort! {|a, b| ... } -> self
+  # -->
+  # Returns `self` with its elements sorted in place.
+  #
+  # With no block, compares elements using operator `<=>` (see Comparable):
+  #     a = 'abcde'.split('').shuffle
+  #     a # => ["e", "b", "d", "a", "c"]
+  #     a.sort!
+  #     a # => ["a", "b", "c", "d", "e"]
+  #
+  # 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"]
   #
   def sort!: () -> self
            | () { (Elem a, Elem b) -> ::Integer } -> self
 
-  # Sorts `self` in place using a set of keys generated by mapping the values in
-  # `self` through the given block.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.sort_by! {|element| ... } -> self
+  #   - array.sort_by! -> new_enumerator
+  # -->
+  # Sorts the elements of `self` in place, using an ordering determined by the
+  # block; returns self.
+  #
+  # Calls the block with each successive element; sorts elements based on the
+  # values returned from the block.
   #
-  # The result is not guaranteed to be stable.  When two keys are equal, the order
-  # of the corresponding elements is unpredictable.
+  # For duplicates returned by the block, the ordering is indeterminate, and may
+  # be unstable.
   #
-  # If no block is given, an Enumerator is returned instead.
+  # This example sorts strings based on their sizes:
+  #     a = ['aaaa', 'bbb', 'cc', 'd']
+  #     a.sort_by! {|element| element.size }
+  #     a # => ["d", "cc", "bbb", "aaaa"]
   #
-  # See also Enumerable#sort_by.
+  # Returns a new Enumerator if no block given:
+  #
+  #     a = ['aaaa', 'bbb', 'cc', 'd']
+  #     a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
   #
   def sort_by!: [U] () { (Elem obj) -> U } -> ::Array[Elem]
               | () -> ::Enumerator[Elem, ::Array[Elem]]
 
-  # Returns the sum of elements. For example, [e1, e2, e3].sum returns init + e1 +
-  # e2 + e3.
-  #
-  # If a block is given, the block is applied to each element before addition.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.sum(init = 0) -> object
+  #   - array.sum(init = 0) {|element| ... } -> object
+  # -->
+  # When no block is given, returns the object equivalent to:
+  #     sum = init
+  #     array.each {|element| sum += element }
+  #     sum
   #
-  # If *ary* is empty, it returns *init*.
+  # For example, `[e1, e2, e3].sum` returns `init + e1 + e2 + e3`.
   #
-  #     [].sum                             #=> 0
-  #     [].sum(0.0)                        #=> 0.0
-  #     [1, 2, 3].sum                      #=> 6
-  #     [3, 5.5].sum                       #=> 8.5
-  #     [2.5, 3.0].sum(0.0) {|e| e * e }   #=> 15.25
-  #     [Object.new].sum                   #=> TypeError
-  #
-  # The (arithmetic) mean value of an array can be obtained as follows.
-  #
-  #     mean = ary.sum(0.0) / ary.length
-  #
-  # This method can be used for non-numeric objects by explicit *init* argument.
-  #
-  #     ["a", "b", "c"].sum("")            #=> "abc"
-  #     [[1], [[2]], [3]].sum([])          #=> [1, [2], 3]
-  #
-  # However, Array#join and Array#flatten is faster than Array#sum for array of
-  # strings and array of arrays.
-  #
-  #     ["a", "b", "c"].join               #=> "abc"
-  #     [[1], [[2]], [3]].flatten(1)       #=> [1, [2], 3]
-  #
-  # Array#sum method may not respect method redefinition of "+" methods such as
-  # Integer#+.
+  # Examples:
+  #     a = [0, 1, 2, 3]
+  #     a.sum # => 6
+  #     a.sum(100) # => 106
+  #
+  # The elements need not be numeric, but must be `+`-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#+.
   #
   def sum: (?untyped init) -> untyped
          | (?untyped init) { (Elem e) -> untyped } -> untyped
 
-  # Returns first `n` elements from the array.
-  #
-  # If a negative number is given, raises an ArgumentError.
-  #
-  # See also Array#drop
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.take(n) -> new_array
+  # -->
+  # Returns a new Array containing the first `n` element of `self`, where `n` is a
+  # non-negative Integer; does not modify `self`.
   #
-  #     a = [1, 2, 3, 4, 5, 0]
-  #     a.take(3)             #=> [1, 2, 3]
+  # 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]
   #
   def take: (int n) -> ::Array[Elem]
 
-  # Passes elements to the block until the block returns `nil` or `false`, then
-  # stops iterating and returns an array of all prior elements.
-  #
-  # If no block is given, an Enumerator is returned instead.
-  #
-  # See also Array#drop_while
-  #
-  #     a = [1, 2, 3, 4, 5, 0]
-  #     a.take_while {|i| i < 3}    #=> [1, 2]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.take_while {|element| ... } -> new_array
+  #   - array.take_while -> new_enumerator
+  # -->
+  # Returns a new Array containing zero or more leading elements of `self`; does
+  # not modify `self`.
+  #
+  # 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>
   #
   def take_while: () { (Elem obj) -> boolish } -> ::Array[Elem]
                 | () -> ::Enumerator[Elem, ::Array[Elem]]
 
-  # Returns `self`.
-  #
-  # If called on a subclass of Array, converts the receiver to an Array object.
+  # <!--
+  #   rdoc-file=array.c
+  #   - 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
+  #     a.kind_of?(Array) # => true
+  #     a1 = a.to_a
+  #     a1 # => ["foo", "bar", "two"]
+  #     a1.class # => Array # Not MyArray
   #
   def to_a: () -> ::Array[Elem]
 
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.to_ary -> self
+  # -->
   # Returns `self`.
   #
   def to_ary: () -> self
 
-  # Returns the result of interpreting *ary* as an array of `[key, value]` pairs.
-  #
-  #     [[:foo, :bar], [1, 2]].to_h
-  #       # => {:foo => :bar, 1 => 2}
-  #
-  # If a block is given, the results of the block on each element of the array
-  # will be used as pairs.
-  #
-  #     ["foo", "bar"].to_h {|s| [s.ord, s]}
-  #       # => {102=>"foo", 98=>"bar"}
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.to_h -> new_hash
+  #   - array.to_h {|item| ... } -> new_hash
+  # -->
+  # Returns a new Hash formed from `self`.
+  #
+  # 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"}
   #
   def to_h: () -> Hash[untyped, untyped]
-          | [T, S] () { (Elem) -> [T, S] } -> Hash[T, S]
+          | [T, S] () { (Elem) -> [ T, S ] } -> Hash[T, S]
 
-  alias to_s inspect
-
-  # Assumes that `self` is an array of arrays and transposes the rows and columns.
+  # <!-- rdoc-file=array.c -->
+  # Returns the new String formed by calling method `#inspect` on each array
+  # element:
+  #     a = [:foo, 'bar', 2]
+  #     a.inspect # => "[:foo, \"bar\", 2]"
   #
-  #     a = [[1,2], [3,4], [5,6]]
-  #     a.transpose   #=> [[1, 3, 5], [2, 4, 6]]
+  # Array#to_s is an alias for Array#inspect.
   #
-  # If the length of the subarrays don't match, an IndexError is raised.
+  alias to_s inspect
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.transpose -> new_array
+  # -->
+  # 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]]
   #
   def transpose: () -> ::Array[::Array[untyped]]
 
-  # Set Union --- Returns a new array by joining `other_ary`s with `self`,
-  # excluding any duplicates and preserving the order from the given arrays.
-  #
-  # It compares elements using their #hash and #eql? methods for efficiency.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.union(*other_arrays) -> new_array
+  # -->
+  # 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 `eql?`:
+  #     [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]
   #
-  #     [ "a", "b", "c" ].union( [ "c", "d", "a" ] )    #=> [ "a", "b", "c", "d" ]
-  #     [ "a" ].union( ["e", "b"], ["a", "c", "b"] )    #=> [ "a", "e", "b", "c" ]
-  #     [ "a" ].union #=> [ "a" ]
+  # Returns a copy of `self` if no arguments given.
   #
-  # See also Array#|.
+  # Related: Array#|.
   #
   def union: [T] (*::Array[T] other_arys) -> ::Array[T | Elem]
 
-  # Returns a new array by removing duplicate values in `self`.
-  #
-  # If a block is given, it will use the return value of the block for comparison.
-  #
-  # It compares values using their #hash and #eql? methods for efficiency.
-  #
-  # `self` is traversed in order, and the first occurrence is kept.
-  #
-  #     a = [ "a", "a", "b", "b", "c" ]
-  #     a.uniq   # => ["a", "b", "c"]
-  #
-  #     b = [["student","sam"], ["student","george"], ["teacher","matz"]]
-  #     b.uniq {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.uniq -> new_array
+  #   - array.uniq {|element| ... } -> new_array
+  # -->
+  # Returns a new Array containing those elements from `self` that are not
+  # duplicates, the first occurrence always being retained.
+  #
+  # With no block given, identifies and omits duplicates using method `eql?` 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
+  # `eql?`) 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"]
   #
   def uniq: () -> ::Array[Elem]
           | () { (Elem item) -> untyped } -> ::Array[Elem]
 
-  # Removes duplicate elements from `self`.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.uniq! -> self or nil
+  #   - array.uniq! {|element| ... } -> self or nil
+  # -->
+  # Removes duplicate elements from `self`, the first occurrence always being
+  # retained; returns `self` if any elements removed, `nil` otherwise.
   #
-  # If a block is given, it will use the return value of the block for comparison.
+  # With no block given, identifies and removes elements using method `eql?` to
+  # compare.
   #
-  # It compares values using their #hash and #eql? methods for efficiency.
+  # Returns `self` if any elements removed:
+  #     a = [0, 0, 1, 1, 2, 2]
+  #     a.uniq! # => [0, 1, 2]
   #
-  # `self` is traversed in order, and the first occurrence is kept.
+  # Returns `nil` if no elements removed.
   #
-  # Returns `nil` if no changes are made (that is, no duplicates are found).
+  # With a block given, calls the block for each element; identifies (using method
+  # `eql?`) and removes elements for which the block returns duplicate values.
   #
-  #     a = [ "a", "a", "b", "b", "c" ]
-  #     a.uniq!   # => ["a", "b", "c"]
+  # Returns `self` if any elements removed:
+  #     a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
+  #     a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
   #
-  #     b = [ "a", "b", "c" ]
-  #     b.uniq!   # => nil
-  #
-  #     c = [["student","sam"], ["student","george"], ["teacher","matz"]]
-  #     c.uniq! {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]
+  # Returns `nil` if no elements removed.
   #
   def uniq!: () -> self?
            | () { (Elem) -> untyped } -> self?
 
-  # Prepends objects to the front of `self`, moving other elements upwards. See
-  # also Array#shift for the opposite effect.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.unshift(*objects) -> self
+  # -->
+  # Prepends the given `objects` to `self`:
+  #     a = [:foo, 'bar', 2]
+  #     a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
+  #
+  # Array#prepend is an alias for Array#unshift.
   #
-  #     a = [ "b", "c", "d" ]
-  #     a.unshift("a")   #=> ["a", "b", "c", "d"]
-  #     a.unshift(1, 2)  #=> [ 1, 2, "a", "b", "c", "d"]
+  # Related: #push, #pop, #shift.
   #
   def unshift: (*Elem obj) -> self
 
-  # Returns an array containing the elements in `self` corresponding to the given
-  # `selector`(s).
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.values_at(*indexes) -> new_array
+  # -->
+  # Returns a new Array whose elements are the elements of `self` at the given
+  # Integer or Range `indexes`.
   #
-  # The selectors may be either integer indices or ranges.
+  # 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"]
   #
-  # See also Array#select.
+  # 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]
   #
-  #     a = %w{ a b c d e f }
-  #     a.values_at(1, 3, 5)          # => ["b", "d", "f"]
-  #     a.values_at(1, 3, 5, 7)       # => ["b", "d", "f", nil]
-  #     a.values_at(-1, -2, -2, -7)   # => ["f", "e", "e", nil]
-  #     a.values_at(4..6, 3...6)      # => ["e", "f", nil, "d", "e", "f"]
+  # Assigns `nil` for an `index` that is too large:
+  #     a = [:foo, 'bar', 2]
+  #     a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
   #
-  def values_at: (*int | ::Range[::Integer] selector) -> ::Array[Elem?]
-
-  # Converts any arguments to arrays, then merges elements of `self` with
-  # corresponding elements from each argument.
+  # Returns a new empty Array if no arguments given.
   #
-  # This generates a sequence of `ary.size` *n*-element arrays, where *n* is one
-  # more than the count of arguments.
+  # For each negative `index`, counts backward from the end of the array:
+  #     a = [:foo, 'bar', 2]
+  #     a.values_at(-1, -3) # => [2, :foo]
   #
-  # If the size of any argument is less than the size of the initial array, `nil`
-  # values are supplied.
+  # 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]
   #
-  # If a block is given, it is invoked for each output `array`, otherwise an array
-  # of arrays is returned.
+  # The given `indexes` may have a mixture of signs:
+  #     a = [:foo, 'bar', 2]
+  #     a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
   #
-  #     a = [ 4, 5, 6 ]
-  #     b = [ 7, 8, 9 ]
-  #     [1, 2, 3].zip(a, b)   #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
-  #     [1, 2].zip(a, b)      #=> [[1, 4, 7], [2, 5, 8]]
-  #     a.zip([1, 2], [8])    #=> [[4, 1, 8], [5, 2, nil], [6, nil, nil]]
+  def values_at: (*int | ::Range[::Integer] selector) -> ::Array[Elem?]
+
+  # <!--
+  #   rdoc-file=array.c
+  #   - array.zip(*other_arrays) -> new_array
+  #   - array.zip(*other_arrays) {|other_array| ... } -> nil
+  # -->
+  # When no block given, returns a new Array `new_array` of size `self.size` whose
+  # elements are Arrays.
+  #
+  # Each nested array `new_array[n]` is of size `other_arrays.size+1`, 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]
+  #     d = a.zip(b, c)
+  #     d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
+  #
+  # If any array in `other_arrays` is smaller than `self`, fills to `self.size`
+  # with `nil`:
+  #     a = [:a0, :a1, :a2, :a3]
+  #     b = [:b0, :b1, :b2]
+  #     c = [:c0, :c1]
+  #     d = a.zip(b, c)
+  #     d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
+  #
+  # 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
+  #     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]
   #
   def zip: [U] (::Array[U] arg) -> ::Array[[ Elem, U? ]]
          | (::Array[untyped] arg, *::Array[untyped] args) -> ::Array[::Array[untyped]]
-         | [U] (::Array[U] arg) { ([Elem, U?]) -> void } -> void
+         | [U] (::Array[U] arg) { ([ Elem, U? ]) -> void } -> void
          | (::Array[untyped] arg, *::Array[untyped] args) { (::Array[untyped]) -> void } -> void
 
-  # Set Union --- Returns a new array by joining `ary` with `other_ary`, excluding
-  # any duplicates and preserving the order from the given arrays.
-  #
-  # It compares elements using their #hash and #eql? methods for efficiency.
+  # <!--
+  #   rdoc-file=array.c
+  #   - array | other_array -> new_array
+  # -->
+  # Returns the union of `array` and Array `other_array`; duplicates are removed;
+  # order is preserved; items are compared using `eql?`:
+  #     [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]
   #
-  #     [ "a", "b", "c" ] | [ "c", "d", "a" ]    #=> [ "a", "b", "c", "d" ]
-  #     [ "c", "d", "a" ] | [ "a", "b", "c" ]    #=> [ "c", "d", "a", "b" ]
-  #
-  # See also Array#union.
+  # Related: Array#union.
   #
   def |: [T] (::Array[T] other_ary) -> ::Array[Elem | T]
 
   private
 
-  # Replaces the contents of `self` with the contents of `other_ary`, truncating
-  # or expanding if necessary.
-  #
-  #     a = [ "a", "b", "c", "d", "e" ]
-  #     a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
-  #     a                              #=> ["x", "y", "z"]
+  # <!--
+  #   rdoc-file=array.c
+  #   - 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]
   #
   def initialize_copy: (self other_ary) -> void
 end