rbs 3.9.5 → 3.10.0.pre.1

data/core/io/wait.rbs

@@ -1,30 +1,9 @@
 %a{annotate:rdoc:skip}
 class IO
   # <!--
-  #   rdoc-file=ext/io/wait/wait.c
-  #   - io.nread -> int
-  # -->
-  # Returns number of bytes that can be read without blocking. Returns zero if no
-  # information available.
-  #
-  # You must require 'io/wait' to use this method.
-  #
-  def nread: () -> Integer
-
-  # <!--
-  #   rdoc-file=ext/io/wait/wait.c
-  #   - io.ready? -> truthy or falsy
-  # -->
-  # Returns a truthy value if input available without blocking, or a falsy value.
-  #
-  # You must require 'io/wait' to use this method.
-  #
-  def ready?: () -> boolish
-
-  # <!--
-  #   rdoc-file=ext/io/wait/wait.c
+  #   rdoc-file=io.c
   #   - io.wait(events, timeout) -> event mask, false or nil
-  #   - io.wait(timeout = nil, mode = :read) -> self, true, or false
+  #   - io.wait(*event_symbols[, timeout]) -> self, true, or false
   # -->
   # Waits until the IO becomes ready for the specified events and returns the
   # subset of events that become ready, or a falsy value when times out.
@@ -32,11 +11,14 @@ class IO
   # The events can be a bit mask of `IO::READABLE`, `IO::WRITABLE` or
   # `IO::PRIORITY`.
   #
-  # Returns a truthy value immediately when buffered data is available.
-  #
-  # Optional parameter `mode` is one of `:read`, `:write`, or `:read_write`.
+  # Returns an event mask (truthy value) immediately when buffered data is
+  # available.
   #
-  # You must require 'io/wait' to use this method.
+  # The second form: if one or more event symbols (`:read`, `:write`, or
+  # `:read_write`) are passed, the event mask is the bit OR of the bitmask
+  # corresponding to those symbols.  In this form, `timeout` is optional, the
+  # order of the arguments is arbitrary, and returns `io` if any of the events is
+  # ready.
   #
   def wait: (Integer events, ?Time::_Timeout timeout) -> (Integer | false | nil)
           | (?Time::_Timeout? timeout, *wait_mode mode) -> (self | true | false)
@@ -44,7 +26,7 @@ class IO
   type wait_mode = :read | :r | :readable | :write | :w | :writable | :read_write | :rw | :readable_writable
 
   # <!--
-  #   rdoc-file=ext/io/wait/wait.c
+  #   rdoc-file=io.c
   #   - io.wait_readable          -> truthy or falsy
   #   - io.wait_readable(timeout) -> truthy or falsy
   # -->
@@ -52,19 +34,15 @@ class IO
   # times out.  Returns a truthy value immediately when buffered data is
   # available.
   #
-  # You must require 'io/wait' to use this method.
-  #
   def wait_readable: (?Time::_Timeout? timeout) -> boolish
 
   # <!--
-  #   rdoc-file=ext/io/wait/wait.c
+  #   rdoc-file=io.c
   #   - io.wait_writable          -> truthy or falsy
   #   - io.wait_writable(timeout) -> truthy or falsy
   # -->
   # Waits until IO is writable and returns a truthy value or a falsy value when
   # times out.
   #
-  # You must require 'io/wait' to use this method.
-  #
   def wait_writable: (?Time::_Timeout? timeout) -> boolish
 end

data/core/io.rbs

@@ -2361,8 +2361,9 @@ class IO < Object
   # closed (eventually) to avoid resource leaks.
   #
   # If a block is given, the stream is passed to the block (again, open for
-  # reading, writing, or both); when the block exits, the stream is closed, and
-  # the block's value is assigned to global variable `$?` and returned.
+  # reading, writing, or both); when the block exits, the stream is closed, the
+  # block's value is returned, and the global variable `$?` is set to the child's
+  # exit status.
   #
   # Optional argument `mode` may be any valid IO mode. See [Access
   # Modes](rdoc-ref:File@Access+Modes).
@@ -2391,7 +2392,7 @@ class IO < Object
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   # *   Options for Kernel#spawn.
   #
-  # **Forked \Process**
+  # **Forked Process**
   #
   # When argument `cmd` is the 1-character string `'-'`, causes the process to
   # fork:
@@ -2785,7 +2786,8 @@ class IO < Object
   # IO objects.
   #
   # Argument `timeout` is a numeric value (such as integer or float) timeout
-  # interval in seconds.
+  # interval in seconds. `timeout` can also be `nil` or `Float::INFINITY`. `nil`
+  # and `Float::INFINITY` means no timeout.
   #
   # The method monitors the IO objects given in all three arrays, waiting for some
   # to be ready; returns a 3-element array whose elements are:

data/core/kernel.rbs

@@ -80,7 +80,7 @@
 # *   #print: Prints the given objects to standard output without a newline.
 # *   #printf: Prints the string resulting from applying the given format string
 #     to any additional arguments.
-# *   #putc: Equivalent to <tt.$stdout.putc(object)</tt> for the given object.
+# *   #putc: Equivalent to `$stdout.putc(object)` for the given object.
 # *   #puts: Equivalent to `$stdout.puts(*objects)` for the given objects.
 # *   #readline: Similar to #gets, but raises an exception at the end of file.
 # *   #readlines: Returns an array of the remaining lines from the current
@@ -725,7 +725,7 @@ module Kernel : BasicObject
   #     $ `date`                 # => "Wed Apr  9 08:56:30 CDT 2003\n"
   #     $ `echo oops && exit 99` # => "oops\n"
   #     $ $?                     # => #<Process::Status: pid 17088 exit 99>
-  #     $ $?.status              # => 99>
+  #     $ $?.exitstatus          # => 99
   #
   # The built-in syntax `%x{...}` uses this method.
   #
@@ -777,6 +777,8 @@ module Kernel : BasicObject
   # If *const* is defined as autoload, the file name to be loaded is 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 self?.autoload: (interned _module, String filename) -> NilClass
 
   # <!--
@@ -1218,6 +1220,7 @@ module Kernel : BasicObject
   #     loop do
   #       print "Input: "
   #       line = gets
+  #       # break if q, Q is entered or EOF signal (Ctrl-D on Unix, Ctrl-Z on windows) is sent
   #       break if !line or line =~ /^q/i
   #       # ...
   #     end
@@ -1463,7 +1466,9 @@ module Kernel : BasicObject
   # Kernel.srand may be used to ensure that sequences of random numbers are
   # reproducible between different runs of a program.
   #
-  # See also Random.rand.
+  # Related: Random.rand.
+  #     rand(100.0)        # => 64 (Integer because max.to_i is 100)
+  #     Random.rand(100.0) # => 30.315320967824523
   #
   def self?.rand: (?0) -> Float
                 | (int arg0) -> Integer
@@ -1585,7 +1590,8 @@ module Kernel : BasicObject
   # IO objects.
   #
   # Argument `timeout` is a numeric value (such as integer or float) timeout
-  # interval in seconds.
+  # interval in seconds. `timeout` can also be `nil` or `Float::INFINITY`. `nil`
+  # and `Float::INFINITY` means no timeout.
   #
   # The method monitors the IO objects given in all three arrays, waiting for some
   # to be ready; returns a 3-element array whose elements are:
@@ -1773,58 +1779,58 @@ module Kernel : BasicObject
   # *   Each of these tests operates only on the entity at `path0`,
   #      and returns `true` or `false`;
   #      for a non-existent entity, returns `false` (does not raise exception):
-  #  Character  |Test
-  # ------------|-------------------------------------------------------------------------
-  # <tt>'b'</tt>|Whether the entity is a block device.
-  # <tt>'c'</tt>|Whether the entity is a character device.
-  # <tt>'d'</tt>|Whether the entity is a directory.
-  # <tt>'e'</tt>|Whether the entity is an existing entity.
-  # <tt>'f'</tt>|Whether the entity is an existing regular file.
-  # <tt>'g'</tt>|Whether the entity's setgid bit is set.
-  # <tt>'G'</tt>|Whether the entity's group ownership is equal to the caller's.
-  # <tt>'k'</tt>|Whether the entity's sticky bit is set.
-  # <tt>'l'</tt>|Whether the entity is a symbolic link.
-  # <tt>'o'</tt>|Whether the entity is owned by the caller's effective uid.
-  # <tt>'O'</tt>|Like <tt>'o'</tt>, but uses the real uid (not the effective uid).
-  # <tt>'p'</tt>|Whether the entity is a FIFO device (named pipe).
-  # <tt>'r'</tt>|Whether the entity is readable by the caller's effective uid/gid.
-  # <tt>'R'</tt>|Like <tt>'r'</tt>, but uses the real uid/gid (not the effective uid/gid).
-  # <tt>'S'</tt>|Whether the entity is a socket.
-  # <tt>'u'</tt>|Whether the entity's setuid bit is set.
-  # <tt>'w'</tt>|Whether the entity is writable by the caller's effective uid/gid.
-  # <tt>'W'</tt>|Like <tt>'w'</tt>, but uses the real uid/gid (not the effective uid/gid).
-  # <tt>'x'</tt>|Whether the entity is executable by the caller's effective uid/gid.
-  # <tt>'X'</tt>|Like <tt>'x'</tt>, but uses the real uid/gid (not the effective uid/git).
-  # <tt>'z'</tt>|Whether the entity exists and is of length zero.
+  # Character|Test
+  # ---------|-------------------------------------------------------------------
+  #   `'b'`  |Whether the entity is a block device.
+  #   `'c'`  |Whether the entity is a character device.
+  #   `'d'`  |Whether the entity is a directory.
+  #   `'e'`  |Whether the entity is an existing entity.
+  #   `'f'`  |Whether the entity is an existing regular file.
+  #   `'g'`  |Whether the entity's setgid bit is set.
+  #   `'G'`  |Whether the entity's group ownership is equal to the caller's.
+  #   `'k'`  |Whether the entity's sticky bit is set.
+  #   `'l'`  |Whether the entity is a symbolic link.
+  #   `'o'`  |Whether the entity is owned by the caller's effective uid.
+  #   `'O'`  |Like `'o'`, but uses the real uid (not the effective uid).
+  #   `'p'`  |Whether the entity is a FIFO device (named pipe).
+  #   `'r'`  |Whether the entity is readable by the caller's effective uid/gid.
+  #   `'R'`  |Like `'r'`, but uses the real uid/gid (not the effective uid/gid).
+  #   `'S'`  |Whether the entity is a socket.
+  #   `'u'`  |Whether the entity's setuid bit is set.
+  #   `'w'`  |Whether the entity is writable by the caller's effective uid/gid.
+  #   `'W'`  |Like `'w'`, but uses the real uid/gid (not the effective uid/gid).
+  #   `'x'`  |Whether the entity is executable by the caller's effective uid/gid.
+  #   `'X'`  |Like `'x'`, but uses the real uid/gid (not the effective uid/git).
+  #   `'z'`  |Whether the entity exists and is of length zero.
   # *   This test operates only on the entity at `path0`,
   #      and returns an integer size or `nil`:
-  #  Character  |Test
-  # ------------|--------------------------------------------------------------------------------------------
-  # <tt>'s'</tt>|Returns positive integer size if the entity exists and has non-zero length, +nil+ otherwise.
+  # Character|Test
+  # ---------|--------------------------------------------------------------------------------------------
+  #   `'s'`  |Returns positive integer size if the entity exists and has non-zero length, `nil` otherwise.
   # *   Each of these tests operates only on the entity at `path0`,
   #      and returns a Time object;
   #      raises an exception if the entity does not exist:
-  #  Character  |Test
-  # ------------|--------------------------------------
-  # <tt>'A'</tt>|Last access time for the entity.
-  # <tt>'C'</tt>|Last change time for the entity.
-  # <tt>'M'</tt>|Last modification time for the entity.
+  # Character|Test
+  # ---------|--------------------------------------
+  #   `'A'`  |Last access time for the entity.
+  #   `'C'`  |Last change time for the entity.
+  #   `'M'`  |Last modification time for the entity.
   # *   Each of these tests operates on the modification time (`mtime`)
   #      of each of the entities at `path0` and `path1`,
   #      and returns a `true` or `false`;
   #      returns `false` if either entity does not exist:
-  #  Character  |Test
-  # ------------|---------------------------------------------------------------
-  # <tt>'<'</tt>|Whether the `mtime` at `path0` is less than that at `path1`.
-  # <tt>'='</tt>|Whether the `mtime` at `path0` is equal to that at `path1`.
-  # <tt>'>'</tt>|Whether the `mtime` at `path0` is greater than that at `path1`.
+  # Character|Test
+  # ---------|---------------------------------------------------------------
+  #   `'<'`  |Whether the `mtime` at `path0` is less than that at `path1`.
+  #   `'='`  |Whether the `mtime` at `path0` is equal to that at `path1`.
+  #   `'>'`  |Whether the `mtime` at `path0` is greater than that at `path1`.
   # *   This test operates on the content of each of the entities at `path0` and
   #     `path1`,
   #      and returns a `true` or `false`;
   #      returns `false` if either entity does not exist:
-  #  Character  |Test
-  # ------------|---------------------------------------------
-  # <tt>'-'</tt>|Whether the entities exist and are identical.
+  # Character|Test
+  # ---------|---------------------------------------------
+  #   `'-'`  |Whether the entities exist and are identical.
   #
   def self?.test: (String | Integer cmd, String | IO file1, ?String | IO file2) -> (TrueClass | FalseClass | Time | nil | Integer)
 

data/core/marshal.rbs

@@ -147,7 +147,7 @@ module Marshal
   # *   anonymous Class/Module.
   # *   objects which are related to system (ex: Dir, File::Stat, IO, File, Socket
   #     and so on)
-  # *   an instance of MatchData, Data, Method, UnboundMethod, Proc, Thread,
+  # *   an instance of MatchData, Method, UnboundMethod, Proc, Thread,
   #     ThreadGroup, Continuation
   # *   objects which define singleton methods
   #

data/core/match_data.rbs

@@ -41,7 +41,7 @@
 # *   `$'` is Regexp.last_match`.post_match`;
 # *   `$+` is Regexp.last_match`[ -1 ]` (the last capture).
 #
-# See also "Special global variables" section in Regexp documentation.
+# See also Regexp@Global+Variables.
 #
 class MatchData
   type capture = String | Symbol | int

data/core/math.rbs

@@ -410,6 +410,27 @@ module Math
   #
   def self.exp: (double x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.expm1(x) -> float
+  # -->
+  # Returns "exp(x) - 1", `e` raised to the `x` power, minus 1.
+  #
+  # *   Domain: `[-INFINITY, INFINITY]`.
+  # *   Range: `[-1.0, INFINITY]`.
+  #
+  # Examples:
+  #
+  #     expm1(-INFINITY) # => 0.0
+  #     expm1(-1.0)      # => -0.6321205588285577 # 1.0/E - 1
+  #     expm1(0.0)       # => 0.0
+  #     expm1(0.5)       # => 0.6487212707001282  # sqrt(E) - 1
+  #     expm1(1.0)       # => 1.718281828459045   # E - 1
+  #     expm1(2.0)       # => 6.38905609893065    # E**2 - 1
+  #     expm1(INFINITY)  # => Infinity
+  #
+  def self.expm1: (double x) -> Float
+
   # <!--
   #   rdoc-file=math.c
   #   - Math.frexp(x) -> [fraction, exponent]
@@ -525,9 +546,8 @@ module Math
   #
   #     [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
   #
-  # See [logarithmic gamma
-  # function](https://en.wikipedia.org/wiki/Gamma_function#The_log-gamma_function)
-  # .
+  # See [log gamma
+  # function](https://en.wikipedia.org/wiki/Gamma_function#Log-gamma_function).
   #
   # *   Domain: `(-INFINITY, INFINITY]`.
   # *   Range of first element: `(-INFINITY, INFINITY]`.
@@ -603,6 +623,25 @@ module Math
   #
   def self.log10: (double x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.log1p(x) -> float
+  # -->
+  # Returns "log(x + 1)", the base E
+  # [logarithm](https://en.wikipedia.org/wiki/Logarithm) of (`x` + 1).
+  #
+  # *   Domain: `[-1, INFINITY]`.
+  # *   Range: `[-INFINITY, INFINITY]`.
+  #
+  # Examples:
+  #
+  #     log1p(-1.0)     # => -Infinity
+  #     log1p(0.0)      # => 0.0
+  #     log1p(E - 1)    # => 1.0
+  #     log1p(INFINITY) # => Infinity
+  #
+  def self.log1p: (double x) -> Float
+
   # <!--
   #   rdoc-file=math.c
   #   - Math.log2(x) -> float

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
@@ -359,10 +359,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 +378,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

@@ -328,6 +328,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 +489,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
 
   # <!--
@@ -1321,19 +1348,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.
   #

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

@@ -530,17 +530,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?
   #

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
 
   # <!--
@@ -159,6 +160,18 @@ module ObjectSpace
   #     2.2250738585072e-308
   #     Total count: 7
   #
+  # Due to a current known Ractor implementation issue, this method will not yield
+  # Ractor-unshareable objects in multi-Ractor mode (when `Ractor.new` has been
+  # called within the process at least once). 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