rbs 4.0.0.dev.4 → 4.0.0.dev.5

data/core/method.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=proc.c -->
-# Method objects are created by Object#method, and are associated with a
+# `Method` objects are created by Object#method, and are associated with a
 # particular object (not just with a class).  They may be used to invoke the
 # method within the object, and as a block associated with an iterator.  They
 # may also be unbound from one object (creating an UnboundMethod) and bound to
@@ -54,8 +54,6 @@ class Method
   #
   def hash: () -> Integer
 
-  def dup: () -> self
-
   # <!--
   #   rdoc-file=proc.c
   #   - meth.to_s      ->  string
@@ -126,7 +124,9 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.call(args, ...)    -> obj
+  #   - meth.call(args, ...) -> obj
+  #   - meth[args, ...] -> obj
+  #   - method === obj -> result_of_method
   # -->
   # Invokes the *meth* with the specified arguments, returning the method's return
   # value.
@@ -135,23 +135,32 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
+  # Using Method#=== allows a method object to be the target of a `when` clause in
+  # a case statement.
+  #
+  #     require 'prime'
+  #
+  #     case 1373
+  #     when Prime.method(:prime?)
+  #       # ...
+  #     end
+  #
   def call: (?) -> untyped
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth << g -> a_proc
+  #   - self << g -> a_proc
   # -->
-  # Returns a proc that is the composition of this method and the given *g*. The
-  # returned proc takes a variable number of arguments, calls *g* with them then
-  # calls this method with the result.
+  # Returns a proc that is the composition of the given `g` and this method.
   #
-  #     def f(x)
-  #       x * x
-  #     end
+  # The returned proc takes a variable number of arguments. It first calls `g`
+  # with the arguments, then calls `self` with the return value of `g`.
+  #
+  #     def f(ary) = ary << 'in f'
   #
   #     f = self.method(:f)
-  #     g = proc {|x| x + x }
-  #     p (f << g).call(2) #=> 16
+  #     g = proc { |ary| ary << 'in proc' }
+  #     (f << g).call([]) # => ["in proc", "in f"]
   #
   def <<: (Proc::_Callable g) -> Proc
 
@@ -163,23 +172,32 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
+  # Using Method#=== allows a method object to be the target of a `when` clause in
+  # a case statement.
+  #
+  #     require 'prime'
+  #
+  #     case 1373
+  #     when Prime.method(:prime?)
+  #       # ...
+  #     end
+  #
   alias === call
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth >> g -> a_proc
+  #   - self >> g -> a_proc
   # -->
-  # Returns a proc that is the composition of this method and the given *g*. The
-  # returned proc takes a variable number of arguments, calls this method with
-  # them then calls *g* with the result.
+  # Returns a proc that is the composition of this method and the given `g`.
   #
-  #     def f(x)
-  #       x * x
-  #     end
+  # The returned proc takes a variable number of arguments. It first calls `self`
+  # with the arguments, then calls `g` with the return value of `self`.
+  #
+  #     def f(ary) = ary << 'in f'
   #
   #     f = self.method(:f)
-  #     g = proc {|x| x + x }
-  #     p (f >> g).call(2) #=> 8
+  #     g = proc { |ary| ary << 'in proc' }
+  #     (f >> g).call([]) # => ["in f", "in proc"]
   #
   def >>: (Proc::_Callable g) -> Proc
 
@@ -191,6 +209,16 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
+  # Using Method#=== allows a method object to be the target of a `when` clause in
+  # a case statement.
+  #
+  #     require 'prime'
+  #
+  #     case 1373
+  #     when Prime.method(:prime?)
+  #       # ...
+  #     end
+  #
   alias [] call
 
   # <!--
@@ -359,10 +387,18 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.source_location  -> [String, Integer]
+  #   - meth.source_location  -> [String, Integer, Integer, Integer, Integer]
   # -->
-  # Returns the Ruby source filename and line number containing this method or nil
-  # if this method was not defined in Ruby (i.e. native).
+  # Returns the location where the method was defined. The returned Array
+  # contains:
+  #     (1) the Ruby source filename
+  #     (2) the line number where the definition starts
+  #     (3) the column number where the definition starts
+  #     (4) the line number where the definition ends
+  #     (5) the column number where the definitions ends
+  #
+  # This method will return `nil` if the method was not defined in Ruby (i.e.
+  # native).
   #
   def source_location: () -> [String, Integer]?
 
@@ -370,8 +406,8 @@ class Method
   #   rdoc-file=proc.c
   #   - meth.super_method  -> method
   # -->
-  # Returns a Method of superclass which would be called when super is used or nil
-  # if there is no method on superclass.
+  # Returns a `Method` of superclass which would be called when super is used or
+  # nil if there is no method on superclass.
   #
   def super_method: () -> Method?
 

data/core/module.rbs

@@ -114,12 +114,15 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - mod < other   ->  true, false, or nil
+  #   - self < other -> true, false, or nil
   # -->
-  # Returns true if *mod* is a subclass of *other*. Returns `false` if *mod* is
-  # the same as *other* or *mod* is an ancestor of *other*. Returns `nil` if
-  # there's no relationship between the two. (Think of the relationship in terms
-  # of the class definition: "class A < B" implies "A < B".)
+  # Returns whether `self` is a subclass of `other`, or `nil` if there is no
+  # relationship between the two:
+  #
+  #     Float < Numeric # => true
+  #     Numeric < Float # => false
+  #     Float < Float   # => false
+  #     Float < Hash    # => nil
   #
   def <: (Module other) -> bool?
 
@@ -135,14 +138,29 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - module <=> other_module   -> -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # Comparison---Returns -1, 0, +1 or nil depending on whether `module` includes
-  # `other_module`, they are the same, or if `module` is included by
-  # `other_module`.
+  # Compares `self` and `other`.
+  #
+  # Returns:
+  #
+  # *   `-1`, if `self` includes `other`, if or `self` is a subclass of `other`.
+  # *   `0`, if `self` and `other` are the same.
+  # *   `1`, if `other` includes `self`, or if `other` is a subclass of `self`.
+  # *   `nil`, if none of the above is true.
+  #
+  # Examples:
   #
-  # Returns `nil` if `module` has no relationship with `other_module`, if
-  # `other_module` is not a module, or if the two values are incomparable.
+  #     # Class Array includes module Enumerable.
+  #              Array <=> Enumerable # => -1
+  #         Enumerable <=> Enumerable # =>  0
+  #         Enumerable <=> Array      # =>  1
+  #     # Class File is a subclass of class IO.
+  #               File <=> IO         # => -1
+  #               File <=> File       # =>  0
+  #                 IO <=> File       # =>  1
+  #     # Class File has no relationship to class String.
+  #               File <=> String     # => nil
   #
   def <=>: (untyped other) -> Integer?
 
@@ -328,6 +346,8 @@ class Module < Object
   # replaced with *filename*.  If *const* is defined but not as autoload, does
   # nothing.
   #
+  # Files that are currently being loaded must not be registered for autoload.
+  #
   def autoload: (interned _module, String filename) -> NilClass
 
   # <!--
@@ -487,6 +507,31 @@ class Module < Object
   #
   #     Added :FOO
   #
+  # If we define a class using the `class` keyword, `const_added` runs before
+  # `inherited`:
+  #
+  #     module M
+  #       def self.const_added(const_name)
+  #         super
+  #         p :const_added
+  #       end
+  #
+  #       parent = Class.new do
+  #         def self.inherited(subclass)
+  #           super
+  #           p :inherited
+  #         end
+  #       end
+  #
+  #       class Child < parent
+  #       end
+  #     end
+  #
+  # *produces:*
+  #
+  #     :const_added
+  #     :inherited
+  #
   def const_added: (Symbol) -> void
 
   # <!--
@@ -753,8 +798,6 @@ class Module < Object
   #
   def deprecate_constant: (*interned) -> self
 
-  def eql?: (untyped other) -> bool
-
   def equal?: (untyped other) -> bool
 
   # <!--
@@ -1321,19 +1364,52 @@ class Module < Object
   #   - protected(method_name, method_name, ...) -> array
   #   - protected(array)                         -> array
   # -->
-  # With no arguments, sets the default visibility for subsequently defined
-  # methods to protected. With arguments, sets the named methods to have protected
-  # visibility. String arguments are converted to symbols. An Array of Symbols
-  # and/or Strings is also accepted. If a single argument is passed, it is
-  # returned. If no argument is passed, nil is returned. If multiple arguments are
-  # passed, the arguments are returned as an array.
+  # Sets the visibility of a section or of a list of method names as protected.
+  # Accepts no arguments, a splat of method names (symbols or strings) or an array
+  # of method names. Returns the arguments that it received.
+  #
+  # ## Important difference between protected in other languages
+  #
+  # Protected methods in Ruby are different from other languages such as Java,
+  # where methods are marked as protected to give access to subclasses. In Ruby,
+  # subclasses **already have access to all methods defined in the parent class**,
+  # even private ones.
+  #
+  # Marking a method as protected allows **different objects of the same class**
+  # to call it.
+  #
+  # One use case is for comparison methods, such as `==`, if we want to expose a
+  # method for comparison between objects of the same class without making the
+  # method public to objects of other classes.
+  #
+  # ## Performance considerations
+  #
+  # Protected methods are slower than others because they can't use inline cache.
+  #
+  # ## Example
+  #
+  #     class Account
+  #       # Mark balance as protected, so that we can compare between accounts
+  #       # without making it public.
+  #       attr_reader :balance
+  #       protected :balance
+  #
+  #       def initialize(balance)
+  #         @balance = balance
+  #       end
+  #
+  #       def >(other)
+  #         # The invocation to `other.balance` is allowed because `other` is a
+  #         # different object of the same class (Account).
+  #         balance > other.balance
+  #       end
+  #     end
   #
-  # If a method has protected visibility, it is callable only where `self` of the
-  # context is the same as the method. (method definition or instance_eval). This
-  # behavior is different from Java's protected method. Usually `private` should
-  # be used.
+  #     account1 = Account.new(100)
+  #     account2 = Account.new(50)
   #
-  # Note that a protected method is slow because it can't use inline cache.
+  #     account1 > account2  # => true (works)
+  #     account1.balance     # => NoMethodError (fails because balance is not public)
   #
   # To show a private method on RDoc, use `:doc:` instead of this.
   #
@@ -1578,7 +1654,7 @@ class Module < Object
   #     m.name #=> nil
   #
   #     c = Class.new
-  #     c.set_temporary_name("MyClass(with description)")
+  #     c.set_temporary_name("MyClass(with description)") # => MyClass(with description)
   #
   #     c.new # => #<MyClass(with description):0x0....>
   #
@@ -1696,7 +1772,8 @@ class Module < Object
   # `attr_reader(name)` but deprecated. Returns an array of defined method names
   # as symbols.
   #
-  def attr: (*interned arg0) -> Array[Symbol]
+  def attr: %a{deprecated} (interned, bool) -> Array[Symbol]
+          | (*interned arg0) -> Array[Symbol]
 
   # A previous incarnation of `interned` for backward-compatibility (see #1499)
   %a{deprecated: Use `interned`}

data/core/nil_class.rbs

@@ -112,7 +112,7 @@ class NilClass
   def nil?: () -> true
 
   # <!--
-  #   rdoc-file=rational.c
+  #   rdoc-file=nilclass.rb
   #   - rationalize(eps = nil)  ->  (0/1)
   # -->
   # Returns zero as a Rational:
@@ -134,7 +134,7 @@ class NilClass
   def to_a: () -> []
 
   # <!--
-  #   rdoc-file=complex.c
+  #   rdoc-file=nilclass.rb
   #   - to_c -> (0+0i)
   # -->
   # Returns zero as a Complex:
@@ -174,7 +174,7 @@ class NilClass
   def to_i: () -> 0
 
   # <!--
-  #   rdoc-file=rational.c
+  #   rdoc-file=nilclass.rb
   #   - to_r  ->  (0/1)
   # -->
   # Returns zero as a Rational:

data/core/numeric.rbs

@@ -160,7 +160,7 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - self % other -> real_numeric
   # -->
-  # Returns `self` modulo `other` as a real number.
+  # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational).
   #
   # Of the Core and Standard Library classes, only Rational uses this
   # implementation.
@@ -201,7 +201,7 @@ class Numeric
   # -->
   # Returns `self`.
   #
-  def +@: () -> Numeric
+  def +@: () -> self
 
   # Performs subtraction: the class of the resulting object depends on the class
   # of `numeric`.
@@ -212,15 +212,23 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - -self -> numeric
   # -->
-  # Unary Minus---Returns the receiver, negated.
+  # Returns `self`, negated.
   #
-  def -@: () -> Numeric
+  def -@: () -> self
 
   # <!--
   #   rdoc-file=numeric.c
   #   - self <=> other -> zero or nil
   # -->
-  # Returns zero if `self` is the same as `other`, `nil` otherwise.
+  # Compares `self` and `other`.
+  #
+  # Returns:
+  #
+  # *   Zero, if `self` is the same as `other`.
+  # *   `nil`, otherwise.
+  #
+  # Class Numeric includes module Comparable, each of whose methods uses
+  # Numeric#<=> for comparison.
   #
   # No subclass in the Ruby Core or Standard Library uses this implementation.
   #
@@ -244,12 +252,12 @@ class Numeric
   # -->
   # Returns the square of `self`.
   #
-  def abs2: () -> Numeric
+  def abs2: () -> self
 
   # <!-- rdoc-file=complex.c -->
   # Returns zero if `self` is positive, Math::PI otherwise.
   #
-  def angle: () -> Numeric
+  def angle: () -> (0 | Float)
 
   # <!--
   #   rdoc-file=complex.c
@@ -310,18 +318,18 @@ class Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - conj()
+  #   - conj -> self
   # -->
+  # Returns `self`.
   #
-  def conj: () -> Numeric
+  def conjugate: () -> self
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - conj -> self
+  #   - conj()
   # -->
-  # Returns `self`.
   #
-  def conjugate: () -> Numeric
+  alias conj conjugate
 
   # <!--
   #   rdoc-file=rational.c
@@ -336,7 +344,7 @@ class Numeric
   #   - div(other) -> integer
   # -->
   # Returns the quotient `self/other` as an integer (via `floor`), using method
-  # `/` in the derived class of `self`. (Numeric itself does not define method
+  # `/` as defined in the subclass of Numeric. (Numeric itself does not define
   # `/`.)
   #
   # Of the Core and Standard Library classes, Only Float and Rational use this
@@ -398,8 +406,8 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - fdiv(other) -> float
   # -->
-  # Returns the quotient `self/other` as a float, using method `/` in the derived
-  # class of `self`. (Numeric itself does not define method `/`.)
+  # Returns the quotient `self/other` as a float, using method `/` as defined in
+  # the subclass of Numeric. (Numeric itself does not define `/`.)
   #
   # Of the Core and Standard Library classes, only BigDecimal uses this
   # implementation.
@@ -445,18 +453,18 @@ class Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - imag()
+  #   - imag -> 0
   # -->
+  # Returns zero.
   #
-  def imag: () -> Numeric
+  def imaginary: () -> 0
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - imag -> 0
+  #   - imag()
   # -->
-  # Returns zero.
   #
-  def imaginary: () -> Numeric
+  alias imag imaginary
 
   # <!--
   #   rdoc-file=numeric.rb
@@ -488,7 +496,7 @@ class Numeric
   alias magnitude abs
 
   # <!-- rdoc-file=numeric.c -->
-  # Returns `self` modulo `other` as a real number.
+  # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational).
   #
   # Of the Core and Standard Library classes, only Rational uses this
   # implementation.
@@ -530,17 +538,17 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - nonzero?  ->  self or nil
   # -->
-  # Returns +self+ if +self+ is not a zero value, +nil+ otherwise;
-  #     uses method <tt>zero?</tt> for the evaluation.
+  # Returns `self` if `self` is not a zero value, `nil` otherwise; uses method
+  # `zero?` 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?
   #
@@ -590,7 +598,7 @@ class Numeric
   # -->
   # Returns `self`.
   #
-  def real: () -> Numeric
+  def real: () -> self
 
   # <!--
   #   rdoc-file=numeric.rb
@@ -598,7 +606,7 @@ class Numeric
   # -->
   # Returns `true` if `self` is a real number (i.e. not Complex).
   #
-  def real?: () -> bool
+  def real?: () -> true
 
   # <!-- rdoc-file=complex.c -->
   # Returns array `[self, 0]`.
@@ -749,9 +757,9 @@ class Numeric
   # where *n = (limit - self)/step*.
   #
   def step: (?Numeric limit, ?Numeric step) { (Numeric) -> void } -> self
-          | (?Numeric limit, ?Numeric step) -> Enumerator[Numeric, self]
+          | (?Numeric limit, ?Numeric step) -> Enumerator::ArithmeticSequence
           | (?by: Numeric, ?to: Numeric) { (Numeric) -> void } -> self
-          | (?by: Numeric, ?to: Numeric) -> Enumerator[Numeric, self]
+          | (?by: Numeric, ?to: Numeric) -> Enumerator::ArithmeticSequence
 
   # <!--
   #   rdoc-file=complex.c
@@ -765,8 +773,8 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - to_int -> integer
   # -->
-  # Returns `self` as an integer; converts using method `to_i` in the derived
-  # class.
+  # Returns `self` as an integer; converts using method `to_i` in the subclass of
+  # Numeric. (Numeric itself does not define `to_i`.)
   #
   # Of the Core and Standard Library classes, only Rational and Complex use this
   # implementation.

data/core/object.rbs

@@ -40,7 +40,7 @@
 # *   #instance_of?: Returns whether `self` is an instance of the given class.
 # *   #instance_variable_defined?: Returns whether the given instance variable
 #     is defined in `self`.
-# *   #method: Returns the Method object for the given method in `self`.
+# *   #method: Returns the `Method` object for the given method in `self`.
 # *   #methods: Returns an array of symbol names of public and protected methods
 #     in `self`.
 # *   #nil?: Returns `false`. (Only `nil` responds `true` to method `nil?`.)
@@ -50,13 +50,13 @@
 #     methods in `self`.
 # *   #protected_methods: Returns an array of the symbol names of the protected
 #     methods in `self`.
-# *   #public_method: Returns the Method object for the given public method in
+# *   #public_method: Returns the `Method` object for the given public method in
 #     `self`.
 # *   #public_methods: Returns an array of the symbol names of the public
 #     methods in `self`.
 # *   #respond_to?: Returns whether `self` responds to the given method.
 # *   #singleton_class: Returns the singleton class of `self`.
-# *   #singleton_method: Returns the Method object for the given singleton
+# *   #singleton_method: Returns the `Method` object for the given singleton
 #     method in `self`.
 # *   #singleton_methods: Returns an array of the symbol names of the singleton
 #     methods in `self`.

data/core/object_space.rbs

@@ -29,6 +29,7 @@ module ObjectSpace
   #   - _id2ref(p1)
   # -->
   #
+  %a{deprecated}
   def self._id2ref: (Integer id) -> untyped
 
   # <!--
@@ -136,28 +137,33 @@ module ObjectSpace
   # Calls the block once for each living, nonimmediate object in this Ruby
   # process. If *module* is specified, calls the block for only those classes or
   # modules that match (or are a subclass of) *module*. Returns the number of
-  # objects found. Immediate objects (`Fixnum`s, `Symbol`s `true`, `false`, and
-  # `nil`) are never returned. In the example below, #each_object returns both the
-  # numbers we defined and several constants defined in the Math module.
+  # objects found. Immediate objects (such as `Fixnum`s, static `Symbol`s `true`,
+  # `false` and `nil`) are never returned.
   #
   # If no block is given, an enumerator is returned instead.
   #
-  #     a = 102.7
-  #     b = 95       # Won't be returned
-  #     c = 12345678987654321
-  #     count = ObjectSpace.each_object(Numeric) {|x| p x }
+  #     Job = Class.new
+  #     jobs = [Job.new, Job.new]
+  #     count = ObjectSpace.each_object(Job) {|x| p x }
   #     puts "Total count: #{count}"
   #
   # *produces:*
   #
-  #     12345678987654321
-  #     102.7
-  #     2.71828182845905
-  #     3.14159265358979
-  #     2.22044604925031e-16
-  #     1.7976931348623157e+308
-  #     2.2250738585072e-308
-  #     Total count: 7
+  #     #<Job:0x000000011d6cbbf0>
+  #     #<Job:0x000000011d6cbc68>
+  #      Total count: 2
+  #
+  # Due to a current Ractor implementation issue, this method does not yield
+  # Ractor-unshareable objects when the process is in multi-Ractor mode.
+  # Multi-ractor mode is enabled when `Ractor.new` has been called for the first
+  # time. See https://bugs.ruby-lang.org/issues/19387 for more information.
+  #
+  #     a = 12345678987654321 # shareable
+  #     b = [].freeze # shareable
+  #     c = {} # not shareable
+  #     ObjectSpace.each_object {|x| x } # yields a, b, and c
+  #     Ractor.new {} # enter multi-Ractor mode
+  #     ObjectSpace.each_object {|x| x } # does not yield c
   #
   def self.each_object: (?Module `module`) -> Enumerator[untyped, Integer]
                       | (?Module `module`) { (untyped obj) -> void } -> Integer