rbs 3.8.0.pre.1 → 3.8.1

data/core/exception.rbs

@@ -19,7 +19,7 @@
 #
 # *   NoMemoryError
 # *   ScriptError
-#     *   [LoadError](https://docs.ruby-lang.org/en/master/LoadError.html)
+#     *   LoadError
 #     *   NotImplementedError
 #     *   SyntaxError
 # *   SecurityError
@@ -51,7 +51,7 @@
 #     *   ZeroDivisionError
 # *   SystemExit
 # *   SystemStackError
-# *   [fatal](https://docs.ruby-lang.org/en/master/fatal.html)
+# *   [fatal](rdoc-ref:fatal)
 #
 class Exception
   # <!--
@@ -99,24 +99,31 @@ class Exception
   #   rdoc-file=error.c
   #   - backtrace -> array or nil
   # -->
-  # Returns a backtrace value for `self`; the returned value depends on the form
-  # of the stored backtrace value:
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of strings.
   #
-  # *   Array of Thread::Backtrace::Location objects: returns the array of strings
-  #     given by `Exception#backtrace_locations.map {|loc| loc.to_s }`. This is
-  #     the normal case, where the backtrace value was stored by Kernel#raise.
-  # *   Array of strings: returns that array. This is the unusual case, where the
-  #     backtrace value was explicitly stored as an array of strings.
-  # *   `nil`: returns `nil`.
+  # Example (assuming the code is stored in the file named `t.rb`):
   #
-  # Example:
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
   #
   #     begin
-  #       1 / 0
-  #     rescue => x
-  #       x.backtrace.take(2)
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace.first
+  #       p loc.class
+  #       # String
   #     end
-  #     # => ["(irb):132:in `/'", "(irb):132:in `<top (required)>'"]
+  #
+  # The value returned by this method migth be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace_locations that provide the same value, as structured
+  # objects. (Note though that two values might not be consistent with each other
+  # when backtraces are manually adjusted.)
   #
   # see [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -126,20 +133,37 @@ class Exception
   #   rdoc-file=error.c
   #   - backtrace_locations -> array or nil
   # -->
-  # Returns a backtrace value for `self`; the returned value depends on the form
-  # of the stored backtrace value:
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of Thread::Backtrace::Location instances.
   #
-  # *   Array of Thread::Backtrace::Location objects: returns that array.
-  # *   Array of strings or `nil`: returns `nil`.
+  # Example (assuming the code is stored in the file named `t.rb`):
   #
-  # Example:
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
   #
   #     begin
-  #       1 / 0
-  #     rescue => x
-  #       x.backtrace_locations.take(2)
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace_locations
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace_locations.first
+  #       p loc.class
+  #       # Thread::Backtrace::Location
+  #       p loc.path
+  #       # "t.rb"
+  #       p loc.lineno
+  #       # 2
+  #       p loc.label
+  #       # "Integer#/"
   #     end
-  #     # => ["(irb):150:in `/'", "(irb):150:in `<top (required)>'"]
+  #
+  # The value returned by this method might be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace that provide the same value as an array of strings. (Note
+  # though that two values might not be consistent with each other when backtraces
+  # are manually adjusted.)
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -294,15 +318,100 @@ class Exception
   #   rdoc-file=error.c
   #   - set_backtrace(value) -> value
   # -->
-  # Sets the backtrace value for `self`; returns the given +value:
+  # Sets the backtrace value for `self`; returns the given `value`.
   #
-  #     x = RuntimeError.new('Boom')
-  #     x.set_backtrace(%w[foo bar baz]) # => ["foo", "bar", "baz"]
-  #     x.backtrace                      # => ["foo", "bar", "baz"]
+  # The `value` might be:
   #
-  # The given `value` must be an array of strings, a single string, or `nil`.
+  # *   an array of Thread::Backtrace::Location;
+  # *   an array of String instances;
+  # *   a single String instance; or
+  # *   `nil`.
+  #
+  # Using array of Thread::Backtrace::Location is the most consistent option: it
+  # sets both #backtrace and #backtrace_locations. It should be preferred when
+  # possible. The suitable array of locations can be obtained from
+  # Kernel#caller_locations, copied from another error, or just set to the
+  # adjusted result of the current error's #backtrace_locations:
+  #
+  #     require 'json'
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)  # test.rb, line 4
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(ex.backtrace_locations[2...])
+  #       raise
+  #     end
   #
-  # Does not affect the value returned by #backtrace_locations.
+  #     parse_payload('{"wrong: "json"')
+  #     # test.rb:4:in 'Object#parse_payload': unexpected token at '{"wrong: "json"' (JSON::ParserError)
+  #     #
+  #     # An error points to the body of parse_payload method,
+  #     # hiding the parts of the backtrace related to the internals
+  #     # of the "json" library
+  #
+  #     # The error has both #backtace and #backtrace_locations set
+  #     # consistently:
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #     end
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only #backtrace is affected:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(["dsl.rb:34", "framework.rb:1"])
+  #       # The error have the new value in #backtrace:
+  #       p ex.backtrace
+  #       # ["dsl.rb:34", "framework.rb:1"]
+  #
+  #       # but the original one in #backtrace_locations
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # Calling #set_backtrace with `nil` clears up #backtrace but doesn't affect
+  # #backtrace_locations:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       p ex.backtrace
+  #       # nil
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # On reraising of such an exception, both #backtrace and #backtrace_locations is
+  # set to the place of reraising:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       raise # test.rb, line 7
+  #     end
+  #
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #     end
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -358,16 +467,16 @@ class Exception
   # Output:
   #
   #     "divided by 0"
-  #     ["t.rb:3:in `/': divided by 0 (ZeroDivisionError)",
-  #      "\tfrom t.rb:3:in `baz'",
-  #      "\tfrom t.rb:10:in `bar'",
-  #      "\tfrom t.rb:11:in `foo'",
-  #      "\tfrom t.rb:12:in `<main>'"]
-  #     ["t.rb:3:in `/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
-  #      "\tfrom t.rb:3:in `baz'",
-  #      "\tfrom t.rb:10:in `bar'",
-  #      "\tfrom t.rb:11:in `foo'",
-  #      "\tfrom t.rb:12:in `<main>'"]
+  #     ["t.rb:3:in 'Integer#/': divided by 0 (ZeroDivisionError)",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
+  #     ["t.rb:3:in 'Integer#/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
   #
   # An overriding method should be careful with ANSI code enhancements; see
   # [Messages](rdoc-ref:exceptions.md@Messages).

data/core/file.rbs

@@ -1314,7 +1314,7 @@ class File < IO
   #
   #     File.join("usr", "mail", "gumby")   #=> "usr/mail/gumby"
   #
-  def self.join: (*string) -> String
+  def self.join: (*path) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -2295,43 +2295,36 @@ File::Constants::DSYNC: Integer
 File::Constants::EXCL: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_CASEFOLD
 # [File::FNM_CASEFOLD](rdoc-ref:File::Constants@File-3A-3AFNM_CASEFOLD)
 #
 File::Constants::FNM_CASEFOLD: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_DOTMATCH
 # [File::FNM_DOTMATCH](rdoc-ref:File::Constants@File-3A-3AFNM_DOTMATCH)
 #
 File::Constants::FNM_DOTMATCH: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_EXTGLOB
 # [File::FNM_EXTGLOB](rdoc-ref:File::Constants@File-3A-3AFNM_EXTGLOB)
 #
 File::Constants::FNM_EXTGLOB: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_NOESCAPE
 # [File::FNM_NOESCAPE](rdoc-ref:File::Constants@File-3A-3AFNM_NOESCAPE)
 #
 File::Constants::FNM_NOESCAPE: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_PATHNAME
 # [File::FNM_PATHNAME](rdoc-ref:File::Constants@File-3A-3AFNM_PATHNAME)
 #
 File::Constants::FNM_PATHNAME: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_SHORTNAME
 # [File::FNM_SHORTNAME](rdoc-ref:File::Constants@File-3A-3AFNM_SHORTNAME)
 #
 File::Constants::FNM_SHORTNAME: Integer
 
 # <!-- rdoc-file=dir.c -->
-# FNM_SYSCASE
 # [File::FNM_SYSCASE](rdoc-ref:File::Constants@File-3A-3AFNM_SYSCASE)
 #
 File::Constants::FNM_SYSCASE: Integer

data/core/gc.rbs

@@ -167,7 +167,8 @@ module GC
   # Configuration parameters are GC implementation-specific and may change without
   # notice.
   #
-  # This method can be called without parameters to retrieve the current config.
+  # This method can be called without parameters to retrieve the current config as
+  # a `Hash` with `Symbol` keys.
   #
   # This method can also be called with a `Hash` argument to assign values to
   # valid config keys. Config keys missing from the passed `Hash` will be left
@@ -185,7 +186,24 @@ module GC
   #
   # This method is only expected to work on CRuby.
   #
-  # Valid config keys for Ruby's default GC implementation are:
+  # ### GC Implementation independent values
+  #
+  # The `GC.config` hash can also contain keys that are global and read-only.
+  # These keys are not specific to any one GC library implementation and
+  # attempting to write to them will raise `ArgumentError`.
+  #
+  # There is currently only one global, read-only key:
+  #
+  # implementation
+  # :   Returns a `String` containing the name of the currently loaded GC library,
+  #     if one has been loaded using `RUBY_GC_LIBRARY`, and "default" in all other
+  #     cases
+  #
+  #
+  # ### GC Implementation specific values
+  #
+  # GC libraries are expected to document their own configuration. Valid keys for
+  # Ruby's default GC implementation are:
   #
   # rgengc_allow_full_mark
   # :   Controls whether the GC is allowed to run a full mark (young & old
@@ -569,7 +587,7 @@ module GC
 
   # The type that `GC.compact` and related functions can return.
   #
-  type compact_info = Hash[:considered | :moved |:moved_up | :moved_down, Hash[Symbol, Integer]]
+  type compact_info = Hash[:considered | :moved | :moved_up | :moved_down, Hash[Symbol, Integer]]
 
   # <!--
   #   rdoc-file=gc.rb

data/core/hash.rbs

@@ -1226,7 +1226,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   # Returns a new String containing the hash entries:
   #
   #     h = {foo: 0, bar: 1, baz: 2}
-  #     h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}"
+  #     h.inspect # => "{foo: 0, bar: 1, baz: 2}"
   #
   def inspect: () -> String
 
@@ -1628,7 +1628,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   # Returns a new String containing the hash entries:
   #
   #     h = {foo: 0, bar: 1, baz: 2}
-  #     h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}"
+  #     h.inspect # => "{foo: 0, bar: 1, baz: 2}"
   #
   alias to_s inspect
 

data/core/io.rbs

@@ -3104,8 +3104,8 @@ class IO < Object
   #
   # Returns an Enumerator if no block is given.
   #
-  def each_line: (?String sep, ?Integer limit) { (String line) -> void } -> self
-               | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
+  def each_line: (?string sep, ?int limit, ?chomp: boolish) { (String line) -> void } -> self
+               | (?string sep, ?int limit, ?chomp: boolish) -> ::Enumerator[String, self]
 
   # <!--
   #   rdoc-file=io.c

data/core/kernel.rbs

@@ -675,7 +675,7 @@ module Kernel : BasicObject
   #
   #     String([0, 1, 2])        # => "[0, 1, 2]"
   #     String(0..5)             # => "0..5"
-  #     String({foo: 0, bar: 1}) # => "{:foo=>0, :bar=>1}"
+  #     String({foo: 0, bar: 1}) # => "{foo: 0, bar: 1}"
   #
   # Raises `TypeError` if `object` cannot be converted to a string.
   #
@@ -936,16 +936,37 @@ module Kernel : BasicObject
   #
   # See [Messages](rdoc-ref:exceptions.md@Messages).
   #
-  # Argument `backtrace` sets the stored backtrace in the new exception, which may
-  # be retrieved by method Exception#backtrace; the backtrace must be an array of
-  # strings or `nil`:
+  # Argument `backtrace` might be used to modify the backtrace of the new
+  # exception, as reported by Exception#backtrace and
+  # Exception#backtrace_locations; the backtrace must be an array of
+  # Thread::Backtrace::Location, an array of strings, a single string, or `nil`.
+  #
+  # Using the array of Thread::Backtrace::Location instances is the most
+  # consistent option and should be preferred when possible. The necessary value
+  # might be obtained from #caller_locations, or copied from
+  # Exception#backtrace_locations of another error:
   #
   #     begin
-  #       raise(StandardError, 'Boom', %w[foo bar baz])
-  #     rescue => x
-  #       p x.backtrace
+  #       do_some_work()
+  #     rescue ZeroDivisionError => ex
+  #       raise(LogicalError, "You have an error in your math", ex.backtrace_locations)
+  #     end
+  #
+  # The ways, both Exception#backtrace and Exception#backtrace_locations of the
+  # raised error are set to the same backtrace.
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only Exception#backtrace is set:
+  #
+  #     begin
+  #       raise(StandardError, 'Boom', %w[dsl.rb:3 framework.rb:1])
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # => ["dsl.rb:3", "framework.rb:1"]
+  #       p ex.backtrace_locations
+  #       # => nil
   #     end
-  #     # => ["foo", "bar", "baz"]
   #
   # If argument `backtrace` is not given, the backtrace is set according to an
   # array of Thread::Backtrace::Location objects, as derived from the call stack.
@@ -1021,16 +1042,37 @@ module Kernel : BasicObject
   #
   # See [Messages](rdoc-ref:exceptions.md@Messages).
   #
-  # Argument `backtrace` sets the stored backtrace in the new exception, which may
-  # be retrieved by method Exception#backtrace; the backtrace must be an array of
-  # strings or `nil`:
+  # Argument `backtrace` might be used to modify the backtrace of the new
+  # exception, as reported by Exception#backtrace and
+  # Exception#backtrace_locations; the backtrace must be an array of
+  # Thread::Backtrace::Location, an array of strings, a single string, or `nil`.
+  #
+  # Using the array of Thread::Backtrace::Location instances is the most
+  # consistent option and should be preferred when possible. The necessary value
+  # might be obtained from #caller_locations, or copied from
+  # Exception#backtrace_locations of another error:
   #
   #     begin
-  #       raise(StandardError, 'Boom', %w[foo bar baz])
-  #     rescue => x
-  #       p x.backtrace
+  #       do_some_work()
+  #     rescue ZeroDivisionError => ex
+  #       raise(LogicalError, "You have an error in your math", ex.backtrace_locations)
+  #     end
+  #
+  # The ways, both Exception#backtrace and Exception#backtrace_locations of the
+  # raised error are set to the same backtrace.
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only Exception#backtrace is set:
+  #
+  #     begin
+  #       raise(StandardError, 'Boom', %w[dsl.rb:3 framework.rb:1])
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # => ["dsl.rb:3", "framework.rb:1"]
+  #       p ex.backtrace_locations
+  #       # => nil
   #     end
-  #     # => ["foo", "bar", "baz"]
   #
   # If argument `backtrace` is not given, the backtrace is set according to an
   # array of Thread::Backtrace::Location objects, as derived from the call stack.
@@ -1499,7 +1541,7 @@ module Kernel : BasicObject
   # Optional keyword arguments `enc_opts` specify encoding options; see [Encoding
   # options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  def self?.readlines: (?String arg0, ?Integer arg1) -> ::Array[String]
+  def self?.readlines: (?string sep, ?int limit, ?chomp: boolish) -> ::Array[String]
 
   # <!--
   #   rdoc-file=lib/rubygems/core_ext/kernel_require.rb

data/core/nil_class.rbs

@@ -18,6 +18,9 @@
 # *   #to_r
 # *   #to_s
 #
+# While `nil` doesn't have an explicitly defined #to_hash method, it can be used
+# in `**` unpacking, not adding any keyword arguments.
+#
 # Another method provides inspection:
 #
 # *   #inspect

data/core/numeric.rbs

@@ -776,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/proc.rbs

@@ -236,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 }
@@ -262,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:
 #
@@ -280,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

data/core/ractor.rbs

@@ -588,6 +588,23 @@ class Ractor
   #
   def self.shareable?: (untyped obj) -> bool
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - Ractor.store_if_absent(key){ init_block }
+  # -->
+  # If the correponding value is not set, yield a value with init_block and store
+  # the value in thread-safe manner. This method returns corresponding stored
+  # value.
+  #
+  #     (1..10).map{
+  #       Thread.new(it){|i|
+  #         Ractor.store_if_absent(:s){ f(); i }
+  #         #=> return stored value of key :s
+  #       }
+  #     }.map(&:value).uniq.size #=> 1 and f() is called only once
+  #
+  def self.store_if_absent: [A] (Symbol) { (nil) -> A } -> A
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - Ractor.yield(msg, move: false) -> nil
@@ -1036,6 +1053,9 @@ class Ractor
   #     end
   #
   class RemoteError < Ractor::Error
+    # <!-- rdoc-file=ractor.rb -->
+    # The Ractor an uncaught exception is raised in.
+    #
     def ractor: () -> Ractor
   end