rbs 3.6.1 → 3.9.5

data/core/numeric.rbs

@@ -77,7 +77,6 @@
 # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
 # *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
-#
 # Here, class Numeric provides methods for:
 #
 # *   [Querying](rdoc-ref:Numeric@Querying)
@@ -85,7 +84,6 @@
 # *   [Converting](rdoc-ref:Numeric@Converting)
 # *   [Other](rdoc-ref:Numeric@Other)
 #
-#
 # ### Querying
 #
 # *   #finite?: Returns true unless `self` is infinite or not a number.
@@ -98,7 +96,6 @@
 # *   #real?: Returns whether `self` is a real value.
 # *   #zero?: Returns whether `self` is zero.
 #
-#
 # ### Comparing
 #
 # *   #<=>: Returns:
@@ -108,11 +105,9 @@
 #     *   1 if `self` is greater than the given value.
 #     *   `nil` if `self` and the given value are not comparable.
 #
-#
 # *   #eql?: Returns whether `self` and the given value have the same value and
 #     type.
 #
-#
 # ### Converting
 #
 # *   #% (aliased as #modulo): Returns the remainder of `self` divided by the
@@ -152,7 +147,6 @@
 #     necessary.
 # *   #truncate: Returns `self` truncated (toward zero) to a given precision.
 #
-#
 # ### Other
 #
 # *   #clone: Returns `self`; does not allow freezing.
@@ -202,7 +196,7 @@ class Numeric
   def +: (Numeric) -> Numeric
 
   # <!--
-  #   rdoc-file=numeric.c
+  #   rdoc-file=numeric.rb
   #   - +self -> self
   # -->
   # Returns `self`.
@@ -267,13 +261,15 @@ class Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - ceil(digits = 0) -> integer or float
+  #   - ceil(ndigits = 0) -> float or integer
   # -->
-  # Returns the smallest number that is greater than or equal to `self` with a
-  # precision of `digits` decimal digits.
+  # Returns the smallest float or integer that is greater than or equal to `self`,
+  # as specified by the given `ndigits`, which must be an [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
   #
-  # Numeric implements this by converting `self` to a Float and invoking
-  # Float#ceil.
+  # Equivalent to `self.to_f.ceil(ndigits)`.
+  #
+  # Related: #floor, Float#ceil.
   #
   def ceil: () -> Integer
           | (Integer digits) -> (Integer | Numeric)
@@ -393,8 +389,8 @@ class Numeric
   #     1.eql?(Rational(1, 1)) # => false
   #     1.eql?(Complex(1, 0))  # => false
   #
-  # Method `eql?` is different from +==+ in that `eql?` requires matching types,
-  # while +==+ does not.
+  # Method `eql?` is different from `==` in that `eql?` requires matching types,
+  # while `==` does not.
   #
   def eql?: (untyped) -> bool
 
@@ -420,13 +416,15 @@ class Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - floor(digits = 0) -> integer or float
+  #   - floor(ndigits = 0) -> float or integer
   # -->
-  # Returns the largest number that is less than or equal to `self` with a
-  # precision of `digits` decimal digits.
+  # Returns the largest float or integer that is less than or equal to `self`, as
+  # specified by the given `ndigits`, which must be an [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
   #
-  # Numeric implements this by converting `self` to a Float and invoking
-  # Float#floor.
+  # Equivalent to `self.to_f.floor(ndigits)`.
+  #
+  # Related: #ceil, Float#floor.
   #
   def floor: () -> Integer
            | (Integer digits) -> Numeric
@@ -532,17 +530,19 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - nonzero?  ->  self or nil
   # -->
-  # Returns `self` if `self` is not a zero value, `nil` otherwise; uses method
-  # `zero?` for the evaluation.
+  # Returns +self+ if +self+ is not a zero value, +nil+ otherwise;
+  #     uses method <tt>zero?</tt> for the evaluation.
+  #
+  #     The returned +self+ allows the method to be chained:
   #
-  # The returned `self` allows the method to be chained:
+  #       a = %w[z Bb bB bb BB a aA Aa AA A]
+  #       a.sort {|a, b| (a.downcase <=> b.downcase).nonzero? || a <=> b }
+  #       # => ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"]
   #
-  #     a = %w[z Bb bB bb BB a aA Aa AA A]
-  #     a.sort {|a, b| (a.downcase <=> b.downcase).nonzero? || a <=> b }
-  #     # => ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"]
+  #     Of the Core and Standard Library classes,
+  #     Integer, Float, Rational, and Complex use this implementation.
   #
-  # Of the Core and Standard Library classes, Integer, Float, Rational, and
-  # Complex use this implementation.
+  # Related: #zero?
   #
   def nonzero?: () -> self?
 
@@ -670,86 +670,83 @@ class Numeric
   # -->
   # Generates a sequence of numbers; with a block given, traverses the sequence.
   #
-  #     Of the Core and Standard Library classes,
-  #     Integer, Float, and Rational use this implementation.
-  #
-  #     A quick example:
-  #
-  #       squares = []
-  #       1.step(by: 2, to: 10) {|i| squares.push(i*i) }
-  #       squares # => [1, 9, 25, 49, 81]
-  #
-  #     The generated sequence:
-  #
-  #     - Begins with +self+.
-  #     - Continues at intervals of +by+ (which may not be zero).
-  #     - Ends with the last number that is within or equal to +to+;
-  #       that is, less than or equal to +to+ if +by+ is positive,
-  #       greater than or equal to +to+ if +by+ is negative.
-  #       If +to+ is +nil+, the sequence is of infinite length.
-  #
-  #     If a block is given, calls the block with each number in the sequence;
-  #     returns +self+.  If no block is given, returns an Enumerator::ArithmeticSequence.
-  #
-  #     <b>Keyword Arguments</b>
-  #
-  #     With keyword arguments +by+ and +to+,
-  #     their values (or defaults) determine the step and limit:
-  #
-  #       # Both keywords given.
-  #       squares = []
-  #       4.step(by: 2, to: 10) {|i| squares.push(i*i) }    # => 4
-  #       squares # => [16, 36, 64, 100]
-  #       cubes = []
-  #       3.step(by: -1.5, to: -3) {|i| cubes.push(i*i*i) } # => 3
-  #       cubes   # => [27.0, 3.375, 0.0, -3.375, -27.0]
-  #       squares = []
-  #       1.2.step(by: 0.2, to: 2.0) {|f| squares.push(f*f) }
-  #       squares # => [1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
-  #
-  #       squares = []
-  #       Rational(6/5).step(by: 0.2, to: 2.0) {|r| squares.push(r*r) }
-  #       squares # => [1.0, 1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
-  #
-  #       # Only keyword to given.
-  #       squares = []
-  #       4.step(to: 10) {|i| squares.push(i*i) }           # => 4
-  #       squares # => [16, 25, 36, 49, 64, 81, 100]
-  #       # Only by given.
-  #
-  #       # Only keyword by given
-  #       squares = []
-  #       4.step(by:2) {|i| squares.push(i*i); break if i > 10 }
-  #       squares # => [16, 36, 64, 100, 144]
-  #
-  #       # No block given.
-  #       e = 3.step(by: -1.5, to: -3) # => (3.step(by: -1.5, to: -3))
-  #       e.class                      # => Enumerator::ArithmeticSequence
-  #
-  #     <b>Positional Arguments</b>
-  #
-  #     With optional positional arguments +to+ and +by+,
-  #     their values (or defaults) determine the step and limit:
-  #
-  #       squares = []
-  #       4.step(10, 2) {|i| squares.push(i*i) }    # => 4
-  #       squares # => [16, 36, 64, 100]
-  #       squares = []
-  #       4.step(10) {|i| squares.push(i*i) }
-  #       squares # => [16, 25, 36, 49, 64, 81, 100]
-  #       squares = []
-  #       4.step {|i| squares.push(i*i); break if i > 10 }  # => nil
-  #       squares # => [16, 25, 36, 49, 64, 81, 100, 121]
+  # Of the Core and Standard Library classes, Integer, Float, and Rational use
+  # this implementation.
+  #
+  # A quick example:
+  #
+  #     squares = []
+  #     1.step(by: 2, to: 10) {|i| squares.push(i*i) }
+  #     squares # => [1, 9, 25, 49, 81]
+  #
+  # The generated sequence:
+  #
+  # *   Begins with `self`.
+  # *   Continues at intervals of `by` (which may not be zero).
+  # *   Ends with the last number that is within or equal to `to`; that is, less
+  #     than or equal to `to` if `by` is positive, greater than or equal to `to`
+  #     if `by` is negative. If `to` is `nil`, the sequence is of infinite length.
+  #
+  # If a block is given, calls the block with each number in the sequence; returns
+  # `self`. If no block is given, returns an Enumerator::ArithmeticSequence.
+  #
+  # **Keyword Arguments**
+  #
+  # With keyword arguments `by` and `to`, their values (or defaults) determine the
+  # step and limit:
+  #
+  #     # Both keywords given.
+  #     squares = []
+  #     4.step(by: 2, to: 10) {|i| squares.push(i*i) }    # => 4
+  #     squares # => [16, 36, 64, 100]
+  #     cubes = []
+  #     3.step(by: -1.5, to: -3) {|i| cubes.push(i*i*i) } # => 3
+  #     cubes   # => [27.0, 3.375, 0.0, -3.375, -27.0]
+  #     squares = []
+  #     1.2.step(by: 0.2, to: 2.0) {|f| squares.push(f*f) }
+  #     squares # => [1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
+  #
+  #     squares = []
+  #     Rational(6/5).step(by: 0.2, to: 2.0) {|r| squares.push(r*r) }
+  #     squares # => [1.0, 1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
+  #
+  #     # Only keyword to given.
+  #     squares = []
+  #     4.step(to: 10) {|i| squares.push(i*i) }           # => 4
+  #     squares # => [16, 25, 36, 49, 64, 81, 100]
+  #     # Only by given.
+  #
+  #     # Only keyword by given
+  #     squares = []
+  #     4.step(by:2) {|i| squares.push(i*i); break if i > 10 }
+  #     squares # => [16, 36, 64, 100, 144]
+  #
+  #     # No block given.
+  #     e = 3.step(by: -1.5, to: -3) # => (3.step(by: -1.5, to: -3))
+  #     e.class                      # => Enumerator::ArithmeticSequence
+  #
+  # **Positional Arguments**
+  #
+  # With optional positional arguments `to` and `by`, their values (or defaults)
+  # determine the step and limit:
+  #
+  #     squares = []
+  #     4.step(10, 2) {|i| squares.push(i*i) }    # => 4
+  #     squares # => [16, 36, 64, 100]
+  #     squares = []
+  #     4.step(10) {|i| squares.push(i*i) }
+  #     squares # => [16, 25, 36, 49, 64, 81, 100]
+  #     squares = []
+  #     4.step {|i| squares.push(i*i); break if i > 10 }  # => nil
+  #     squares # => [16, 25, 36, 49, 64, 81, 100, 121]
   #
   # **Implementation Notes**
   #
-  #     If all the arguments are integers, the loop operates using an integer
-  #     counter.
+  # If all the arguments are integers, the loop operates using an integer counter.
   #
-  #     If any of the arguments are floating point numbers, all are converted
-  #     to floats, and the loop is executed
-  #     <i>floor(n + n*Float::EPSILON) + 1</i> times,
-  #     where <i>n = (limit - self)/step</i>.
+  # If any of the arguments are floating point numbers, all are converted to
+  # floats, and the loop is executed *floor(n + n*Float::EPSILON) + 1* times,
+  # where *n = (limit - self)/step*.
   #
   def step: (?Numeric limit, ?Numeric step) { (Numeric) -> void } -> self
           | (?Numeric limit, ?Numeric step) -> Enumerator[Numeric, self]
@@ -779,7 +776,7 @@ class Numeric
   #     Rational(1, 2).to_int # => 0
   #     Rational(2, 1).to_int # => 2
   #     Complex(2, 0).to_int  # => 2
-  #     Complex(2, 1)         # Raises RangeError (non-zero imaginary part)
+  #     Complex(2, 1).to_int  # Raises RangeError (non-zero imaginary part)
   #
   def to_int: () -> Integer
 

data/core/object.rbs

@@ -21,14 +21,12 @@
 # *   Inherits from [class BasicObject](rdoc-ref:BasicObject@What-27s+Here).
 # *   Includes [module Kernel](rdoc-ref:Kernel@What-27s+Here).
 #
-#
 # Here, class Object provides methods for:
 #
 # *   [Querying](rdoc-ref:Object@Querying)
 # *   [Instance Variables](rdoc-ref:Object@Instance+Variables)
 # *   [Other](rdoc-ref:Object@Other)
 #
-#
 # ### Querying
 #
 # *   #!~: Returns `true` if `self` does not match the given object, otherwise
@@ -70,7 +68,6 @@
 #     argument.
 # *   #send: Calls the given method in `self` with the given argument.
 #
-#
 # ### Instance Variables
 #
 # *   #instance_variable_get: Returns the value of the given instance variable
@@ -82,7 +79,6 @@
 # *   #remove_instance_variable: Removes the named instance variable from
 #     `self`.
 #
-#
 # ### Other
 #
 # *   #clone:  Returns a shallow copy of `self`, including singleton class and
@@ -110,5 +106,5 @@ class Object < BasicObject
 end
 
 # A previous incarnation of `interned` for backward-compatibility (see #1499)
-%a{steep:deprecated}
+%a{deprecated: Use `interned` instead}
 type Object::name = interned

data/core/object_space/weak_key_map.rbs

@@ -22,17 +22,16 @@ module ObjectSpace
   #
   #         val = nil
   #         GC.start
-  #         # There is no more references to `val`, yet the pair isn't
+  #         # There are no more references to `val`, yet the pair isn't
   #         # garbage-collected.
   #         map["name"] #=> 2023-12-07 00:00:00 +0200
   #
   #         key = nil
   #         GC.start
-  #         # There is no more references to `key`, key and value are
+  #         # There are no more references to `key`, key and value are
   #         # garbage-collected.
   #         map["name"] #=> nil
   #
-  #
   # (Note that GC.start is used here only for demonstrational purposes and might
   # not always lead to demonstrated results.)
   #
@@ -55,7 +54,7 @@ module ObjectSpace
   #     end
   #
   # This will result in `make_value` returning the same object for same set of
-  # attributes always, but the values that aren't needed anymore woudn't be
+  # attributes always, but the values that aren't needed anymore wouldn't be
   # sitting in the cache forever.
   #
   class WeakKeyMap[Key, Value]

data/core/object_space.rbs

@@ -4,9 +4,9 @@
 # an iterator.
 #
 # ObjectSpace also provides support for object finalizers, procs that will be
-# called when a specific object is about to be destroyed by garbage collection.
-# See the documentation for `ObjectSpace.define_finalizer` for important
-# information on how to use this method correctly.
+# called after a specific object was destroyed by garbage collection.  See the
+# documentation for `ObjectSpace.define_finalizer` for important information on
+# how to use this method correctly.
 #
 #     a = "A"
 #     b = "B"

data/core/proc.rbs

@@ -56,7 +56,6 @@
 #
 #         lambda2 = ->(x) { x**2 }
 #
-#
 # ## Lambda and non-lambda semantics
 #
 # Procs are coming in two flavors: lambda and non-lambda (regular procs).
@@ -75,7 +74,6 @@
 #     filled with `nil`, single Array arguments are deconstructed if the proc
 #     has multiple arguments, and there is no error raised on extra arguments.
 #
-#
 # Examples:
 #
 #     # +return+ in non-lambda proc, +b+, exits +m2+.
@@ -238,19 +236,86 @@
 # Since `return` and `break` exits the block itself in lambdas, lambdas cannot
 # be orphaned.
 #
-# ## Numbered parameters
+# ## Anonymous block parameters
 #
-# Numbered parameters are implicitly defined block parameters intended to
-# simplify writing short blocks:
+# To simplify writing short blocks, Ruby provides two different types of
+# anonymous parameters: `it` (single parameter) and numbered ones: `_1`, `_2`
+# and so on.
 #
 #     # Explicit parameter:
 #     %w[test me please].each { |str| puts str.upcase } # prints TEST, ME, PLEASE
 #     (1..5).map { |i| i**2 } # => [1, 4, 9, 16, 25]
 #
-#     # Implicit parameter:
+#     # it:
+#     %w[test me please].each { puts it.upcase } # prints TEST, ME, PLEASE
+#     (1..5).map { it**2 } # => [1, 4, 9, 16, 25]
+#
+#     # Numbered parameter:
 #     %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE
 #     (1..5).map { _1**2 } # => [1, 4, 9, 16, 25]
 #
+# ### `it`
+#
+# `it` is a name that is available inside a block when no explicit parameters
+# defined, as shown above.
+#
+#     %w[test me please].each { puts it.upcase } # prints TEST, ME, PLEASE
+#     (1..5).map { it**2 } # => [1, 4, 9, 16, 25]
+#
+# `it` is a "soft keyword": it is not a reserved name, and can be used as a name
+# for methods and local variables:
+#
+#     it = 5 # no warnings
+#     def it(&block) # RSpec-like API, no warnings
+#        # ...
+#     end
+#
+# `it` can be used as a local variable even in blocks that use it as an implicit
+# parameter (though this style is obviously confusing):
+#
+#     [1, 2, 3].each {
+#       # takes a value of implicit parameter "it" and uses it to
+#       # define a local variable with the same name
+#       it = it**2
+#       p it
+#     }
+#
+# In a block with explicit parameters defined `it` usage raises an exception:
+#
+#     [1, 2, 3].each { |x| p it }
+#     # syntax error found (SyntaxError)
+#     # [1, 2, 3].each { |x| p it }
+#     #                        ^~ `it` is not allowed when an ordinary parameter is defined
+#
+# But if a local name (variable or method) is available, it would be used:
+#
+#     it = 5
+#     [1, 2, 3].each { |x| p it }
+#     # Prints 5, 5, 5
+#
+# Blocks using `it` can be nested:
+#
+#     %w[test me].each { it.each_char { p it } }
+#     # Prints "t", "e", "s", "t", "m", "e"
+#
+# Blocks using `it` are considered to have one parameter:
+#
+#     p = proc { it**2 }
+#     l = lambda { it**2 }
+#     p.parameters     # => [[:opt, nil]]
+#     p.arity          # => 1
+#     l.parameters     # => [[:req]]
+#     l.arity          # => 1
+#
+# ### Numbered parameters
+#
+# Numbered parameters are another way to name block parameters implicitly.
+# Unlike `it`, numbered parameters allow to refer to several parameters in one
+# block.
+#
+#     %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE
+#     {a: 100, b: 200}.map { "#{_1} = #{_2}" } # => "a = 100", "b = 200"
+#
 # Parameter names from `_1` to `_9` are supported:
 #
 #     [10, 20, 30].zip([40, 50, 60], [70, 80, 90]).map { _1 + _2 + _3 }
@@ -264,11 +329,16 @@
 #     [10, 20, 30].map { |x| _1**2 }
 #     # SyntaxError (ordinary parameter is defined)
 #
+# Numbered parameters can't be mixed with `it` either:
+#
+#     [10, 20, 30].map { _1 + it }
+#     # SyntaxError: `it` is not allowed when a numbered parameter is already used
+#
 # To avoid conflicts, naming local variables or method arguments `_1`, `_2` and
-# so on, causes a warning.
+# so on, causes an error.
 #
-#     _1 = 'test'
-#     # warning: `_1' is reserved as numbered parameter
+#       _1 = 'test'
+#     # ^~ _1 is reserved for numbered parameters (SyntaxError)
 #
 # Using implicit numbered parameters affects block's arity:
 #
@@ -282,12 +352,10 @@
 # Blocks with numbered parameters can't be nested:
 #
 #     %w[test me].each { _1.each_char { p _1 } }
-#     # SyntaxError (numbered parameter is already used in outer block here)
+#     # numbered parameter is already used in outer block (SyntaxError)
 #     # %w[test me].each { _1.each_char { p _1 } }
 #     #                    ^~
 #
-# Numbered parameters were introduced in Ruby 2.7.
-#
 class Proc
   interface _Callable
     def call: (?) -> untyped
@@ -308,8 +376,8 @@ class Proc
   #
   def self.new: () { (?) -> untyped } -> instance
 
-  def clone: () -> instance
-  def dup: () -> instance
+  def clone: () -> self
+  def dup: () -> self
 
   # <!-- rdoc-file=proc.c -->
   # Invokes the block, setting the block's parameters to the values in *params*