rbs 3.10.4 → 4.0.0

data/core/errno.rbs

@@ -9,7 +9,7 @@
 #
 # When the Ruby interpreter interacts with the operating system and receives
 # such an error code (e.g., `2`), it maps the code to a particular Ruby
-# exception class (e.g., `Errno::ENOENT`):
+# exception class (e.g., <code>Errno::ENOENT</code>):
 #
 #     File.open('nosuch.txt')
 #     # => No such file or directory @ rb_sysopen - nosuch.txt (Errno::ENOENT)
@@ -25,7 +25,8 @@
 #     Errno::ENOENT.superclass # => SystemCallError
 #     Errno::ENOENT::Errno     # => 2
 #
-# The names of nested classes are returned by method `Errno.constants`:
+# The names of nested classes are returned by method
+# <code>Errno.constants</code>:
 #
 #     Errno.constants.size         # => 158
 #     Errno.constants.sort.take(5) # => [:E2BIG, :EACCES, :EADDRINUSE, :EADDRNOTAVAIL, :EADV]

data/core/errors.rbs

@@ -6,7 +6,7 @@
 #
 #     [1, 2, 3].first(4, 5)
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     ArgumentError: wrong number of arguments (given 2, expected 1)
 #
@@ -14,7 +14,7 @@
 #
 #     [1, 2, 3].first(-4)
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     ArgumentError: negative array size
 #
@@ -66,7 +66,7 @@ end
 #
 #     [1, 2, 3].freeze << 4
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     FrozenError: can't modify frozen Array
 #
@@ -115,11 +115,11 @@ end
 #       puts "Note: You will typically use Signal.trap instead."
 #     end
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     Press ctrl-C when you get bored
 #
-# *then waits until it is interrupted with Control-C and then prints:*
+# <em>then waits until it is interrupted with Control-C and then prints:</em>
 #
 #     Note: You will typically use Signal.trap instead.
 #
@@ -184,7 +184,7 @@ end
 #
 #     require 'this/file/does/not/exist'
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LoadError: no such file to load -- this/file/does/not/exist
 #
@@ -209,7 +209,7 @@ end
 #     end
 #     call_block
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LocalJumpError: no block given (yield)
 #
@@ -220,7 +220,7 @@ end
 #     end
 #     get_me_a_return.call
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LocalJumpError: unexpected return
 #
@@ -248,7 +248,7 @@ end
 #
 #     puts foo
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     NameError: undefined local variable or method `foo' for main:Object
 #
@@ -256,7 +256,7 @@ end
 #
 #     Integer.const_set :answer, 42
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     NameError: wrong constant name answer
 #
@@ -350,7 +350,7 @@ end
 #
 #     "hello".to_ary
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     NoMethodError: undefined method `to_ary' for an instance of String
 #
@@ -360,11 +360,13 @@ class NoMethodError[T] < NameError[T]
   #   - NoMethodError.new(msg=nil, name=nil, args=nil, private=false, receiver: nil)  -> no_method_error
   # -->
   # Construct a NoMethodError exception for a method of the given name called with
-  # the given arguments. The name may be accessed using the `#name` method on the
-  # resulting object, and the arguments using the `#args` method.
+  # the given arguments. The name may be accessed using the <code>#name</code>
+  # method on the resulting object, and the arguments using the <code>#args</code>
+  # method.
   #
   # If *private* argument were passed, it designates method was attempted to call
-  # in private context, and can be accessed with `#private_call?` method.
+  # in private context, and can be accessed with <code>#private_call?</code>
+  # method.
   #
   # *receiver* argument stores an object whose method was called.
   #
@@ -393,8 +395,8 @@ end
 # exception if the underlying operating system or Ruby runtime does not support
 # them.
 #
-# Note that if `fork` raises a `NotImplementedError`, then `respond_to?(:fork)`
-# returns `false`.
+# Note that if `fork` raises a `NotImplementedError`, then
+# <code>respond_to?(:fork)</code> returns `false`.
 #
 class NotImplementedError < ScriptError
 end
@@ -404,7 +406,7 @@ end
 #
 #     [1, 2, 3].drop(1 << 100)
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     RangeError: bignum too big to convert into `long'
 #
@@ -416,7 +418,7 @@ end
 #
 #     Regexp.new("?")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     RegexpError: target of repeat operator is not specified: /?/
 #
@@ -429,7 +431,7 @@ end
 #
 #     raise "ouch"
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     RuntimeError: ouch
 #
@@ -461,7 +463,7 @@ end
 #       puts "received Exception #{e}"
 #     end
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     received Exception SIGHUP
 #
@@ -502,7 +504,7 @@ end
 #
 #     require 'does/not/exist' rescue "Hi"
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LoadError: no such file to load -- does/not/exist
 #
@@ -520,7 +522,7 @@ end
 #     end
 #     puts "Done!"
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     Hello
 #     Done!
@@ -560,7 +562,7 @@ end
 #
 #     eval("1+1=2")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     SyntaxError: (eval):1: syntax error, unexpected '=', expecting $end
 #
@@ -587,7 +589,7 @@ end
 #
 #     File.open("does/not/exist")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     Errno::ENOENT: No such file or directory - does/not/exist
 #
@@ -614,7 +616,7 @@ class SystemCallError < StandardError
   #     SystemCallError.new("foo", Errno::EPIPE::Errno)
   #     #=> #<Errno::EPIPE: Broken pipe - foo>
   #
-  # If *func* is not `nil`, it is appended to the message with "` @ `".
+  # If *func* is not `nil`, it is appended to the message with "<code> @ </code>".
   #
   #     SystemCallError.new("foo", Errno::EPIPE::Errno, "here")
   #     #=> #<Errno::EPIPE: Broken pipe @ here - foo>
@@ -685,7 +687,7 @@ end
 #     end
 #     me_myself_and_i
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     SystemStackError: stack level too deep
 #
@@ -712,7 +714,7 @@ end
 #
 #     [1, 2, 3].first("two")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     TypeError: no implicit conversion of String into Integer
 #
@@ -725,7 +727,7 @@ end
 #
 #     throw "foo", "bar"
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     UncaughtThrowError: uncaught throw "foo"
 #
@@ -741,7 +743,7 @@ class UncaughtThrowError < ArgumentError
   #
   #     throw "foo", "bar"
   #
-  # *raises the exception:*
+  # <em>raises the exception:</em>
   #
   #     UncaughtThrowError: uncaught throw "foo"
   #

data/core/exception.rbs

@@ -102,7 +102,7 @@ class Exception
   # Returns the backtrace (the list of code locations that led to the exception),
   # as an array of strings.
   #
-  # Example (assuming the code is stored in the file named `t.rb`):
+  # Example (assuming the code is stored in the file named <code>t.rb</code>):
   #
   #     def division(numerator, denominator)
   #       numerator / denominator
@@ -136,7 +136,7 @@ class Exception
   # Returns the backtrace (the list of code locations that led to the exception),
   # as an array of Thread::Backtrace::Location instances.
   #
-  # Example (assuming the code is stored in the file named `t.rb`):
+  # Example (assuming the code is stored in the file named <code>t.rb</code>):
   #
   #     def division(numerator, denominator)
   #       numerator / denominator
@@ -173,8 +173,8 @@ class Exception
   #   rdoc-file=error.c
   #   - cause -> exception or nil
   # -->
-  # Returns the previous value of global variable `$!`, which may be `nil` (see
-  # [Global Variables](rdoc-ref:exceptions.md@Global+Variables)):
+  # Returns the previous value of global variable <code>$!</code>, which may be
+  # `nil` (see [Global Variables](rdoc-ref:exceptions.md@Global+Variables)):
   #
   #     begin
   #       raise('Boom 0')
@@ -237,10 +237,10 @@ class Exception
   # An overriding method must be tolerant of passed keyword arguments, which may
   # include (but may not be limited to):
   #
-  # *   `:highlight`.
-  # *   `:did_you_mean`.
-  # *   `:error_highlight`.
-  # *   `:syntax_suggest`.
+  # *   <code>:highlight</code>.
+  # *   <code>:did_you_mean</code>.
+  # *   <code>:error_highlight</code>.
+  # *   <code>:syntax_suggest</code>.
   #
   # An overriding method should also be careful with ANSI code enhancements; see
   # [Messages](rdoc-ref:exceptions.md@Messages).
@@ -444,10 +444,10 @@ class Exception
   #     message.
   # *   Includes the [backtrace](rdoc-ref:exceptions.md@Backtraces):
   #
-  #     *   If the value of keyword `order` is `:top` (the default), lists the
-  #         error message and the innermost backtrace entry first.
-  #     *   If the value of keyword `order` is `:bottom`, lists the error message
-  #         the innermost entry last.
+  #     *   If the value of keyword `order` is <code>:top</code> (the default),
+  #         lists the error message and the innermost backtrace entry first.
+  #     *   If the value of keyword `order` is <code>:bottom</code>, lists the
+  #         error message the innermost entry last.
   #
   # Example:
   #

data/core/fiber.rbs

@@ -57,16 +57,16 @@
 #
 # ## Non-blocking Fibers
 #
-# The concept of *non-blocking fiber* was introduced in Ruby 3.0. A non-blocking
-# fiber, when reaching an operation that would normally block the fiber (like
-# `sleep`, or wait for another process or I/O) will yield control to other
-# fibers and allow the *scheduler* to handle blocking and waking up (resuming)
-# this fiber when it can proceed.
+# The concept of <em>non-blocking fiber</em> was introduced in Ruby 3.0. A
+# non-blocking fiber, when reaching an operation that would normally block the
+# fiber (like `sleep`, or wait for another process or I/O) will yield control to
+# other fibers and allow the *scheduler* to handle blocking and waking up
+# (resuming) this fiber when it can proceed.
 #
 # For a Fiber to behave as non-blocking, it need to be created in Fiber.new with
-# `blocking: false` (which is the default), and Fiber.scheduler should be set
-# with Fiber.set_scheduler. If Fiber.scheduler is not set in the current thread,
-# blocking and non-blocking fibers' behavior is identical.
+# <code>blocking: false</code> (which is the default), and Fiber.scheduler
+# should be set with Fiber.set_scheduler. If Fiber.scheduler is not set in the
+# current thread, blocking and non-blocking fibers' behavior is identical.
 #
 # Ruby doesn't provide a scheduler class: it is expected to be implemented by
 # the user and correspond to Fiber::Scheduler.
@@ -102,12 +102,23 @@ class Fiber < Object
   #
   def self.[]=: [A] (Symbol, A) -> A
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber.blocking{|fiber| ...} -> result
+  # -->
+  # Forces the fiber to be blocking for the duration of the block. Returns the
+  # result of the block.
+  #
+  # See the "Non-blocking fibers" section in class docs for details.
+  #
+  def self.blocking: [T] () { (Fiber) -> T } -> T
+
   # <!--
   #   rdoc-file=cont.c
   #   - Fiber.blocking? -> false or 1
   # -->
   # Returns `false` if the current fiber is non-blocking. Fiber is non-blocking if
-  # it was created via passing `blocking: false` to Fiber.new, or via
+  # it was created via passing <code>blocking: false</code> to Fiber.new, or via
   # Fiber.schedule.
   #
   # If the current Fiber is blocking, the method returns 1. Future developments
@@ -165,18 +176,18 @@ class Fiber < Object
   #     ...1 sec pause here...
   #     I slept well
   #
-  # ...e.g. on the first blocking operation inside the Fiber (`sleep(1)`), the
-  # control is yielded to the outside code (main fiber), and *at the end of that
-  # execution*, the scheduler takes care of properly resuming all the blocked
-  # fibers.
+  # ...e.g. on the first blocking operation inside the Fiber
+  # (<code>sleep(1)</code>), the control is yielded to the outside code (main
+  # fiber), and *at the end of that execution*, the scheduler takes care of
+  # properly resuming all the blocked fibers.
   #
   # Note that the behavior described above is how the method is *expected* to
   # behave, actual behavior is up to the current scheduler's implementation of
   # Fiber::Scheduler#fiber method. Ruby doesn't enforce this method to behave in
   # any particular way.
   #
-  # If the scheduler is not set, the method raises `RuntimeError (No scheduler is
-  # available!)`.
+  # If the scheduler is not set, the method raises <code>RuntimeError (No
+  # scheduler is available!)</code>.
   #
   def self.schedule: () { () -> void } -> Fiber
 
@@ -197,11 +208,11 @@ class Fiber < Object
   #   - Fiber.set_scheduler(scheduler) -> scheduler
   # -->
   # Sets the Fiber scheduler for the current thread. If the scheduler is set,
-  # non-blocking fibers (created by Fiber.new with `blocking: false`, or by
-  # Fiber.schedule) call that scheduler's hook methods on potentially blocking
-  # operations, and the current thread will call scheduler's `close` method on
-  # finalization (allowing the scheduler to properly manage all non-finished
-  # fibers).
+  # non-blocking fibers (created by Fiber.new with <code>blocking: false</code>,
+  # or by Fiber.schedule) call that scheduler's hook methods on potentially
+  # blocking operations, and the current thread will call scheduler's `close`
+  # method on finalization (allowing the scheduler to properly manage all
+  # non-finished fibers).
   #
   # `scheduler` can be an object of any class corresponding to Fiber::Scheduler.
   # Its implementation is up to the user.
@@ -240,13 +251,13 @@ class Fiber < Object
   #     f.resume          # prints: current: nil
   #     # ... and so on ...
   #
-  # If `blocking: false` is passed to `Fiber.new`, *and* current thread has a
-  # Fiber.scheduler defined, the Fiber becomes non-blocking (see "Non-blocking
-  # Fibers" section in class docs).
+  # If <code>blocking: false</code> is passed to <code>Fiber.new</code>, *and*
+  # current thread has a Fiber.scheduler defined, the Fiber becomes non-blocking
+  # (see "Non-blocking Fibers" section in class docs).
   #
   # If the `storage` is unspecified, the default is to inherit a copy of the
-  # storage from the current fiber. This is the same as specifying `storage:
-  # true`.
+  # storage from the current fiber. This is the same as specifying <code>storage:
+  # true</code>.
   #
   #     Fiber[:x] = 1
   #     Fiber.new do
@@ -266,8 +277,8 @@ class Fiber < Object
   # Otherwise, the given `storage` is used as the new fiber's storage, and it must
   # be an instance of Hash.
   #
-  # Explicitly using `storage: true` is currently experimental and may change in
-  # the future.
+  # Explicitly using <code>storage: true</code> is currently experimental and may
+  # change in the future.
   #
   def initialize: (?blocking: boolish, ?storage: true | Hash[interned, untyped] | nil) { (?) -> void } -> void
 
@@ -353,8 +364,8 @@ class Fiber < Object
   #   - fiber.blocking? -> true or false
   # -->
   # Returns `true` if `fiber` is blocking and `false` otherwise. Fiber is
-  # non-blocking if it was created via passing `blocking: false` to Fiber.new, or
-  # via Fiber.schedule.
+  # non-blocking if it was created via passing <code>blocking: false</code> to
+  # Fiber.new, or via Fiber.schedule.
   #
   # Note that, even if the method returns `false`, the fiber behaves differently
   # only if Fiber.scheduler is set in the current thread.
@@ -378,9 +389,9 @@ class Fiber < Object
   # the given fiber and no other fiber, returning `nil` to another fiber if that
   # fiber was calling #resume or #transfer.
   #
-  # `Fiber#kill` only interrupts another fiber when it is in Fiber.yield. If
-  # called on the current fiber then it raises that exception at the `Fiber#kill`
-  # call site.
+  # <code>Fiber#kill</code> only interrupts another fiber when it is in
+  # Fiber.yield. If called on the current fiber then it raises that exception at
+  # the <code>Fiber#kill</code> call site.
   #
   # If the fiber has not been started, transition directly to the terminated
   # state.
@@ -396,8 +407,8 @@ class Fiber < Object
   #   - raise(exception, message = exception.to_s, backtrace = nil, cause: $!)
   #   - raise(message = nil, cause: $!)
   # -->
-  # Raises an exception in the fiber at the point at which the last `Fiber.yield`
-  # was called.
+  # Raises an exception in the fiber at the point at which the last
+  # <code>Fiber.yield</code> was called.
   #
   #     f = Fiber.new {
   #       puts "Before the yield"
@@ -461,8 +472,8 @@ class Fiber < Object
   # important fiber-storage state. You should mostly prefer to assign specific
   # keys in the storage using Fiber::[]=.
   #
-  # You can also use `Fiber.new(storage: nil)` to create a fiber with an empty
-  # storage.
+  # You can also use <code>Fiber.new(storage: nil)</code> to create a fiber with
+  # an empty storage.
   #
   # Example:
   #