rbs 2.0.0 → 2.1.0

data/core/exception.rbs

@@ -1,195 +1,269 @@
-# Descendants of class [Exception](Exception) are used
-# to communicate between
-# [Kernel\#raise](https://ruby-doc.org/core-2.6.3/Kernel.html#method-i-raise)
-# and `rescue` statements in `begin ... end` blocks.
-# [Exception](Exception) objects carry information
-# about the exception – its type (the exception’s class name), an optional
-# descriptive string, and optional traceback information.
-# [Exception](Exception) subclasses may add additional
-# information like
-# [NameError\#name](https://ruby-doc.org/core-2.6.3/NameError.html#method-i-name)
-# .
-#
-# Programs may make subclasses of
-# [Exception](Exception), typically of
-# [StandardError](https://ruby-doc.org/core-2.6.3/StandardError.html) or
-# [RuntimeError](https://ruby-doc.org/core-2.6.3/RuntimeError.html), to
-# provide custom classes and add additional information. See the subclass
-# list below for defaults for `raise` and `rescue` .
-#
-# When an exception has been raised but not yet handled (in `rescue`,
-# `ensure`, `at_exit` and `END` blocks) the global variable `$!` will
-# contain the current exception and `$@` contains the current exception’s
-# backtrace.
-#
-# It is recommended that a library should have one subclass of
-# [StandardError](https://ruby-doc.org/core-2.6.3/StandardError.html) or
-# [RuntimeError](https://ruby-doc.org/core-2.6.3/RuntimeError.html) and
-# have specific exception types inherit from it. This allows the user to
-# rescue a generic exception type to catch all exceptions the library may
-# raise even if future versions of the library add new exception
-# subclasses.
+# <!-- rdoc-file=error.c -->
+# Class Exception and its subclasses are used to communicate between
+# Kernel#raise and `rescue` statements in `begin ... end` blocks.
 #
-# For example:
-#
-# ```ruby
-# class MyLibrary
-#   class Error < RuntimeError
-#   end
-#
-#   class WidgetError < Error
-#   end
-#
-#   class FrobError < Error
-#   end
-#
-# end
-# ```
-#
-# To handle both WidgetError and FrobError the library user can rescue
-# MyLibrary::Error.
-#
-# The built-in subclasses of [Exception](Exception)
-# are:
-#
-#   - [NoMemoryError](https://ruby-doc.org/core-2.6.3/NoMemoryError.html)
+# An Exception object carries information about an exception:
+# *   Its type (the exception's class).
+# *   An optional descriptive message.
+# *   Optional backtrace information.
 #
-#   - [ScriptError](https://ruby-doc.org/core-2.6.3/ScriptError.html)
 #
-#       - [LoadError](https://ruby-doc.org/core-2.6.3/LoadError.html)
+# Some built-in subclasses of Exception have additional methods: e.g.,
+# NameError#name.
 #
-#       - [NotImplementedError](https://ruby-doc.org/core-2.6.3/NotImplementedError.html)
+# ## Defaults
 #
-#       - [SyntaxError](https://ruby-doc.org/core-2.6.3/SyntaxError.html)
+# Two Ruby statements have default exception classes:
+# *   `raise`: defaults to RuntimeError.
+# *   `rescue`: defaults to StandardError.
 #
-#   - [SecurityError](https://ruby-doc.org/core-2.6.3/SecurityError.html)
 #
-#   - [SignalException](https://ruby-doc.org/core-2.6.3/SignalException.html)
+# ## Global Variables
 #
-#       - [Interrupt](https://ruby-doc.org/core-2.6.3/Interrupt.html)
+# When an exception has been raised but not yet handled (in `rescue`, `ensure`,
+# `at_exit` and `END` blocks), two global variables are set:
+# *   `$!` contains the current exception.
+# *   `$@` contains its backtrace.
 #
-#   - [StandardError](https://ruby-doc.org/core-2.6.3/StandardError.html)
-#     -- default for `rescue`
 #
-#       - [ArgumentError](https://ruby-doc.org/core-2.6.3/ArgumentError.html)
+# ## Custom Exceptions
 #
-#           - [UncaughtThrowError](https://ruby-doc.org/core-2.6.3/UncaughtThrowError.html)
+# To provide additional or alternate information, a program may create custom
+# exception classes that derive from the built-in exception classes.
 #
-#       - [EncodingError](https://ruby-doc.org/core-2.6.3/EncodingError.html)
+# A good practice is for a library to create a single "generic" exception class
+# (typically a subclass of StandardError or RuntimeError) and have its other
+# exception classes derive from that class. This allows the user to rescue the
+# generic exception, thus catching all exceptions the library may raise even if
+# future versions of the library add new exception subclasses.
 #
-#       - [FiberError](https://ruby-doc.org/core-2.6.3/FiberError.html)
-#
-#       - [IOError](https://ruby-doc.org/core-2.6.3/IOError.html)
+# For example:
 #
-#           - [EOFError](https://ruby-doc.org/core-2.6.3/EOFError.html)
+#     class MyLibrary
+#       class Error < ::StandardError
+#       end
 #
-#       - [IndexError](https://ruby-doc.org/core-2.6.3/IndexError.html)
+#       class WidgetError < Error
+#       end
 #
-#           - [KeyError](https://ruby-doc.org/core-2.6.3/KeyError.html)
+#       class FrobError < Error
+#       end
 #
-#           - [StopIteration](https://ruby-doc.org/core-2.6.3/StopIteration.html)
+#     end
 #
-#       - [LocalJumpError](https://ruby-doc.org/core-2.6.3/LocalJumpError.html)
+# To handle both MyLibrary::WidgetError and MyLibrary::FrobError the library
+# user can rescue MyLibrary::Error.
 #
-#       - [NameError](https://ruby-doc.org/core-2.6.3/NameError.html)
+# ## Built-In Exception Classes
 #
-#           - [NoMethodError](https://ruby-doc.org/core-2.6.3/NoMethodError.html)
+# The built-in subclasses of Exception are:
 #
-#       - [RangeError](https://ruby-doc.org/core-2.6.3/RangeError.html)
+# *   NoMemoryError
+# *   ScriptError
+#     *   LoadError
+#     *   NotImplementedError
+#     *   SyntaxError
 #
-#           - [FloatDomainError](https://ruby-doc.org/core-2.6.3/FloatDomainError.html)
+# *   SecurityError
+# *   SignalException
+#     *   Interrupt
 #
-#       - [RegexpError](https://ruby-doc.org/core-2.6.3/RegexpError.html)
+# *   StandardError
+#     *   ArgumentError
+#         *   UncaughtThrowError
 #
-#       - [RuntimeError](https://ruby-doc.org/core-2.6.3/RuntimeError.html)
-#         -- default for `raise`
+#     *   EncodingError
+#     *   FiberError
+#     *   IOError
+#         *   EOFError
 #
-#           - [FrozenError](https://ruby-doc.org/core-2.6.3/FrozenError.html)
+#     *   IndexError
+#         *   KeyError
+#         *   StopIteration
+#             *   ClosedQueueError
 #
-#       - [SystemCallError](https://ruby-doc.org/core-2.6.3/SystemCallError.html)
 #
-#           - Errno::\*
+#     *   LocalJumpError
+#     *   NameError
+#         *   NoMethodError
 #
-#       - [ThreadError](https://ruby-doc.org/core-2.6.3/ThreadError.html)
+#     *   RangeError
+#         *   FloatDomainError
 #
-#       - [TypeError](https://ruby-doc.org/core-2.6.3/TypeError.html)
+#     *   RegexpError
+#     *   RuntimeError
+#         *   FrozenError
 #
-#       - [ZeroDivisionError](https://ruby-doc.org/core-2.6.3/ZeroDivisionError.html)
+#     *   SystemCallError
+#         *   Errno::*
 #
-#   - [SystemExit](https://ruby-doc.org/core-2.6.3/SystemExit.html)
+#     *   ThreadError
+#     *   TypeError
+#     *   ZeroDivisionError
 #
-#   - [SystemStackError](https://ruby-doc.org/core-2.6.3/SystemStackError.html)
+# *   SystemExit
+# *   SystemStackError
+# *   fatal
 #
-#   - fatal – impossible to rescue
 class Exception < Object
+  # <!--
+  #   rdoc-file=error.c
+  #   - Exception.to_tty?   ->  true or false
+  # -->
+  # Returns `true` if exception messages will be sent to a tty.
+  #
   def self.to_tty?: () -> bool
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - exc.exception([string])  ->  an_exception or exc
+  # -->
+  # With no argument, or if the argument is the same as the receiver, return the
+  # receiver. Otherwise, create a new exception object of the same class as the
+  # receiver, but with a message equal to `string.to_str`.
+  #
   def self.exception: (?String msg) -> Exception
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - exc == obj   -> true or false
+  # -->
+  # Equality---If *obj* is not an Exception, returns `false`. Otherwise, returns
+  # `true` if *exc* and *obj* share same class, messages, and backtrace.
+  #
   def ==: (untyped arg0) -> bool
 
-  # Returns any backtrace associated with the exception. The backtrace is an
-  # array of strings, each containing either “filename:lineNo: in \`method”‘
-  # or “filename:lineNo.”
-  #
-  # ```ruby
-  # def a
-  #   raise "boom"
-  # end
-  #
-  # def b
-  #   a()
-  # end
-  #
-  # begin
-  #   b()
-  # rescue => detail
-  #   print detail.backtrace.join("\n")
-  # end
-  # ```
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.backtrace    -> array or nil
+  # -->
+  # Returns any backtrace associated with the exception. The backtrace is an array
+  # of strings, each containing either ``filename:lineNo: in `method''' or
+  # ``filename:lineNo.''
+  #
+  #     def a
+  #       raise "boom"
+  #     end
+  #
+  #     def b
+  #       a()
+  #     end
+  #
+  #     begin
+  #       b()
+  #     rescue => detail
+  #       print detail.backtrace.join("\n")
+  #     end
   #
   # *produces:*
   #
   #     prog.rb:2:in `a'
   #     prog.rb:6:in `b'
   #     prog.rb:10
+  #
+  # In the case no backtrace has been set, `nil` is returned
+  #
+  #     ex = StandardError.new
+  #     ex.backtrace
+  #     #=> nil
+  #
   def backtrace: () -> ::Array[String]?
 
-  # Returns any backtrace associated with the exception. This method is
-  # similar to
-  # [\#backtrace](Exception.downloaded.ruby_doc#method-i-backtrace), but
-  # the backtrace is an array of
-  # [Thread::Backtrace::Location](https://ruby-doc.org/core-2.6.3/Thread/Backtrace/Location.html)
-  # .
-  #
-  # Now, this method is not affected by
-  # [\#set\_backtrace](Exception.downloaded.ruby_doc#method-i-set_backtrace)
-  # .
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.backtrace_locations    -> array or nil
+  # -->
+  # Returns any backtrace associated with the exception. This method is similar to
+  # Exception#backtrace, but the backtrace is an array of
+  # Thread::Backtrace::Location.
+  #
+  # This method is not affected by Exception#set_backtrace().
+  #
   def backtrace_locations: () -> ::Array[Thread::Backtrace::Location]?
 
-  # Returns the previous exception ($\!) at the time this exception was
-  # raised. This is useful for wrapping exceptions and retaining the
-  # original exception information.
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.cause   -> an_exception or nil
+  # -->
+  # Returns the previous exception ($!) at the time this exception was raised.
+  # This is useful for wrapping exceptions and retaining the original exception
+  # information.
+  #
   def cause: () -> Exception?
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - exc.exception([string])  ->  an_exception or exc
+  # -->
+  # With no argument, or if the argument is the same as the receiver, return the
+  # receiver. Otherwise, create a new exception object of the same class as the
+  # receiver, but with a message equal to `string.to_str`.
+  #
   def exception: () -> self
                | (String arg0) -> Exception
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - Exception.new(msg = nil)        ->  exception
+  #   - Exception.exception(msg = nil)  ->  exception
+  # -->
+  # Construct a new Exception object, optionally passing in a message.
+  #
   def initialize: (?String arg0) -> void
 
-  # Return this exception’s class name and message.
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.inspect   -> string
+  # -->
+  # Return this exception's class name and message.
+  #
   def inspect: () -> String
 
-  # Returns the result of invoking `exception.to_s` . Normally this returns
-  # the exception’s message or name.
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.message   ->  string
+  # -->
+  # Returns the result of invoking `exception.to_s`. Normally this returns the
+  # exception's message or name.
+  #
   def message: () -> String
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - exc.set_backtrace(backtrace)   ->  array
+  # -->
+  # Sets the backtrace information associated with `exc`. The `backtrace` must be
+  # an array of String objects or a single String in the format described in
+  # Exception#backtrace.
+  #
   def set_backtrace: (String | ::Array[String] arg0) -> ::Array[String]
                    | (nil) -> nil
 
-  # Returns exception’s message (or the name of the exception if no message
-  # is set).
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.to_s   ->  string
+  # -->
+  # Returns exception's message (or the name of the exception if no message is
+  # set).
+  #
   def to_s: () -> String
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.full_message(highlight: bool, order: [:top or :bottom]) ->  string
+  # -->
+  # Returns formatted string of *exception*. The returned string is formatted
+  # using the same format that Ruby uses when printing an uncaught exceptions to
+  # stderr.
+  #
+  # If *highlight* is `true` the default error handler will send the messages to a
+  # tty.
+  #
+  # *order* must be either of `:top` or `:bottom`, and places the error message
+  # and the innermost backtrace come at the top or the bottom.
+  #
+  # The default values of these options depend on `$stderr` and its `tty?` at the
+  # timing of a call.
+  #
   def full_message: (?highlight: bool, ?order: :top | :bottom) -> String
 end

data/core/false_class.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=object.c -->
 # The global value `false` is the only instance of class FalseClass and
 # represents a logically false value in boolean expressions. The class provides
 # operators allowing `false` to participate correctly in logical expressions.
@@ -7,11 +8,20 @@ class FalseClass
 
   def !: () -> true
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - false & obj   -> false
+  #   - nil & obj     -> false
+  # -->
   # And---Returns `false`. *obj* is always evaluated as it is the argument to a
   # method call---there is no short-circuit evaluation in this case.
   #
   def &: (untyped obj) -> false
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj === other   -> true or false
+  # -->
   # Case Equality -- For class Object, effectively the same as calling `#==`, but
   # typically overridden by descendants to provide meaningful semantics in `case`
   # statements.
@@ -19,6 +29,11 @@ class FalseClass
   def ===: (false) -> true
          | (untyped obj) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - false ^ obj    -> true or false
+  #   - nil   ^ obj    -> true or false
+  # -->
   # Exclusive Or---If *obj* is `nil` or `false`, returns `false`; otherwise,
   # returns `true`.
   #
@@ -26,12 +41,24 @@ class FalseClass
        | (false) -> false
        | (untyped obj) -> true
 
+  # <!-- rdoc-file=object.c -->
+  # The string representation of `false` is "false".
+  #
   alias inspect to_s
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - false.to_s   ->  "false"
+  # -->
   # The string representation of `false` is "false".
   #
   def to_s: () -> "false"
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - false | obj   ->   true or false
+  #   - nil   | obj   ->   true or false
+  # -->
   # Or---Returns `false` if *obj* is `nil` or `false`; `true` otherwise.
   #
   def |: (nil) -> false

data/core/fiber.rbs

@@ -1,35 +1,33 @@
-# Fibers are primitives for implementing light weight cooperative
-# concurrency in Ruby. Basically they are a means of creating code blocks
-# that can be paused and resumed, much like threads. The main difference
-# is that they are never preempted and that the scheduling must be done by
-# the programmer and not the VM.
+# <!-- rdoc-file=cont.c -->
+# Fibers are primitives for implementing light weight cooperative concurrency in
+# Ruby. Basically they are a means of creating code blocks that can be paused
+# and resumed, much like threads. The main difference is that they are never
+# preempted and that the scheduling must be done by the programmer and not the
+# VM.
 #
-# As opposed to other stackless light weight concurrency models, each
-# fiber comes with a stack. This enables the fiber to be paused from
-# deeply nested function calls within the fiber block. See the ruby(1)
-# manpage to configure the size of the fiber stack(s).
+# As opposed to other stackless light weight concurrency models, each fiber
+# comes with a stack.  This enables the fiber to be paused from deeply nested
+# function calls within the fiber block.  See the ruby(1) manpage to configure
+# the size of the fiber stack(s).
 #
 # When a fiber is created it will not run automatically. Rather it must be
-# explicitly asked to run using the `Fiber#resume` method. The code
-# running inside the fiber can give up control by calling `Fiber.yield` in
-# which case it yields control back to caller (the caller of the
-# `Fiber#resume` ).
+# explicitly asked to run using the Fiber#resume method. The code running inside
+# the fiber can give up control by calling Fiber.yield in which case it yields
+# control back to caller (the caller of the Fiber#resume).
 #
-# Upon yielding or termination the [Fiber](Fiber)
-# returns the value of the last executed expression
+# Upon yielding or termination the Fiber returns the value of the last executed
+# expression
 #
 # For instance:
 #
-# ```ruby
-# fiber = Fiber.new do
-#   Fiber.yield 1
-#   2
-# end
+#     fiber = Fiber.new do
+#       Fiber.yield 1
+#       2
+#     end
 #
-# puts fiber.resume
-# puts fiber.resume
-# puts fiber.resume
-# ```
+#     puts fiber.resume
+#     puts fiber.resume
+#     puts fiber.resume
 #
 # *produces*
 #
@@ -37,35 +35,118 @@
 #     2
 #     FiberError: dead fiber called
 #
-# The `Fiber#resume` method accepts an arbitrary number of parameters, if
-# it is the first call to `resume` then they will be passed as block
-# arguments. Otherwise they will be the return value of the call to
-# `Fiber.yield`
+# The Fiber#resume method accepts an arbitrary number of parameters, if it is
+# the first call to #resume then they will be passed as block arguments.
+# Otherwise they will be the return value of the call to Fiber.yield
 #
 # Example:
 #
-# ```ruby
-# fiber = Fiber.new do |first|
-#   second = Fiber.yield first + 2
-# end
+#     fiber = Fiber.new do |first|
+#       second = Fiber.yield first + 2
+#     end
 #
-# puts fiber.resume 10
-# puts fiber.resume 14
-# puts fiber.resume 18
-# ```
+#     puts fiber.resume 10
+#     puts fiber.resume 1_000_000
+#     puts fiber.resume "The fiber will be dead before I can cause trouble"
 #
 # *produces*
 #
 #     12
-#     14
+#     1000000
 #     FiberError: dead fiber called
+#
+# ## Non-blocking Fibers
+#
+# The concept of *non-blocking fiber* was introduced in Ruby 3.0. A non-blocking
+# fiber, when reaching a 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.
+#
+# Ruby doesn't provide a scheduler class: it is expected to be implemented by
+# the user and correspond to Fiber::SchedulerInterface.
+#
+# There is also Fiber.schedule method, which is expected to immediately perform
+# the given block in a non-blocking manner. Its actual implementation is up to
+# the scheduler.
+#
 class Fiber < Object
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber.yield(args, ...) -> obj
+  # -->
+  # Yields control back to the context that resumed the fiber, passing along any
+  # arguments that were passed to it. The fiber will resume processing at this
+  # point when #resume is called next. Any arguments passed to the next #resume
+  # will be the value that this Fiber.yield expression evaluates to.
+  #
   def self.yield: (*untyped args) -> untyped
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber.new(blocking: false) { |*args| ... } -> fiber
+  # -->
+  # Creates new Fiber. Initially, the fiber is not running and can be resumed with
+  # #resume. Arguments to the first #resume call will be passed to the block:
+  #
+  #     f = Fiber.new do |initial|
+  #        current = initial
+  #        loop do
+  #          puts "current: #{current.inspect}"
+  #          current = Fiber.yield
+  #        end
+  #     end
+  #     f.resume(100)     # prints: current: 100
+  #     f.resume(1, 2, 3) # prints: current: [1, 2, 3]
+  #     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).
+  #
   def initialize: () { () -> untyped } -> void
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.resume(args, ...) -> obj
+  # -->
+  # Resumes the fiber from the point at which the last Fiber.yield was called, or
+  # starts running it if it is the first call to #resume. Arguments passed to
+  # resume will be the value of the Fiber.yield expression or will be passed as
+  # block parameters to the fiber's block if this is the first #resume.
+  #
+  # Alternatively, when resume is called it evaluates to the arguments passed to
+  # the next Fiber.yield statement inside the fiber's block or to the block value
+  # if it runs to completion without any Fiber.yield
+  #
   def resume: (*untyped args) -> untyped
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.raise                                 -> obj
+  #   - fiber.raise(string)                         -> obj
+  #   - fiber.raise(exception [, string [, array]]) -> obj
+  # -->
+  # Raises an exception in the fiber at the point at which the last `Fiber.yield`
+  # was called. If the fiber has not been started or has already run to
+  # completion, raises `FiberError`. If the fiber is yielding, it is resumed. If
+  # it is transferring, it is transferred into. But if it is resuming, raises
+  # `FiberError`.
+  #
+  # With no arguments, raises a `RuntimeError`. With a single `String` argument,
+  # raises a `RuntimeError` with the string as a message.  Otherwise, the first
+  # parameter should be the name of an `Exception` class (or an object that
+  # returns an `Exception` object when sent an `exception` message). The optional
+  # second parameter sets the message associated with the exception, and the third
+  # parameter is an array of callback information. Exceptions are caught by the
+  # `rescue` clause of `begin...end` blocks.
+  #
   def raise: () -> untyped
            | (string message) -> untyped
            | (_Exception exception, ?string message, ?Array[String] backtrace) -> untyped

data/core/fiber_error.rbs

@@ -1,12 +1,11 @@
-# Raised when an invalid operation is attempted on a
-# [Fiber](https://ruby-doc.org/core-2.6.3/Fiber.html), in particular when
-# attempting to call/resume a dead fiber, attempting to yield from the
-# root fiber, or calling a fiber across threads.
+# <!-- rdoc-file=cont.c -->
+# Raised when an invalid operation is attempted on a Fiber, in particular when
+# attempting to call/resume a dead fiber, attempting to yield from the root
+# fiber, or calling a fiber across threads.
+#
+#     fiber = Fiber.new{}
+#     fiber.resume #=> nil
+#     fiber.resume #=> FiberError: dead fiber called
 #
-# ```ruby
-# fiber = Fiber.new{}
-# fiber.resume #=> nil
-# fiber.resume #=> FiberError: dead fiber called
-# ```
 class FiberError < StandardError
 end