rbs 3.10.0 → 4.0.0.dev.1

data/core/array.rbs

@@ -151,8 +151,8 @@
 #
 # ## Example Usage
 #
-# In addition to the methods it mixes in through the Enumerable module, class
-# Array has proprietary methods for accessing, searching and otherwise
+# In addition to the methods it mixes in through the Enumerable module, the
+# `Array` class has proprietary methods for accessing, searching and otherwise
 # manipulating arrays.
 #
 # Some of the more common ones are illustrated below.
@@ -200,9 +200,9 @@
 #
 #     arr.drop(3) #=> [4, 5, 6]
 #
-# ## Obtaining Information about an Array
+# ## Obtaining Information about an `Array`
 #
-# An array keeps track of its own length at all times.  To query an array about
+# Arrays keep track of their own length at all times.  To query an array about
 # the number of elements it contains, use #length, #count or #size.
 #
 #     browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
@@ -217,7 +217,7 @@
 #
 #     browsers.include?('Konqueror') #=> false
 #
-# ## Adding Items to an Array
+# ## Adding Items to Arrays
 #
 # Items can be added to the end of an array by using either #push or #<<
 #
@@ -238,7 +238,7 @@
 #     arr.insert(3, 'orange', 'pear', 'grapefruit')
 #     #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
 #
-# ## Removing Items from an Array
+# ## Removing Items from an `Array`
 #
 # The method #pop removes the last element in an array and returns it:
 #
@@ -277,12 +277,12 @@
 #     arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
 #     arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
 #
-# ## Iterating over an Array
+# ## Iterating over Arrays
 #
-# Like all classes that include the Enumerable module, class Array has an each
+# Like all classes that include the Enumerable module, `Array` has an each
 # method, which defines what elements should be iterated over and how.  In case
-# of Array#each, all elements in `self` are yielded to the supplied block in
-# sequence.
+# of Array's #each, all elements in the `Array` instance are yielded to the
+# supplied block in sequence.
 #
 # Note that this operation leaves the array unchanged.
 #
@@ -307,7 +307,7 @@
 #     arr.map! {|a| a**2}   #=> [1, 4, 9, 16, 25]
 #     arr                   #=> [1, 4, 9, 16, 25]
 #
-# ## Selecting Items from an Array
+# ## Selecting Items from an `Array`
 #
 # Elements can be selected from an array according to criteria defined in a
 # block.  The selection can happen in a destructive or a non-destructive manner.
@@ -340,13 +340,13 @@
 #
 # ## What's Here
 #
-# First, what's elsewhere. Class Array:
+# First, what's elsewhere. Class `Array`:
 #
 # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
 # *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
 #     provides dozens of additional methods.
 #
-# Here, class Array provides methods that are useful for:
+# Here, class `Array` provides methods that are useful for:
 #
 # *   [Creating an Array](rdoc-ref:Array@Methods+for+Creating+an+Array)
 # *   [Querying](rdoc-ref:Array@Methods+for+Querying)
@@ -359,7 +359,7 @@
 # *   [Converting](rdoc-ref:Array@Methods+for+Converting)
 # *   [And more....](rdoc-ref:Array@Other+Methods)
 #
-# ### Methods for Creating an Array
+# ### Methods for Creating an `Array`
 #
 # *   ::[]: Returns a new array populated with given objects.
 # *   ::new: Returns a new array.
@@ -524,7 +524,7 @@
 #     return-value.
 # *   #flatten: Returns an array that is a recursive flattening of `self`.
 # *   #inspect (aliased as #to_s): Returns a new String containing the elements.
-# *   #join: Returns a new String containing the elements joined by the field
+# *   #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`.
@@ -840,8 +840,9 @@ class Array[unchecked out Elem] < Object
   #
   # 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`:
+  # 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"]
@@ -855,7 +856,7 @@ class Array[unchecked out Elem] < Object
   #     a[1, 3] # => ["bar", 2]
   #     a[2, 2] # => [2]
   #
-  # If `start == self.size` and `length >= 0`, returns a new empty array.
+  # If `start == self.size` and `length >= 0`, returns a new empty `Array`.
   #
   # If `length` is negative, returns `nil`.
   #
@@ -866,7 +867,7 @@ class Array[unchecked out Elem] < Object
   #     a[0..1] # => [:foo, "bar"]
   #     a[1..2] # => ["bar", 2]
   #
-  # Special case: If `range.start == a.size`, returns a new empty array.
+  # Special case: If `range.start == a.size`, returns a new empty `Array`.
   #
   # If `range.end` is negative, calculates the end index from the end:
   #
@@ -890,7 +891,7 @@ class Array[unchecked out Elem] < Object
   #     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.
+  # an `Array` of elements corresponding to the indexes produced by the sequence.
   #
   #     a = ['--', 'data1', '--', 'data2', '--', 'data3']
   #     a[(1..).step(2)] # => ["data1", "data2", "data3"]
@@ -975,8 +976,8 @@ class Array[unchecked out Elem] < Object
   #     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`:
+  # `Array`, removes `length - 1` elements beginning at offset `start`, and
+  # assigns `object` at offset `start`:
   #
   #     a = [:foo, 'bar', 2]
   #     a[0, 2] = 'foo' # => "foo"
@@ -1009,7 +1010,7 @@ class Array[unchecked out Elem] < Object
   #     a[1, 5] = 'foo' # => "foo"
   #     a # => [:foo, "foo"]
   #
-  # When Range argument `range` is given and `object` is not an array, removes
+  # When Range argument `range` is given and `object` is not an `Array`, removes
   # `length - 1` elements beginning at offset `start`, and assigns `object` at
   # offset `start`:
   #
@@ -1213,7 +1214,7 @@ class Array[unchecked out Elem] < Object
   # Returns the element from `self` found by a binary search, or `nil` if the
   # search found no suitable element.
   #
-  # See [Binary Searching](rdoc-ref:language/bsearch.rdoc).
+  # See [Binary Searching](rdoc-ref:bsearch.rdoc).
   #
   # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching).
   #
@@ -1229,7 +1230,7 @@ class Array[unchecked out Elem] < Object
   # Returns the integer index of the element from `self` found by a binary search,
   # or `nil` if the search found no suitable element.
   #
-  # See [Binary Searching](rdoc-ref:language/bsearch.rdoc).
+  # See [Binary Searching](rdoc-ref:bsearch.rdoc).
   #
   # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching).
   #
@@ -1273,9 +1274,9 @@ class Array[unchecked out Elem] < Object
 
   # <!--
   #   rdoc-file=array.c
-  #   - collect! {|element| ... } -> self
+  #   - collect! {|element| ... } -> new_array
   #   - collect! -> new_enumerator
-  #   - map! {|element| ... } -> self
+  #   - map! {|element| ... } -> new_array
   #   - map! -> new_enumerator
   # -->
   # With a block given, calls the block with each element of `self` and replaces
@@ -1563,7 +1564,7 @@ class Array[unchecked out Elem] < Object
 
   # <!--
   #   rdoc-file=array.c
-  #   - dig(index, *identifiers) -> object
+  #   - array.dig(index, *identifiers) -> object
   # -->
   # Finds and returns the object in nested object specified by `index` and
   # `identifiers`; the nested objects may be instances of various classes. See
@@ -1692,7 +1693,7 @@ class Array[unchecked out Elem] < Object
 
   # <!--
   #   rdoc-file=array.c
-  #   - empty?  -> true or false
+  #   - array.empty?  -> true or false
   # -->
   # Returns `true` if the count of elements in `self` is zero, `false` otherwise.
   #
@@ -1803,10 +1804,10 @@ class Array[unchecked out Elem] < Object
 
   # <!--
   #   rdoc-file=array.c
-  #   - fill(object, start = nil, count = nil) -> self
-  #   - fill(object, range) -> self
-  #   - fill(start = nil, count = nil) {|element| ... } -> self
-  #   - fill(range) {|element| ... } -> self
+  #   - fill(object, start = nil, count = nil) -> new_array
+  #   - fill(object, range) -> new_array
+  #   - fill(start = nil, count = nil) {|element| ... } -> new_array
+  #   - fill(range) {|element| ... } -> new_array
   # -->
   # Replaces selected elements in `self`; may add elements to `self`; always
   # returns `self` (never a new array).
@@ -2019,32 +2020,6 @@ class Array[unchecked out Elem] < Object
   def filter!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
-  # <!--
-  #   rdoc-file=array.c
-  #   - find(if_none_proc = nil) {|element| ... } -> object or nil
-  #   - find(if_none_proc = nil) -> enumerator
-  # -->
-  # Returns the first element for which the block returns a truthy value.
-  #
-  # With a block given, calls the block with successive elements of the array;
-  # returns the first element for which the block returns a truthy value:
-  #
-  #     (0..9).find {|element| element > 2}                # => 3
-  #
-  # If no such element is found, calls `if_none_proc` and returns its return
-  # value.
-  #
-  #     (0..9).find(proc {false}) {|element| element > 12} # => false
-  #     {foo: 0, bar: 1, baz: 2}.find {|key, value| key.start_with?('b') }            # => [:bar, 1]
-  #     {foo: 0, bar: 1, baz: 2}.find(proc {[]}) {|key, value| key.start_with?('c') } # => []
-  #
-  # With no block given, returns an Enumerator.
-  #
-  def find: () { (Elem) -> boolish } -> Elem?
-          | () -> ::Enumerator[Elem, Elem?]
-          | [T] (Enumerable::_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
-          | [T] (Enumerable::_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
-
   # <!--
   #   rdoc-file=array.c
   #   - find_index(object) -> integer or nil
@@ -2325,7 +2300,7 @@ class Array[unchecked out Elem] < Object
 
   # <!--
   #   rdoc-file=array.c
-  #   - join(separator = $,) -> new_string
+  #   - array.join(separator = $,) -> new_string
   # -->
   # Returns the new string formed by joining the converted elements of `self`; for
   # each element `element`:
@@ -2644,7 +2619,7 @@ class Array[unchecked out Elem] < Object
   #   - pack(template, buffer: nil) -> string
   # -->
   # Formats each element in `self` into a binary string; returns that string. See
-  # [Packed Data](rdoc-ref:language/packed_data.rdoc).
+  # [Packed Data](rdoc-ref:packed_data.rdoc).
   #
   def pack: (string fmt, ?buffer: String?) -> String
 
@@ -3014,33 +2989,6 @@ class Array[unchecked out Elem] < Object
   def reverse_each: () { (Elem item) -> void } -> self
                   | () -> ::Enumerator[Elem, self]
 
-  # <!--
-  #   rdoc-file=array.c
-  #   - rfind(if_none_proc = nil) {|element| ... } -> object or nil
-  #   - rfind(if_none_proc = nil) -> enumerator
-  # -->
-  # Returns the last element for which the block returns a truthy value.
-  #
-  # With a block given, calls the block with successive elements of the array in
-  # reverse order; returns the last element for which the block returns a truthy
-  # value:
-  #
-  #     (0..9).rfind {|element| element < 5}                # => 4
-  #
-  # If no such element is found, calls `if_none_proc` and returns its return
-  # value.
-  #
-  #     (0..9).rfind(proc {false}) {|element| element < -2} # => false
-  #     {foo: 0, bar: 1, baz: 2}.rfind {|key, value| key.start_with?('b') }            # => [:baz, 2]
-  #     {foo: 0, bar: 1, baz: 2}.rfind(proc {[]}) {|key, value| key.start_with?('c') } # => []
-  #
-  # With no block given, returns an Enumerator.
-  #
-  def rfind: () { (Elem) -> boolish } -> Elem?
-           | () -> ::Enumerator[Elem, Elem?]
-           | [T] (Enumerable::_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
-           | [T] (Enumerable::_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
-
   # <!--
   #   rdoc-file=array.c
   #   - rindex(object) -> integer or nil
@@ -3167,7 +3115,7 @@ class Array[unchecked out Elem] < Object
   #
   # The order of the result array is unrelated to the order of `self`.
   #
-  # Returns a new empty array if `self` is empty:
+  # Returns a new empty `Array` if `self` is empty:
   #
   #     [].sample(4) # => []
   #
@@ -3372,8 +3320,9 @@ class Array[unchecked out Elem] < Object
   #
   # 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`:
+  # 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"]
@@ -3387,7 +3336,7 @@ class Array[unchecked out Elem] < Object
   #     a[1, 3] # => ["bar", 2]
   #     a[2, 2] # => [2]
   #
-  # If `start == self.size` and `length >= 0`, returns a new empty array.
+  # If `start == self.size` and `length >= 0`, returns a new empty `Array`.
   #
   # If `length` is negative, returns `nil`.
   #
@@ -3398,7 +3347,7 @@ class Array[unchecked out Elem] < Object
   #     a[0..1] # => [:foo, "bar"]
   #     a[1..2] # => ["bar", 2]
   #
-  # Special case: If `range.start == a.size`, returns a new empty array.
+  # Special case: If `range.start == a.size`, returns a new empty `Array`.
   #
   # If `range.end` is negative, calculates the end index from the end:
   #
@@ -3422,7 +3371,7 @@ class Array[unchecked out Elem] < Object
   #     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.
+  # an `Array` of elements corresponding to the indexes produced by the sequence.
   #
   #     a = ['--', 'data1', '--', 'data2', '--', 'data3']
   #     a[(1..).step(2)] # => ["data1", "data2", "data3"]
@@ -3569,9 +3518,6 @@ class Array[unchecked out Elem] < Object
   # When the block returns zero, the order for `a` and `b` is indeterminate, and
   # may be unstable.
   #
-  # See an example in Numeric#nonzero? for the idiom to sort more complex
-  # structure.
-  #
   # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching).
   #
   def sort: () -> ::Array[Elem]
@@ -3701,7 +3647,7 @@ class Array[unchecked out Elem] < Object
   #   rdoc-file=array.c
   #   - to_a -> self or new_array
   # -->
-  # When `self` is an instance of Array, returns `self`.
+  # When `self` is an instance of `Array`, returns `self`.
   #
   # Otherwise, returns a new array containing the elements of `self`:
   #
@@ -3717,7 +3663,7 @@ class Array[unchecked out Elem] < Object
 
   # <!--
   #   rdoc-file=array.c
-  #   - to_ary -> self
+  #   - array.to_ary -> self
   # -->
   # Returns `self`.
   #
@@ -4062,7 +4008,7 @@ class Array[unchecked out Elem] < Object
   #      [:c3, :b3, :a3]]
   #
   # For an **object** in **other_arrays** that is not actually an array, forms the
-  # "other array" as `object.to_ary`, if defined, or as `object.each.to_a`
+  # the "other array" as `object.to_ary`, if defined, or as `object.each.to_a`
   # otherwise.
   #
   # Related: see [Methods for Converting](rdoc-ref:Array@Methods+for+Converting).

data/core/complex.rbs

@@ -184,24 +184,23 @@ class Complex < Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - self * other -> numeric
+  #   - complex * numeric -> new_complex
   # -->
-  # Returns the numeric product of `self` and `other`:
+  # Returns the product of `self` and `numeric`:
   #
-  #     Complex.rect(9, 8)  * 4                   # => (36+32i)
-  #     Complex.rect(20, 9) * 9.8                 # => (196.0+88.2i)
   #     Complex.rect(2, 3)  * Complex.rect(2, 3)  # => (-5+12i)
   #     Complex.rect(900)   * Complex.rect(1)     # => (900+0i)
   #     Complex.rect(-2, 9) * Complex.rect(-9, 2) # => (0-85i)
-  #     Complex.rect(9, 8)  * Rational(2, 3)      # => ((6/1)+(16/3)*i)
+  #     Complex.rect(9, 8)  * 4                   # => (36+32i)
+  #     Complex.rect(20, 9) * 9.8                 # => (196.0+88.2i)
   #
   def *: (Numeric) -> Complex
 
   # <!--
   #   rdoc-file=complex.c
-  #   - self ** exponent -> complex
+  #   - complex ** numeric -> new_complex
   # -->
-  # Returns `self` raised to the power `exponent`:
+  # Returns `self` raised to power `numeric`:
   #
   #     Complex.rect(0, 1) ** 2            # => (-1+0i)
   #     Complex.rect(-8) ** Rational(1, 3) # => (1.0000000000000002+1.7320508075688772i)
@@ -210,25 +209,15 @@ class Complex < Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - self + other -> numeric
+  #   - complex + numeric -> new_complex
   # -->
-  # Returns the sum of `self` and `other`:
-  #
-  #     Complex(1, 2) + 0  # => (1+2i)
-  #     Complex(1, 2) + 1  # => (2+2i)
-  #     Complex(1, 2) + -1 # => (0+2i)
-  #
-  #     Complex(1, 2) + 1.0  # => (2.0+2i)
-  #
-  #     Complex(1, 2) + Complex(2, 1)     # => (3+3i)
-  #     Complex(1, 2) + Complex(2.0, 1.0) # => (3.0+3.0i)
-  #
-  #     Complex(1, 2) + Rational(1, 1) # => ((2/1)+2i)
-  #     Complex(1, 2) + Rational(1, 2) # => ((3/2)+2i)
-  #
-  # For a computation involving Floats, the result may be inexact (see Float#+):
+  # Returns the sum of `self` and `numeric`:
   #
-  #     Complex(1, 2) + 3.14 # => (4.140000000000001+2i)
+  #     Complex.rect(2, 3)  + Complex.rect(2, 3)  # => (4+6i)
+  #     Complex.rect(900)   + Complex.rect(1)     # => (901+0i)
+  #     Complex.rect(-2, 9) + Complex.rect(-9, 2) # => (-11+11i)
+  #     Complex.rect(9, 8)  + 4                   # => (13+8i)
+  #     Complex.rect(20, 9) + 9.8                 # => (29.8+9i)
   #
   def +: (Numeric) -> Complex
 
@@ -236,9 +225,9 @@ class Complex < Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - self - other -> complex
+  #   - complex - numeric -> new_complex
   # -->
-  # Returns the difference of `self` and `other`:
+  # Returns the difference of `self` and `numeric`:
   #
   #     Complex.rect(2, 3)  - Complex.rect(2, 3)  # => (0+0i)
   #     Complex.rect(900)   - Complex.rect(1)     # => (899+0i)
@@ -250,9 +239,9 @@ class Complex < Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - -self -> complex
+  #   - -complex -> new_complex
   # -->
-  # Returns `self`, negated, which is the negation of each of its parts:
+  # Returns the negation of `self`, which is the negation of each of its parts:
   #
   #     -Complex.rect(1, 2)   # => (-1-2i)
   #     -Complex.rect(-1, -2) # => (1+2i)
@@ -261,9 +250,9 @@ class Complex < Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - self / other -> complex
+  #   - complex / numeric -> new_complex
   # -->
-  # Returns the quotient of `self` and `other`:
+  # Returns the quotient of `self` and `numeric`:
   #
   #     Complex.rect(2, 3)  / Complex.rect(2, 3)  # => (1+0i)
   #     Complex.rect(900)   / Complex.rect(1)     # => (900+0i)
@@ -605,9 +594,9 @@ class Complex < Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - self / other -> complex
+  #   - complex / numeric -> new_complex
   # -->
-  # Returns the quotient of `self` and `other`:
+  # Returns the quotient of `self` and `numeric`:
   #
   #     Complex.rect(2, 3)  / Complex.rect(2, 3)  # => (1+0i)
   #     Complex.rect(900)   / Complex.rect(1)     # => (900+0i)

data/core/dir.rbs

@@ -477,8 +477,8 @@ class Dir
 
   # <!--
   #   rdoc-file=dir.rb
-  #   - Dir.glob(patterns, flags: 0, base: nil, sort: true) -> array
-  #   - Dir.glob(patterns, flags: 0, base: nil, sort: true) {|entry_name| ... } -> nil
+  #   - Dir.glob(*patterns, flags: 0, base: nil, sort: true) -> array
+  #   - Dir.glob(*patterns, flags: 0, base: nil, sort: true) {|entry_name| ... } -> nil
   # -->
   # Forms an array *entry_names* of the entry names selected by the arguments.
   #

data/core/encoding.rbs

@@ -281,7 +281,7 @@ class Encoding
   def inspect: () -> String
 
   # <!-- rdoc-file=encoding.c -->
-  # The name of the encoding.
+  # Returns the name of the encoding.
   #
   #     Encoding::UTF_8.name      #=> "UTF-8"
   #
@@ -297,8 +297,12 @@ class Encoding
   #
   def names: () -> Array[String]
 
-  # <!-- rdoc-file=encoding.c -->
-  # The name of the encoding.
+  # <!--
+  #   rdoc-file=encoding.c
+  #   - enc.name -> string
+  #   - enc.to_s -> string
+  # -->
+  # Returns the name of the encoding.
   #
   #     Encoding::UTF_8.name      #=> "UTF-8"
   #
@@ -919,9 +923,8 @@ class Encoding::Converter < Object
   #     p ec.primitive_convert(src, dst, nil, 1)             #=> :destination_buffer_full
   #     p ec.last_error      #=> nil
   #
-  def last_error: () -> ( Encoding::InvalidByteSequenceError
-                        | Encoding::UndefinedConversionError
-                        | nil )
+  def last_error: () -> Encoding::InvalidByteSequenceError?
+                | () -> Encoding::UndefinedConversionError?
 
   # <!--
   #   rdoc-file=transcode.c

data/core/enumerable.rbs

@@ -114,8 +114,8 @@
 #     by the block.
 # *   #grep: Returns elements selected by a given object or objects returned by
 #     a given block.
-# *   #grep_v: Returns elements not selected by a given object or objects
-#     returned by a given block.
+# *   #grep_v: Returns elements selected by a given object or objects returned
+#     by a given block.
 # *   #inject (aliased as #reduce): Returns the object formed by combining all
 #     elements.
 # *   #sum: Returns the sum of the elements, using method `+`.
@@ -191,82 +191,6 @@
 #     usage would not make sense, and so it is not shown.  Example: #tally would
 #     find exactly one of each Hash entry.
 #
-# ## Extended Methods
-#
-# A Enumerable class may define extended methods. This section describes the
-# standard behavior of extension methods for reference purposes.
-#
-# ### #size
-#
-# Enumerator has a #size method. It uses the size function argument passed to
-# `Enumerator.new`.
-#
-#     e = Enumerator.new(-> { 3 }) {|y| p y; y.yield :a; y.yield :b; y.yield :c; :z }
-#     p e.size #=> 3
-#     p e.next #=> :a
-#     p e.next #=> :b
-#     p e.next #=> :c
-#     begin
-#       e.next
-#     rescue StopIteration
-#       p $!.result #=> :z
-#     end
-#
-# The result of the size function should represent the number of iterations
-# (i.e., the number of times Enumerator::Yielder#yield is called). In the above
-# example, the block calls #yield three times, and the size function, +-> { 3
-# }+, returns 3 accordingly. The result of the size function can be an integer,
-# `Float::INFINITY`, or `nil`. An integer means the exact number of times #yield
-# will be called, as shown above. `Float::INFINITY` indicates an infinite number
-# of #yield calls. `nil` means the number of #yield calls is difficult or
-# impossible to determine.
-#
-# Many iteration methods return an Enumerator object with an appropriate size
-# function if no block is given.
-#
-# Examples:
-#
-#     ["a", "b", "c"].each.size #=> 3
-#     {a: "x", b: "y", c: "z"}.each.size #=> 3
-#     (0..20).to_a.permutation.size #=> 51090942171709440000
-#     loop.size #=> Float::INFINITY
-#     (1..100).drop_while.size #=> nil  # size depends on the block's behavior
-#     STDIN.each.size #=> nil # cannot be computed without consuming input
-#     File.open("/etc/resolv.conf").each.size #=> nil # cannot be computed without reading the file
-#
-# The behavior of #size for Range-based enumerators depends on the #begin
-# element:
-#
-# *   If the #begin element is an Integer, the #size method returns an Integer
-#     or `Float::INFINITY`.
-# *   If the #begin element is an object with a #succ method (other than
-#     Integer), #size returns `nil`. (Computing the size would require
-#     repeatedly calling #succ, which may be too slow.)
-# *   If the #begin element does not have a #succ method, #size raises a
-#     TypeError.
-#
-# Examples:
-#
-#     (10..42).each.size #=> 33
-#     (10..42.9).each.size #=> 33 (the #end element may be a non-integer numeric)
-#     (10..).each.size #=> Float::INFINITY
-#     ("a".."z").each.size #=> nil
-#     ("a"..).each.size #=> nil
-#     (1.0..9.0).each.size # raises TypeError (Float does not have #succ)
-#     (..10).each.size # raises TypeError (beginless range has nil as its #begin)
-#
-# The Enumerable module itself does not define a #size method. A class that
-# includes Enumerable may define its own #size method. It is recommended that
-# such a #size method be consistent with Enumerator#size.
-#
-# Array and Hash implement #size and return values consistent with
-# Enumerator#size. IO and Dir do not define #size, which is also consistent
-# because the corresponding enumerator's size function returns `nil`.
-#
-# However, it is not strictly required for a class's #size method to match
-# Enumerator#size. For example, File#size returns the number of bytes in the
-# file, not the number of lines.
-#
 module Enumerable[unchecked out Elem] : _Each[Elem]
   # <!--
   #   rdoc-file=enum.c
@@ -514,17 +438,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #
   # With no block given, returns an Enumerator.
   #
-  #     e = (1..4).drop_while
-  #     p e #=> #<Enumerator: 1..4:drop_while>
-  #     i = e.next; p i; e.feed(i < 3) #=> 1
-  #     i = e.next; p i; e.feed(i < 3) #=> 2
-  #     i = e.next; p i; e.feed(i < 3) #=> 3
-  #     begin
-  #       e.next
-  #     rescue StopIteration
-  #       p $!.result #=> [3, 4]
-  #     end
-  #
   def drop_while: () { (Elem) -> boolish } -> ::Array[Elem]
                 | () -> ::Enumerator[Elem, ::Array[Elem]]
 
@@ -2127,7 +2040,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #     ["F", 6860]
   #
   # You can use the special symbol `:_alone` to force an element into its own
-  # separate chunk:
+  # separate chuck:
   #
   #     a = [0, 0, 1, 1]
   #     e = a.chunk{|i| i.even? ? :_alone : true }