rbs 4.0.0.dev.4 → 4.0.0

data/core/nil_class.rbs

@@ -19,7 +19,7 @@
 # *   #to_s
 #
 # While `nil` doesn't have an explicitly defined #to_hash method, it can be used
-# in `**` unpacking, not adding any keyword arguments.
+# in <code>**</code> unpacking, not adding any keyword arguments.
 #
 # Another method provides inspection:
 #
@@ -97,7 +97,7 @@ class NilClass
   #   rdoc-file=object.c
   #   - inspect -> 'nil'
   # -->
-  # Returns string `'nil'`:
+  # Returns string <code>'nil'</code>:
   #
   #     nil.inspect # => "nil"
   #
@@ -107,12 +107,13 @@ class NilClass
   #   rdoc-file=object.c
   #   - nil.nil?  -> true
   # -->
-  # Returns `true`. For all other objects, method `nil?` returns `false`.
+  # Returns `true`. For all other objects, method <code>nil?</code> returns
+  # `false`.
   #
   def nil?: () -> true
 
   # <!--
-  #   rdoc-file=rational.c
+  #   rdoc-file=nilclass.rb
   #   - rationalize(eps = nil)  ->  (0/1)
   # -->
   # Returns zero as a Rational:
@@ -134,7 +135,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 +175,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

@@ -23,10 +23,10 @@
 # two-member Array containing an object that has been coerced into an instance
 # of the new class and `self` (see #coerce).
 #
-# Inheriting classes should also implement arithmetic operator methods (`+`,
-# `-`, `*` and `/`) and the `<=>` operator (see Comparable). These methods may
-# rely on `coerce` to ensure interoperability with instances of other numeric
-# classes.
+# Inheriting classes should also implement arithmetic operator methods
+# (<code>+</code>, <code>-</code>, <code>*</code> and <code>/</code>) and the
+# <code><=></code> operator (see Comparable). These methods may rely on `coerce`
+# to ensure interoperability with instances of other numeric classes.
 #
 #     class Tally < Numeric
 #       def initialize(string)
@@ -88,7 +88,7 @@
 #
 # *   #finite?: Returns true unless `self` is infinite or not a number.
 # *   #infinite?: Returns -1, `nil` or +1, depending on whether `self` is
-#     `-Infinity<tt>, finite, or <tt>+Infinity`.
+#     <code>-Infinity<tt>, finite, or <tt>+Infinity</code>.
 # *   #integer?: Returns whether `self` is an integer.
 # *   #negative?: Returns whether `self` is negative.
 # *   #nonzero?: Returns whether `self` is not zero.
@@ -119,27 +119,29 @@
 #     Math::PI otherwise.
 # *   #ceil: Returns the smallest number greater than or equal to `self`, to a
 #     given precision.
-# *   #coerce: Returns array `[coerced_self, coerced_other]` for the given other
-#     value.
+# *   #coerce: Returns array <code>[coerced_self, coerced_other]</code> for the
+#     given other value.
 # *   #conj (aliased as #conjugate): Returns the complex conjugate of `self`.
 # *   #denominator: Returns the denominator (always positive) of the Rational
 #     representation of `self`.
 # *   #div: Returns the value of `self` divided by the given value and converted
 #     to an integer.
-# *   #divmod: Returns array `[quotient, modulus]` resulting from dividing
-#     `self` the given divisor.
+# *   #divmod: Returns array <code>[quotient, modulus]</code> resulting from
+#     dividing `self` the given divisor.
 # *   #fdiv: Returns the Float result of dividing `self` by the given divisor.
 # *   #floor: Returns the largest number less than or equal to `self`, to a
 #     given precision.
-# *   #i: Returns the Complex object `Complex(0, self)`. the given value.
+# *   #i: Returns the Complex object <code>Complex(0, self)</code>. the given
+#     value.
 # *   #imaginary (aliased as #imag): Returns the imaginary part of the `self`.
 # *   #numerator: Returns the numerator of the Rational representation of
 #     `self`; has the same sign as `self`.
-# *   #polar: Returns the array `[self.abs, self.arg]`.
+# *   #polar: Returns the array <code>[self.abs, self.arg]</code>.
 # *   #quo: Returns the value of `self` divided by the given value.
 # *   #real: Returns the real part of `self`.
-# *   #rect (aliased as #rectangular): Returns the array `[self, 0]`.
-# *   #remainder: Returns `self-arg*(self/arg).truncate` for the given `arg`.
+# *   #rect (aliased as #rectangular): Returns the array <code>[self, 0]</code>.
+# *   #remainder: Returns <code>self-arg*(self/arg).truncate</code> for the
+#     given `arg`.
 # *   #round: Returns the value of `self` rounded to the nearest value for the
 #     given a precision.
 # *   #to_c: Returns the Complex representation of `self`.
@@ -160,7 +162,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 +203,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 +214,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 +254,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
@@ -267,7 +277,7 @@ class Numeric
   # as specified by the given `ndigits`, which must be an [integer-convertible
   # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
   #
-  # Equivalent to `self.to_f.ceil(ndigits)`.
+  # Equivalent to <code>self.to_f.ceil(ndigits)</code>.
   #
   # Related: #floor, Float#ceil.
   #
@@ -310,18 +320,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
@@ -335,9 +345,9 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - 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
-  # `/`.)
+  # Returns the quotient <code>self/other</code> as an integer (via `floor`),
+  # using method <code>/</code> as defined in the subclass of Numeric. (Numeric
+  # itself does not define <code>/</code>.)
   #
   # Of the Core and Standard Library classes, Only Float and Rational use this
   # implementation.
@@ -348,7 +358,7 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - divmod(other) -> array
   # -->
-  # Returns a 2-element array `[q, r]`, where
+  # Returns a 2-element array <code>[q, r]</code>, where
   #
   #     q = (self/other).floor                  # Quotient
   #     r = self % other                        # Remainder
@@ -389,8 +399,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 <code>eql?</code> is different from <code>==</code> in that
+  # <code>eql?</code> requires matching types, while <code>==</code> does not.
   #
   def eql?: (untyped) -> bool
 
@@ -398,8 +408,9 @@ 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 <code>self/other</code> as a float, using method
+  # <code>/</code> as defined in the subclass of Numeric. (Numeric itself does not
+  # define <code>/</code>.)
   #
   # Of the Core and Standard Library classes, only BigDecimal uses this
   # implementation.
@@ -422,7 +433,7 @@ class Numeric
   # specified by the given `ndigits`, which must be an [integer-convertible
   # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
   #
-  # Equivalent to `self.to_f.floor(ndigits)`.
+  # Equivalent to <code>self.to_f.floor(ndigits)</code>.
   #
   # Related: #ceil, Float#floor.
   #
@@ -433,7 +444,7 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - i -> complex
   # -->
-  # Returns `Complex(0, self)`:
+  # Returns <code>Complex(0, self)</code>:
   #
   #     2.i              # => (0+2i)
   #     -2.i             # => (0-2i)
@@ -445,25 +456,25 @@ 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
   #   - infinite? -> -1, 1, or nil
   # -->
-  # Returns `nil`, -1, or 1 depending on whether `self` is finite, `-Infinity`, or
-  # `+Infinity`.
+  # Returns `nil`, -1, or 1 depending on whether `self` is finite,
+  # <code>-Infinity</code>, or <code>+Infinity</code>.
   #
   def infinite?: () -> Integer?
 
@@ -488,7 +499,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 +541,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
+  # <code>zero?</code> 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?
   #
@@ -563,7 +574,7 @@ class Numeric
   #   rdoc-file=complex.c
   #   - polar -> array
   # -->
-  # Returns array `[self.abs, self.arg]`.
+  # Returns array <code>[self.abs, self.arg]</code>.
   #
   def polar: () -> [ Numeric, Numeric ]
 
@@ -590,7 +601,7 @@ class Numeric
   # -->
   # Returns `self`.
   #
-  def real: () -> Numeric
+  def real: () -> self
 
   # <!--
   #   rdoc-file=numeric.rb
@@ -598,10 +609,10 @@ 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]`.
+  # Returns array <code>[self, 0]</code>.
   #
   def rect: () -> [ Numeric, Numeric ]
 
@@ -609,7 +620,7 @@ class Numeric
   #   rdoc-file=complex.c
   #   - rect -> array
   # -->
-  # Returns array `[self, 0]`.
+  # Returns array <code>[self, 0]</code>.
   #
   alias rectangular rect
 
@@ -745,13 +756,13 @@ class Numeric
   # 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 *floor(n + n*Float::EPSILON) + 1* times,
-  # where *n = (limit - self)/step*.
+  # floats, and the loop is executed <em>floor(n + n*Float::EPSILON) + 1</em>
+  # times, where <em>n = (limit - self)/step</em>.
   #
   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 +776,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

@@ -12,7 +12,8 @@
 # will find the top-level File class.
 #
 # In the descriptions of Object's methods, the parameter *symbol* refers to a
-# symbol, which is either a quoted string or a Symbol (such as `:name`).
+# symbol, which is either a quoted string or a Symbol (such as
+# <code>:name</code>).
 #
 # ## What's Here
 #
@@ -32,7 +33,7 @@
 # *   #!~: Returns `true` if `self` does not match the given object, otherwise
 #     `false`.
 # *   #<=>: Returns 0 if `self` and the given object `object` are the same
-#     object, or if `self == object`; otherwise returns `nil`.
+#     object, or if <code>self == object</code>; otherwise returns `nil`.
 # *   #===: Implements case equality, effectively the same as calling #==.
 # *   #eql?: Implements hash equality, effectively the same as calling #==.
 # *   #kind_of? (aliased as #is_a?): Returns whether given argument is an
@@ -40,23 +41,24 @@
 # *   #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?`.)
+# *   #nil?: Returns `false`. (Only `nil` responds `true` to method
+#     <code>nil?</code>.)
 # *   #object_id: Returns an integer corresponding to `self` that is unique for
 #     the current process
 # *   #private_methods: Returns an array of the symbol names of the private
 #     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`.
@@ -85,7 +87,7 @@
 #     frozen state.
 # *   #define_singleton_method: Defines a singleton method in `self` for the
 #     given symbol method-name and block or proc.
-# *   #display: Prints `self` to the given IO stream or `$stdout`.
+# *   #display: Prints `self` to the given IO stream or <code>$stdout</code>.
 # *   #dup: Returns a shallow unfrozen copy of `self`.
 # *   #enum_for (aliased as #to_enum): Returns an Enumerator for `self` using
 #     the using the given method, arguments, and block.
@@ -104,7 +106,3 @@
 class Object < BasicObject
   include Kernel
 end
-
-# A previous incarnation of `interned` for backward-compatibility (see #1499)
-%a{deprecated: Use `interned` instead}
-type Object::name = interned

data/core/object_space.rbs

@@ -5,8 +5,8 @@
 #
 # ObjectSpace also provides support for object finalizers, procs that will be
 # 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.
+# documentation for <code>ObjectSpace.define_finalizer</code> for important
+# information on how to use this method correctly.
 #
 #     a = "A"
 #     b = "B"
@@ -17,7 +17,7 @@
 #     a = nil
 #     b = nil
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     Finalizer two on 537763470
 #     Finalizer one on 537763480
@@ -29,6 +29,7 @@ module ObjectSpace
   #   - _id2ref(p1)
   # -->
   #
+  %a{deprecated}
   def self._id2ref: (Integer id) -> untyped
 
   # <!--
@@ -49,9 +50,9 @@ module ObjectSpace
   # The contents of the returned hash are implementation specific. It may be
   # changed in future.
   #
-  # The keys starting with `:T_` means live objects. For example, `:T_ARRAY` is
-  # the number of arrays. `:FREE` means object slots which is not used now.
-  # `:TOTAL` means sum of above.
+  # The keys starting with <code>:T_</code> means live objects. For example,
+  # <code>:T_ARRAY</code> is the number of arrays. <code>:FREE</code> means object
+  # slots which is not used now. <code>:TOTAL</code> means sum of above.
   #
   # If the optional argument `result_hash` is given, it is overwritten and
   # returned. This is intended to avoid probe effect.
@@ -73,7 +74,7 @@ module ObjectSpace
   # object ID of the *obj* will be passed as an argument to *aProc*. If *aProc* is
   # a lambda or method, make sure it can be called with a single argument.
   #
-  # The return value is an array `[0, aProc]`.
+  # The return value is an array <code>[0, aProc]</code>.
   #
   # The two recommended patterns are to either create the finaliser proc in a
   # non-instance method where it can safely capture the needed state, or to use a
@@ -136,28 +137,34 @@ 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:*
+  # <em>produces:</em>
   #
-  #     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 <code>Ractor.new</code> 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