rbs 3.10.0 → 3.10.1

data/core/ractor.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=ractor.rb -->
-# Ractor.new makes a new Ractor, which can run in parallel.
+# Ractor.new creates a new Ractor, which can run in parallel with other ractors.
 #
 #     # The simplest ractor
 #     r = Ractor.new {puts "I am in Ractor!"}
@@ -10,10 +10,10 @@
 # to this: across ractors, thread-safety concerns such as data-races and
 # race-conditions are not possible. The other benefit is parallelism.
 #
-# To achieve this, object sharing is limited across ractors. For example, unlike
-# in threads, ractors can't access all the objects available in other ractors.
-# Even objects normally available through variables in the outer scope are
-# prohibited from being used across ractors.
+# To achieve this, object sharing is limited across ractors. Unlike in threads,
+# ractors can't access all the objects available in other ractors. For example,
+# objects normally available through variables in the outer scope are prohibited
+# from being used across ractors.
 #
 #     a = 1
 #     r = Ractor.new {puts "I am in Ractor! a=#{a}"}
@@ -24,16 +24,16 @@
 #     a = 1
 #     r = Ractor.new(a) { |a1| puts "I am in Ractor! a=#{a1}"}
 #
-# On CRuby (the default implementation), Global Virtual Machine Lock (GVL) is
-# held per ractor, so ractors can perform in parallel without locking each
-# other. This is unlike the situation with threads on CRuby.
+# On CRuby (the default implementation), the Global Virtual Machine Lock (GVL)
+# is held per ractor, so ractors can run in parallel. This is unlike the
+# situation with threads on CRuby.
 #
 # Instead of accessing shared state, objects should be passed to and from
 # ractors by sending and receiving them as messages.
 #
 #     a = 1
 #     r = Ractor.new do
-#       a_in_ractor = receive # receive blocks until somebody passes a message
+#       a_in_ractor = receive # receive blocks the Thread until our default port gets sent a message
 #       puts "I am in Ractor! a=#{a_in_ractor}"
 #     end
 #     r.send(a)  # pass it
@@ -46,15 +46,15 @@
 #
 # ## Shareable and unshareable objects
 #
-# When an object is sent to and from a ractor, it's important to understand
-# whether the object is shareable or unshareable. Most Ruby objects are
-# unshareable objects. Even frozen objects can be unshareable if they contain
-# (through their instance variables) unfrozen objects.
+# When an object is sent to a ractor, it's important to understand whether the
+# object is shareable or unshareable. Most Ruby objects are unshareable objects.
+# Even frozen objects can be unshareable if they contain (through their instance
+# variables) unfrozen objects.
 #
-# Shareable objects are those which can be used by several threads without
-# compromising thread-safety, for example numbers, `true` and `false`.
+# Shareable objects are those which can be used by several ractors at once
+# without compromising thread-safety, for example numbers, `true` and `false`.
 # Ractor.shareable? allows you to check this, and Ractor.make_shareable tries to
-# make the object shareable if it's not already, and gives an error if it can't
+# make the object shareable if it's not already and gives an error if it can't
 # do it.
 #
 #     Ractor.shareable?(1)            #=> true -- numbers and other immutable basic values are shareable
@@ -70,13 +70,13 @@
 #     ary[0].frozen?              #=> true
 #     ary[1].frozen?              #=> true
 #
-# When a shareable object is sent (via #send or Ractor.yield), no additional
-# processing occurs on it. It just becomes usable by both ractors. When an
-# unshareable object is sent, it can be either *copied* or *moved*. The first is
-# the default, and it copies the object fully by deep cloning (Object#clone) the
-# non-shareable parts of its structure.
+# When a shareable object is sent via #send, no additional processing occurs on
+# it and it becomes usable by both ractors. When an unshareable object is sent,
+# it can be either *copied* or *moved*. Copying is the default, and it copies
+# the object fully by deep cloning (Object#clone) the non-shareable parts of its
+# structure.
 #
-#     data = ['foo', 'bar'.freeze]
+#     data = ['foo'.dup, 'bar'.freeze]
 #     r = Ractor.new do
 #       data2 = Ractor.receive
 #       puts "In ractor: #{data2.object_id}, #{data2[0].object_id}, #{data2[1].object_id}"
@@ -87,8 +87,8 @@
 #
 # This will output something like:
 #
-#     In ractor: 340, 360, 320
-#     Outside  : 380, 400, 320
+#     In ractor: 8, 16, 24
+#     Outside  : 32, 40, 24
 #
 # Note that the object ids of the array and the non-frozen string inside the
 # array have changed in the ractor because they are different objects. The
@@ -115,14 +115,14 @@
 #     Outside: moved? true
 #     test.rb:9:in `method_missing': can not send any methods to a moved object (Ractor::MovedError)
 #
-# Notice that even `inspect` (and more basic methods like `__id__`) is
+# Notice that even `inspect` and more basic methods like `__id__` are
 # inaccessible on a moved object.
 #
-# `Class` and `Module` objects are shareable so the class/module definitions are
-# shared between ractors. Ractor objects are also shareable. All operations on
-# shareable objects are thread-safe, so the thread-safety property will be kept.
-# We can not define mutable shareable objects in Ruby, but C extensions can
-# introduce them.
+# `Class` and `Module` objects are shareable and their class/module definitions
+# are shared between ractors. Ractor objects are also shareable. All operations
+# on shareable objects are thread-safe across ractors. Defining mutable,
+# shareable objects in Ruby is not possible, but C extensions can introduce
+# them.
 #
 # It is prohibited to access (get) instance variables of shareable objects in
 # other ractors if the values of the variables aren't shareable. This can occur
@@ -189,14 +189,15 @@
 # ## Note on code examples
 #
 # In the examples below, sometimes we use the following method to wait for
-# ractors that are not currently blocked to finish (or to make progress).
+# ractors to make progress or finish.
 #
 #     def wait
 #       sleep(0.1)
 #     end
 #
-# It is **only for demonstration purposes** and shouldn't be used in a real
-# code. Most of the time, #join is used to wait for ractors to finish.
+# This is **only for demonstration purposes** and shouldn't be used in a real
+# code. Most of the time, #join is used to wait for ractors to finish and
+# Ractor.receive is used to wait for messages.
 #
 # ## Reference
 #
@@ -215,7 +216,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - [](sym)
   # -->
-  # get a value from ractor-local storage of current Ractor
+  # Gets a value from ractor-local storage for the current Ractor.
   #
   def self.[]: (Symbol) -> untyped
 
@@ -223,7 +224,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - []=(sym, val)
   # -->
-  # set a value in ractor-local storage of current Ractor
+  # Sets a value in ractor-local storage for the current Ractor.
   #
   def self.[]=: (Symbol, untyped) -> untyped
 
@@ -231,7 +232,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - count()
   # -->
-  # Returns the number of Ractors currently running or blocking (waiting).
+  # Returns the number of ractors currently running or blocking (waiting).
   #
   #     Ractor.count                   #=> 1
   #     r = Ractor.new(name: 'example') { Ractor.receive }
@@ -256,7 +257,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - main()
   # -->
-  # returns main ractor
+  # Returns the main ractor.
   #
   def self.main: () -> Ractor
 
@@ -264,7 +265,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - main?()
   # -->
-  # return true if the current ractor is main ractor
+  # Returns true if the current ractor is the main ractor.
   #
   def self.main?: () -> boolish
 
@@ -272,7 +273,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - Ractor.make_shareable(obj, copy: false) -> shareable_obj
   # -->
-  # Make `obj` shareable between ractors.
+  # Makes `obj` shareable between ractors.
   #
   # `obj` and all the objects it refers to will be frozen, unless they are already
   # shareable.
@@ -311,10 +312,10 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - Ractor.new(*args, name: nil) {|*args| block } -> ractor
   # -->
-  # Create a new Ractor with args and a block.
+  # Creates a new Ractor with args and a block.
   #
-  # The given block (Proc) will be isolated (can't access any outer variables).
-  # `self` inside the block will refer to the current Ractor.
+  # The given block (Proc) is isolated (can't access any outer variables). `self`
+  # inside the block will refer to the current Ractor.
   #
   #     r = Ractor.new { puts "Hi, I am #{self.inspect}" }
   #     r.join
@@ -346,7 +347,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - Ractor.receive -> obj
   # -->
-  # Receive a message from the default port.
+  # Receives a message from the current ractor's default port.
   #
   def self.receive: () -> untyped
 
@@ -359,9 +360,48 @@ class Ractor
 
   # <!--
   #   rdoc-file=ractor.rb
-  #   - Ractor.select(*ports) -> [...]
+  #   - Ractor.select(*ractors_or_ports) -> [ractor or port, obj]
   # -->
-  # TBD
+  # Blocks the current Thread until one of the given ports has received a message.
+  # Returns an array of two elements where the first element is the Port and the
+  # second is the received object. This method can also accept Ractor objects
+  # themselves, and in that case will wait until one has terminated and return a
+  # two-element array where the first element is the ractor and the second is its
+  # termination value.
+  #
+  #     p1, p2 = Ractor::Port.new, Ractor::Port.new
+  #     ps = [p1, p2]
+  #     rs = 2.times.map do |i|
+  #       Ractor.new(ps.shift, i) do |p, i|
+  #         sleep rand(0.99)
+  #         p.send("r#{i}")
+  #         sleep rand(0.99)
+  #         "r#{i} done"
+  #       end
+  #     end
+  #
+  #     waiting_on = [p1, p2, *rs]
+  #     until waiting_on.empty?
+  #       received_on, obj = Ractor.select(*waiting_on)
+  #       waiting_on.delete(received_on)
+  #       puts obj
+  #     end
+  #
+  #     # r0
+  #     # r1
+  #     # r1 done
+  #     # r0 done
+  #
+  # The following example is almost equivalent to `ractors.map(&:value)` except
+  # the thread is unblocked when any of the ractors has terminated as opposed to
+  # waiting for their termination in the array element order.
+  #
+  #     values = []
+  #     until ractors.empty?
+  #       r, val = Ractor.select(*ractors)
+  #       ractors.delete(r)
+  #       values << val
+  #     end
   #
   def self.select: (?) -> Array[untyped]
 
@@ -371,7 +411,7 @@ class Ractor
   # -->
   # Checks if the object is shareable by ractors.
   #
-  #     Ractor.shareable?(1)            #=> true -- numbers and other immutable basic values are frozen
+  #     Ractor.shareable?(1)            #=> true -- numbers are shareable
   #     Ractor.shareable?('foo')        #=> false, unless the string is frozen due to # frozen_string_literal: true
   #     Ractor.shareable?('foo'.freeze) #=> true
   #
@@ -384,16 +424,17 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - Ractor.shareable_proc(self: nil){} -> shareable proc
   # -->
-  # It returns shareable Proc object. The Proc object is shareable and the self in
-  # a block will be replaced with the value passed via `self:` keyword.
+  # Returns a shareable copy of the given block's Proc. The value of `self` in the
+  # Proc will be replaced with the value passed via the `self:` keyword, or `nil`
+  # if not given.
   #
-  # In a shareable Proc, you can not access to the outer variables.
+  # In a shareable Proc, access to any outer variables if prohibited.
   #
   #     a = 42
   #     Ractor.shareable_proc{ p a }
   #     #=> can not isolate a Proc because it accesses outer variables (a). (ArgumentError)
   #
-  # The `self` should be a shareable object
+  # The value of `self` in the Proc must be a shareable object.
   #
   #     Ractor.shareable_proc(self: self){}
   #     #=> self should be shareable: main (Ractor::IsolationError)
@@ -403,9 +444,9 @@ class Ractor
 
   # <!--
   #   rdoc-file=ractor.rb
-  #   - Ractor.shareable_proc{} -> shareable proc
+  #   - Ractor.shareable_lambda(self: nil){} -> shareable lambda
   # -->
-  # Same as Ractor.shareable_proc, but returns lambda proc.
+  # Same as Ractor.shareable_proc, but returns a lambda Proc.
   #
   def self.shareable_lambda: [T] () { (?) [self: nil] -> T } -> ^(?) [self: nil] -> T
                            | [T, S] (self: S) { (?) [self: S] -> T } -> ^(?) [self: S] -> T
@@ -414,9 +455,9 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - Ractor.store_if_absent(key){ init_block }
   # -->
-  # If the corresponding value is not set, yield a value with init_block and store
-  # the value in thread-safe manner. This method returns corresponding stored
-  # value.
+  # If the corresponding ractor-local value is not set, yields a value with
+  # init_block and stores the value in a thread-safe manner. This method returns
+  # the stored value.
   #
   #     (1..10).map{
   #       Thread.new(it){|i|
@@ -438,7 +479,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - [](sym)
   # -->
-  # get a value from ractor-local storage for current Ractor Obsolete and use
+  # Gets a value from ractor-local storage for the current Ractor. Obsolete, use
   # Ractor.[] instead.
   #
   %a{deprecated: Use Ractor.[] instead}
@@ -448,7 +489,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - []=(sym, val)
   # -->
-  # set a value in ractor-local storage for current Ractor Obsolete and use
+  # Sets a value in ractor-local storage for the current Ractor. Obsolete, use
   # Ractor.[]= instead.
   #
   %a{deprecated: Use Ractor.[]= instead}
@@ -458,7 +499,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - ractor.default_port -> port object
   # -->
-  # return default port of the Ractor.
+  # Returns the default port of the Ractor.
   #
   def default_port: () -> Port[untyped]
 
@@ -473,13 +514,13 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - ractor.join -> self
   # -->
-  # Wait for the termination of the Ractor. If the Ractor was aborted (terminated
-  # with an exception), Ractor#value is called to raise an exception.
+  # Waits for the termination of the Ractor. If the Ractor was aborted (terminated
+  # by an unhandled exception), the exception is raised in the current ractor.
   #
   #     Ractor.new{}.join #=> ractor
   #
   #     Ractor.new{ raise "foo" }.join
-  #     #=> raise an exception "foo (RuntimeError)"
+  #     #=> raises the exception "foo (RuntimeError)"
   #
   def join: () -> self
 
@@ -487,7 +528,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - name()
   # -->
-  # The name set in Ractor.new, or `nil`.
+  # Returns the name set in Ractor.new, or `nil`.
   #
   def name: () -> String?
 
@@ -495,26 +536,27 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - ractor.monitor(port) -> self
   # -->
-  # Register port as a monitoring port. If the ractor terminated, the port
-  # received a Symbol object. :exited will be sent if the ractor terminated
-  # without an exception. :aborted will be sent if the ractor terminated with a
-  # exception.
+  # Registers the port as a monitoring port for this ractor. When the ractor
+  # terminates, the port receives a Symbol object.
+  #
+  # *   `:exited` is sent if the ractor terminates without an unhandled exception.
+  # *   `:aborted` is sent if the ractor terminates by an unhandled exception.
   #
-  #     r = Ractor.new{ some_task() }
-  #     r.monitor(port = Ractor::Port.new)
-  #     port.receive #=> :exited and r is terminated
+  #         r = Ractor.new{ some_task() }
+  #         r.monitor(port = Ractor::Port.new)
+  #         port.receive #=> :exited and r is terminated
   #
-  #     r = Ractor.new{ raise "foo" }
-  #     r.monitor(port = Ractor::Port.new)
-  #     port.receive #=> :terminated and r is terminated with an exception "foo"
+  #         r = Ractor.new{ raise "foo" }
+  #         r.monitor(port = Ractor::Port.new)
+  #         port.receive #=> :aborted and r is terminated by the RuntimeError "foo"
   #
   def monitor: [T < Symbol] (Port[T]) -> untyped
 
   # <!--
   #   rdoc-file=ractor.rb
-  #   - ractor.send(msg) -> self
+  #   - ractor.send(msg, move: false) -> self
   # -->
-  # It is equivalent to default_port.send(msg)
+  # This is equivalent to Port#send to the ractor's #default_port.
   #
   def send: (untyped obj, ?move: boolish) -> Ractor
 
@@ -529,7 +571,7 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - ractor.unmonitor(port) -> self
   # -->
-  # Unregister port from the monitoring ports.
+  # Unregisters the port from the monitoring ports for this ractor.
   #
   def unmonitor: (Port[untyped]) -> self
 
@@ -537,9 +579,10 @@ class Ractor
   #   rdoc-file=ractor.rb
   #   - ractor.value -> obj
   # -->
-  # Waits for `ractor` to complete, using #join, and return its value or raise the
-  # exception which terminated the Ractor. The value will not be copied even if it
-  # is unshareable object. Therefore at most 1 Ractor can get a value.
+  # Waits for `ractor` to complete and returns its value or raises the exception
+  # which terminated the Ractor. The termination value will be moved to the
+  # calling Ractor. Therefore, at most 1 Ractor can receive another ractor's
+  # termination value.
   #
   #     r = Ractor.new{ [1, 2] }
   #     r.value #=> [1, 2] (unshareable object)
@@ -576,36 +619,16 @@ class Ractor
   # <!-- rdoc-file=ractor.c -->
   # Raised when an attempt is made to send a message to a closed port, or to
   # retrieve a message from a closed and empty port. Ports may be closed
-  # explicitly with Ractor#close_outgoing/close_incoming and are closed implicitly
-  # when a Ractor terminates.
-  #
-  #     r = Ractor.new { sleep(500) }
-  #     r.close_outgoing
-  #     r.take # Ractor::ClosedError
-  #
-  # ClosedError is a descendant of StopIteration, so the closing of the ractor
-  # will break the loops without propagating the error:
+  # explicitly with Ractor::Port#close and are closed implicitly when a Ractor
+  # terminates.
   #
-  #     r = Ractor.new do
-  #       loop do
-  #         msg = receive # raises ClosedError and loop traps it
-  #         puts "Received: #{msg}"
-  #       end
-  #       puts "loop exited"
-  #     end
-  #
-  #     3.times{|i| r << i}
-  #     r.close_incoming
-  #     r.take
-  #     puts "Continue successfully"
+  #     port = Ractor::Port.new
+  #     port.close
+  #     port << "test"  # Ractor::ClosedError
+  #     port.receive    # Ractor::ClosedError
   #
-  # This will print:
-  #
-  #     Received: 0
-  #     Received: 1
-  #     Received: 2
-  #     loop exited
-  #     Continue successfully
+  # ClosedError is a descendant of StopIteration, so the closing of a port will
+  # break out of loops without propagating the error.
   #
   class ClosedError < StopIteration
   end
@@ -624,7 +647,7 @@ class Ractor
 
   # <!-- rdoc-file=ractor.c -->
   # Raised on an attempt to access an object which was moved in Ractor#send or
-  # Ractor.yield.
+  # Ractor::Port#send.
   #
   #     r = Ractor.new { sleep }
   #
@@ -638,7 +661,7 @@ class Ractor
 
   # <!-- rdoc-file=ractor.c -->
   # A special object which replaces any value that was moved to another ractor in
-  # Ractor#send or Ractor.yield. Any attempt to access the object results in
+  # Ractor#send or Ractor::Port#send. Any attempt to access the object results in
   # Ractor::MovedError.
   #
   #     r = Ractor.new { receive }
@@ -730,22 +753,10 @@ class Ractor
     #   rdoc-file=ractor.rb
     #   - port.close
     # -->
-    # Close the port. On the closed port, sending is not prohibited. Receiving is
-    # also not allowed if there is no sent messages arrived before closing.
+    # Closes the port. Sending to a closed port is prohibited. Receiving is also
+    # prohibited if there are no messages in its message queue.
     #
-    #     port = Ractor::Port.new
-    #     Ractor.new port do |port|
-    #       port.send 1 # OK
-    #       port.send 2 # OK
-    #       port.close
-    #       port.send 3 # raise Ractor::ClosedError
-    #     end
-    #
-    #     port.receive #=> 1
-    #     port.receive #=> 2
-    #     port.receive #=> raise Ractor::ClosedError
-    #
-    # Now, only a Ractor which creates the port is allowed to close ports.
+    # Only the Ractor which created the port is allowed to close it.
     #
     #     port = Ractor::Port.new
     #     Ractor.new port do |port|
@@ -758,7 +769,7 @@ class Ractor
     #   rdoc-file=ractor.rb
     #   - port.closed? -> true/false
     # -->
-    # Return the port is closed or not.
+    # Returns whether or not the port is closed.
     #
     def closed?: () -> bool
 
@@ -773,7 +784,8 @@ class Ractor
     #   rdoc-file=ractor.rb
     #   - port.receive -> msg
     # -->
-    # Receive a message to the port (which was sent there by Port#send).
+    # Receives a message from the port (which was sent there by Port#send). Only the
+    # ractor that created the port can receive messages this way.
     #
     #     port = Ractor::Port.new
     #     r = Ractor.new port do |port|
@@ -783,9 +795,9 @@ class Ractor
     #     v1 = port.receive
     #     puts "Received: #{v1}"
     #     r.join
-    #     # Here will be printed: "Received: message1"
+    #     # This will print: "Received: message1"
     #
-    # The method blocks if the message queue is empty.
+    # The method blocks the current Thread if the message queue is empty.
     #
     #     port = Ractor::Port.new
     #     r = Ractor.new port do |port|
@@ -811,8 +823,8 @@ class Ractor
     #     Still received only one
     #     Received: message2
     #
-    # If close_incoming was called on the ractor, the method raises
-    # Ractor::ClosedError if there are no more messages in the message queue:
+    # If the port is closed and there are no more messages in the message queue, the
+    # method raises Ractor::ClosedError.
     #
     #     port = Ractor::Port.new
     #     port.close
@@ -824,28 +836,27 @@ class Ractor
     #   rdoc-file=ractor.rb
     #   - port.send(msg, move: false) -> self
     # -->
-    # Send a message to a port to be accepted by port.receive.
+    # Sends a message to the port to be accepted by port.receive.
     #
     #     port = Ractor::Port.new
-    #     r = Ractor.new do
-    #       r.send 'message'
+    #     r = Ractor.new(port) do |port|
+    #       port.send 'message'
     #     end
     #     value = port.receive
     #     puts "Received #{value}"
     #     # Prints: "Received: message"
     #
-    # The method is non-blocking (will return immediately even if the ractor is not
-    # ready to receive anything):
+    # The method is non-blocking (it will return immediately even if the ractor that
+    # created the port is not ready to receive anything):
     #
     #     port = Ractor::Port.new
     #     r = Ractor.new(port) do |port|
-    #       port.send 'test'}
+    #       port.send 'test'
     #       puts "Sent successfully"
     #       # Prints: "Sent successfully" immediately
     #     end
     #
-    # An attempt to send to a port which already closed its execution will raise
-    # Ractor::ClosedError.
+    # An attempt to send to a closed port will raise Ractor::ClosedError.
     #
     #     r = Ractor.new {Ractor::Port.new}
     #     r.join
@@ -857,8 +868,8 @@ class Ractor
     # If the `obj` is unshareable, by default it will be copied into the receiving
     # ractor by deep cloning.
     #
-    # If the object is shareable, it only send a reference to the object without
-    # cloning.
+    # If the object is shareable, a reference to the object will be sent to the
+    # receiving ractor.
     #
     def send: (T obj, ?move: boolish) -> self
 
@@ -876,14 +887,14 @@ class Ractor
   end
 
   # <!-- rdoc-file=ractor.c -->
-  # Raised on attempt to Ractor#take if there was an uncaught exception in the
-  # Ractor. Its `cause` will contain the original exception, and `ractor` is the
-  # original ractor it was raised in.
+  # Raised on Ractor#join or Ractor#value if there was an uncaught exception in
+  # the Ractor. Its `cause` will contain the original exception, and `ractor` is
+  # the original ractor it was raised in.
   #
   #     r = Ractor.new { raise "Something weird happened" }
   #
   #     begin
-  #       r.take
+  #       r.value
   #     rescue => e
   #       p e             # => #<Ractor::RemoteError: thrown by remote Ractor.>
   #       p e.ractor == r # => true
@@ -892,7 +903,7 @@ class Ractor
   #
   class RemoteError < Ractor::Error
     # <!-- rdoc-file=ractor.rb -->
-    # The Ractor an uncaught exception is raised in.
+    # The Ractor in which the uncaught exception was raised.
     #
     def ractor: () -> Ractor
   end

data/core/rational.rbs

@@ -157,20 +157,29 @@ class Rational < Numeric
 
   # <!--
   #   rdoc-file=rational.c
-  #   - rational <=> numeric  ->  -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # Returns -1, 0, or +1 depending on whether `rational` is less than, equal to,
-  # or greater than `numeric`.
+  # Compares `self` and `other`.
   #
-  # `nil` is returned if the two values are incomparable.
+  # Returns:
   #
-  #     Rational(2, 3) <=> Rational(2, 3)  #=> 0
-  #     Rational(5)    <=> 5               #=> 0
-  #     Rational(2, 3) <=> Rational(1, 3)  #=> 1
-  #     Rational(1, 3) <=> 1               #=> -1
-  #     Rational(1, 3) <=> 0.3             #=> 1
+  # *   `-1`, if `self` is less than `other`.
+  # *   `0`, if the two values are the same.
+  # *   `1`, if `self` is greater than `other`.
+  # *   `nil`, if the two values are incomparable.
   #
-  #     Rational(1, 3) <=> "0.3"           #=> nil
+  # Examples:
+  #
+  #     Rational(2, 3) <=> Rational(4, 3) # => -1
+  #     Rational(2, 1) <=> Rational(2, 1) # => 0
+  #     Rational(2, 1) <=> 2              # => 0
+  #     Rational(2, 1) <=> 2.0            # => 0
+  #     Rational(2, 1) <=> Complex(2, 0)  # => 0
+  #     Rational(4, 3) <=> Rational(2, 3) # => 1
+  #     Rational(4, 3) <=> :foo           # => nil
+  #
+  # Class Rational includes module Comparable, each of whose methods uses
+  # Rational#<=> for comparison.
   #
   def <=>: (Integer | Rational) -> Integer
          | (untyped) -> Integer?