rbs 3.7.0 → 3.8.0.pre.1

data/core/struct.rbs

@@ -46,7 +46,6 @@
 # *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
 #     provides dozens of additional methods.
 #
-#
 # See also Data, which is a somewhat similar, but stricter concept for defining
 # immutable value objects.
 #
@@ -61,17 +60,14 @@
 # *   [Iterating](rdoc-ref:Struct@Methods+for+Iterating)
 # *   [Converting](rdoc-ref:Struct@Methods+for+Converting)
 #
-#
 # ### Methods for Creating a Struct Subclass
 #
 # *   ::new: Returns a new subclass of Struct.
 #
-#
 # ### Methods for Querying
 #
 # *   #hash: Returns the integer hash code.
-# *   #length, #size: Returns the number of members.
-#
+# *   #size (aliased as #length): Returns the number of members.
 #
 # ### Methods for Comparing
 #
@@ -80,36 +76,32 @@
 # *   #eql?: Returns whether a given object is equal to `self`, using `eql?` to
 #     compare member values.
 #
-#
 # ### Methods for Fetching
 #
 # *   #[]: Returns the value associated with a given member name.
-# *   #to_a, #values, #deconstruct: Returns the member values in `self` as an
-#     array.
+# *   #to_a (aliased as #values, #deconstruct): Returns the member values in
+#     `self` as an array.
 # *   #deconstruct_keys: Returns a hash of the name/value pairs for given member
 #     names.
 # *   #dig: Returns the object in nested objects that is specified by a given
 #     member name and additional arguments.
 # *   #members: Returns an array of the member names.
-# *   #select, #filter: Returns an array of member values from `self`, as
-#     selected by the given block.
+# *   #select (aliased as #filter): Returns an array of member values from
+#     `self`, as selected by the given block.
 # *   #values_at: Returns an array containing values for given member names.
 #
-#
 # ### Methods for Assigning
 #
 # *   #[]=: Assigns a given value to a given member name.
 #
-#
 # ### Methods for Iterating
 #
 # *   #each: Calls a given block with each member name.
 # *   #each_pair: Calls a given block with each member name/value pair.
 #
-#
 # ### Methods for Converting
 #
-# *   #inspect, #to_s: Returns a string representation of `self`.
+# *   #inspect (aliased as #to_s): Returns a string representation of `self`.
 # *   #to_h: Returns a hash of the member name/value pairs in `self`.
 #
 class Struct[Elem]
@@ -133,7 +125,6 @@ class Struct[Elem]
   # *   May have members as given by `member_names`.
   # *   May have initialization via ordinary arguments, or via keyword arguments
   #
-  #
   # The new subclass has its own method `::new`; thus:
   #
   #     Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
@@ -215,7 +206,6 @@ class Struct[Elem]
   #
   #         Foo.members # => [:foo, :bar]
   #
-  #
   # **Keyword Argument**
   #
   # By default, the arguments for initializing an instance of the new subclass can
@@ -285,7 +275,6 @@ class Struct[Elem]
   # *   `other.class == self.class`.
   # *   For each member name `name`, `other.name == self.name`.
   #
-  #
   # Examples:
   #
   #     Customer = Struct.new(:name, :address, :zip)
@@ -315,7 +304,6 @@ class Struct[Elem]
   #         joe_jr[:name] = 'Joe Smith, Jr.'
   #         joe_jr.eql?(joe) # => false
   #
-  #
   # Related: Object#==.
   #
   def eql?: (untyped other) -> bool

data/core/symbol.rbs

@@ -1,15 +1,14 @@
 # <!-- rdoc-file=string.c -->
-# Symbol objects represent named identifiers inside the Ruby interpreter.
+# A `Symbol` object represents a named identifier inside the Ruby interpreter.
 #
-# You can create a Symbol object explicitly with:
+# You can create a `Symbol` object explicitly with:
 #
 # *   A [symbol literal](rdoc-ref:syntax/literals.rdoc@Symbol+Literals).
 #
-#
-# The same Symbol object will be created for a given name or string for the
+# The same `Symbol` object will be created for a given name or string for the
 # duration of a program's execution, regardless of the context or meaning of
 # that name. Thus if `Fred` is a constant in one context, a method in another,
-# and a class in a third, the Symbol `:Fred` will be the same object in all
+# and a class in a third, the `Symbol` `:Fred` will be the same object in all
 # three contexts.
 #
 #     module One
@@ -52,24 +51,22 @@
 #     local_variables
 #     # => [:seven]
 #
-# Symbol objects are different from String objects in that Symbol objects
-# represent identifiers, while String objects represent text or data.
+# A `Symbol` object differs from a String object in that a `Symbol` object
+# represents an identifier, while a String object represents text or data.
 #
 # ## What's Here
 #
-# First, what's elsewhere. Class Symbol:
+# First, what's elsewhere. Class `Symbol`:
 #
 # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
 # *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
-#
-# Here, class Symbol provides methods that are useful for:
+# Here, class `Symbol` provides methods that are useful for:
 #
 # *   [Querying](rdoc-ref:Symbol@Methods+for+Querying)
 # *   [Comparing](rdoc-ref:Symbol@Methods+for+Comparing)
 # *   [Converting](rdoc-ref:Symbol@Methods+for+Converting)
 #
-#
 # ### Methods for Querying
 #
 # *   ::all_symbols: Returns an array of the symbols currently in Ruby's symbol
@@ -90,7 +87,6 @@
 # *   #start_with?: Returns `true` if symbol starts with any of the given
 #     strings.
 #
-#
 # ### Methods for Comparing
 #
 # *   #<=>: Returns -1, 0, or 1 as a given symbol is smaller than, equal to, or
@@ -102,7 +98,6 @@
 # *   #casecmp?: Returns `true` if symbol is equal to a given symbol after
 #     Unicode case folding; `false` otherwise.
 #
-#
 # ### Methods for Converting
 #
 # *   #capitalize: Returns symbol with the first character upcased and all other
@@ -310,12 +305,10 @@ class Symbol
   #
   def end_with?: (*string suffixes) -> bool
 
-  # <!-- rdoc-file=string.c -->
-  # Returns a string representation of `self` (not including the leading colon):
-  #
-  #     :foo.to_s # => "foo"
-  #
-  # Related: Symbol#inspect, Symbol#name.
+  # <!--
+  #   rdoc-file=symbol.rb
+  #   - id2name()
+  # -->
   #
   alias id2name to_s
 
@@ -375,7 +368,7 @@ class Symbol
   def next: () -> Symbol
 
   # <!--
-  #   rdoc-file=string.c
+  #   rdoc-file=symbol.rb
   #   - name -> string
   # -->
   # Returns a frozen string representation of `self` (not including the leading
@@ -446,7 +439,7 @@ class Symbol
   def to_proc: () -> Proc
 
   # <!--
-  #   rdoc-file=string.c
+  #   rdoc-file=symbol.rb
   #   - to_s -> string
   # -->
   # Returns a string representation of `self` (not including the leading colon):

data/core/thread.rbs

@@ -485,7 +485,6 @@ class Thread < Object
   # *   On Windows it is the thread identifier returned by GetThreadId().
   # *   On other platforms, it raises NotImplementedError.
   #
-  #
   # NOTE: If the thread is not associated yet or already deassociated with a
   # native thread, it returns *nil*. If the Ruby implementation uses M:N thread
   # model, the ID may change depending on the timing.
@@ -614,12 +613,16 @@ class Thread < Object
   #
   # `"sleep"`
   # :   Returned if this thread is sleeping or waiting on I/O
+  #
   # `"run"`
   # :   When this thread is executing
+  #
   # `"aborting"`
   # :   If this thread is aborting
+  #
   # `false`
   # :   When this thread is terminated normally
+  #
   # `nil`
   # :   If terminated with an exception.
   #
@@ -819,7 +822,7 @@ class Thread < Object
 
   # <!--
   #   rdoc-file=vm_backtrace.c
-  #   - Thread.each_caller_location{ |loc| ... } -> nil
+  #   - Thread.each_caller_location(...) { |loc| ... } -> nil
   # -->
   # Yields each frame of the current execution stack as a backtrace location
   # object.
@@ -873,8 +876,10 @@ class Thread < Object
   #
   # `:immediate`
   # :   Invoke interrupts immediately.
+  #
   # `:on_blocking`
   # :   Invoke interrupts while *BlockingOperation*.
+  #
   # `:never`
   # :   Never invoke all interrupts.
   #
@@ -923,30 +928,6 @@ class Thread < Object
   # resource allocation code. Then, the ensure block is where we can safely
   # deallocate your resources.
   #
-  # #### Guarding from Timeout::Error
-  #
-  # In the next example, we will guard from the Timeout::Error exception. This
-  # will help prevent from leaking resources when Timeout::Error exceptions occur
-  # during normal ensure clause. For this example we use the help of the standard
-  # library Timeout, from lib/timeout.rb
-  #
-  #     require 'timeout'
-  #     Thread.handle_interrupt(Timeout::Error => :never) {
-  #       timeout(10){
-  #         # Timeout::Error doesn't occur here
-  #         Thread.handle_interrupt(Timeout::Error => :on_blocking) {
-  #           # possible to be killed by Timeout::Error
-  #           # while blocking operation
-  #         }
-  #         # Timeout::Error doesn't occur here
-  #       }
-  #     }
-  #
-  # In the first part of the `timeout` block, we can rely on Timeout::Error being
-  # ignored. Then in the `Timeout::Error => :on_blocking` block, any operation
-  # that will block the calling thread is susceptible to a Timeout::Error
-  # exception being raised.
-  #
   # #### Stack control settings
   #
   # It's possible to stack multiple levels of ::handle_interrupt blocks in order
@@ -992,7 +973,7 @@ class Thread < Object
   #      from prog.rb:2
   #
   def raise: (?String message) -> nil
-           | (_Exception, ?_ToS message, ?Array[String] backtrace) -> nil
+           | (_Exception, ?_ToS message, ?Array[Thread::Backtrace::Location] | Array[String] | nil backtrace) -> nil
 
   # <!--
   #   rdoc-file=thread.c
@@ -1130,7 +1111,6 @@ class Thread < Object
   #     However, this might handle the exception much later, or not at all if the
   #     Thread is never joined due to the parent thread being blocked, etc.
   #
-  #
   # See also ::report_on_exception=.
   #
   # There is also an instance level method to set this for a specific thread, see
@@ -1318,9 +1298,28 @@ class Thread::Backtrace::Location
   #   rdoc-file=vm_backtrace.c
   #   - base_label()
   # -->
-  # Returns the base label of this frame.
+  # Returns the base label of this frame, which is usually equal to the label,
+  # without decoration.
   #
-  # Usually same as #label, without decoration.
+  # Consider the following example:
+  #
+  #     def foo
+  #       puts caller_locations(0).first.base_label
+  #
+  #       1.times do
+  #         puts caller_locations(0).first.base_label
+  #
+  #         1.times do
+  #           puts caller_locations(0).first.base_label
+  #         end
+  #       end
+  #     end
+  #
+  # The result of calling `foo` is this:
+  #
+  #     foo
+  #     foo
+  #     foo
   #
   def base_label: () -> String?
 
@@ -1343,15 +1342,14 @@ class Thread::Backtrace::Location
   #         1.times do
   #           puts caller_locations(0).first.label
   #         end
-  #
   #       end
   #     end
   #
   # The result of calling `foo` is this:
   #
-  #     label: foo
-  #     label: block in foo
-  #     label: block (2 levels) in foo
+  #     foo
+  #     block in foo
+  #     block (2 levels) in foo
   #
   def label: () -> String?
 
@@ -1578,7 +1576,6 @@ class Thread::Queue[Elem = untyped] < Object
   # *   when `empty?` is true, deq(false) will not suspend the thread and will
   #     return nil. deq(true) will raise a `ThreadError`.
   #
-  #
   # ClosedQueueError is inherited from StopIteration, so that you can break loop
   # block.
   #