rbs 3.10.0.pre.2 → 3.10.1

data/core/integer.rbs

@@ -146,9 +146,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self % other -> real_number
+  #   - self % other -> real_numeric
   # -->
-  # Returns `self` modulo `other` as a real number.
+  # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational).
   #
   # For integer `n` and real number `r`, these expressions are equivalent:
   #
@@ -193,13 +193,13 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self * numeric -> numeric_result
+  #   - self * other -> numeric
   # -->
-  # Performs multiplication:
+  # Returns the numeric product of `self` and `other`:
   #
   #     4 * 2              # => 8
-  #     4 * -2             # => -8
   #     -4 * 2             # => -8
+  #     4 * -2             # => -8
   #     4 * 2.0            # => 8.0
   #     4 * Rational(1, 3) # => (4/3)
   #     4 * Complex(2, 0)  # => (8+0i)
@@ -211,17 +211,47 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self ** numeric -> numeric_result
+  #   - self ** exponent -> numeric
   # -->
-  # Raises `self` to the power of `numeric`:
-  #
-  #     2 ** 3              # => 8
-  #     2 ** -3             # => (1/8)
-  #     -2 ** 3             # => -8
-  #     -2 ** -3            # => (-1/8)
-  #     2 ** 3.3            # => 9.849155306759329
-  #     2 ** Rational(3, 1) # => (8/1)
-  #     2 ** Complex(3, 0)  # => (8+0i)
+  # Returns `self` raised to the power `exponent`:
+  #
+  #     # Result for non-negative Integer exponent is Integer.
+  #     2 ** 0   # => 1
+  #     2 ** 1   # => 2
+  #     2 ** 2   # => 4
+  #     2 ** 3   # => 8
+  #     -2 ** 3  # => -8
+  #     # Result for negative Integer exponent is Rational, not Float.
+  #     2 ** -3  # => (1/8)
+  #     -2 ** -3 # => (-1/8)
+  #
+  #     # Result for Float exponent is Float.
+  #     2 ** 0.0   # => 1.0
+  #     2 ** 1.0   # => 2.0
+  #     2 ** 2.0   # => 4.0
+  #     2 ** 3.0   # => 8.0
+  #     -2 ** 3.0  # => -8.0
+  #     2 ** -3.0  # => 0.125
+  #     -2 ** -3.0 # => -0.125
+  #
+  #     # Result for non-negative Complex exponent is Complex with Integer parts.
+  #     2 ** Complex(0, 0)   # => (1+0i)
+  #     2 ** Complex(1, 0)   # => (2+0i)
+  #     2 ** Complex(2, 0)   # => (4+0i)
+  #     2 ** Complex(3, 0)   # => (8+0i)
+  #     -2 ** Complex(3, 0) # => (-8+0i)
+  #     # Result for negative Complex exponent is Complex with Rational parts.
+  #     2 ** Complex(-3, 0)  # => ((1/8)+(0/1)*i)
+  #     -2 ** Complex(-3, 0) # => ((-1/8)+(0/1)*i)
+  #
+  #     # Result for Rational exponent is Rational.
+  #     2 ** Rational(0, 1)   # => (1/1)
+  #     2 ** Rational(1, 1)   # => (2/1)
+  #     2 ** Rational(2, 1)   # => (4/1)
+  #     2 ** Rational(3, 1)   # => (8/1)
+  #     -2 ** Rational(3, 1)  # => (-8/1)
+  #     2 ** Rational(-3, 1)  # => (1/8)
+  #     -2 ** Rational(-3, 1) # => (-1/8)
   #
   def **: (Integer) -> Numeric
         | (Float) -> Numeric
@@ -230,16 +260,20 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self + numeric -> numeric_result
+  #   - self + other -> numeric
   # -->
-  # Performs addition:
+  # Returns the sum of `self` and `other`:
+  #
+  #     1 + 1               # => 2
+  #     1 + -1             # => 0
+  #     1 + 0              # => 1
+  #     1 + -2             # => -1
+  #     1 + Complex(1, 0)  # => (2+0i)
+  #     1 + Rational(1, 1) # => (2/1)
+  #
+  # For a computation involving Floats, the result may be inexact (see Float#+):
   #
-  #     2 + 2              # => 4
-  #     -2 + 2             # => 0
-  #     -2 + -2            # => -4
-  #     2 + 2.0            # => 4.0
-  #     2 + Rational(2, 1) # => (4/1)
-  #     2 + Complex(2, 0)  # => (4+0i)
+  #     1 + 3.14           # => 4.140000000000001
   #
   def +: (Integer) -> Integer
        | (Float) -> Float
@@ -250,9 +284,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self - numeric -> numeric_result
+  #   - self - other -> numeric
   # -->
-  # Performs subtraction:
+  # Returns the difference of `self` and `other`:
   #
   #     4 - 2              # => 2
   #     -4 - 2             # => -6
@@ -268,28 +302,34 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - -int -> integer
+  #   - -self -> integer
   # -->
-  # Returns `self`, negated.
+  # Returns `self`, negated:
+  #
+  #     -1    # => -1
+  #     -(-1) # => 1
+  #     -0    # => 0
   #
   def -@: () -> Integer
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self / numeric -> numeric_result
+  #   - self / other -> numeric
   # -->
-  # Performs division; for integer `numeric`, truncates the result to an integer:
+  # Returns the quotient of `self` and `other`.
+  #
+  # For integer `other`, truncates the result to an integer:
   #
-  #      4 / 3              # => 1
-  #      4 / -3             # => -2
-  #      -4 / 3             # => -2
-  #      -4 / -3            # => 1
+  #     4 / 3              # => 1
+  #     4 / -3             # => -2
+  #     -4 / 3             # => -2
+  #     -4 / -3            # => 1
   #
-  #     For other +numeric+, returns non-integer result:
+  # For non-integer `other`, returns a non-integer result:
   #
-  #      4 / 3.0            # => 1.3333333333333333
-  #      4 / Rational(3, 1) # => (4/3)
-  #      4 / Complex(3, 0)  # => ((4/3)+0i)
+  #     4 / 3.0            # => 1.3333333333333333
+  #     4 / Rational(3, 1) # => (4/3)
+  #     4 / Complex(3, 0)  # => ((4/3)+0i)
   #
   def /: (Integer) -> Integer
        | (Float) -> Float
@@ -300,15 +340,14 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - self < other -> true or false
   # -->
-  # Returns `true` if the value of `self` is less than that of `other`:
+  # Returns whether the value of `self` is less than the value of `other`; `other`
+  # must be numeric, but may not be Complex:
   #
-  #       1 < 0              # => false
-  #       1 < 1              # => false
-  #       1 < 2              # => true
-  #       1 < 0.5            # => false
-  #       1 < Rational(1, 2) # => false
-  #
-  #     Raises an exception if the comparison cannot be made.
+  #     1 < 0              # => false
+  #     1 < 1              # => false
+  #     1 < 2              # => true
+  #     1 < 0.5            # => false
+  #     1 < Rational(1, 2) # => false
   #
   def <: (Numeric) -> bool
 
@@ -331,44 +370,46 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self <= real -> true or false
+  #   - self <= other -> true or false
   # -->
-  # Returns `true` if the value of `self` is less than or equal to that of
-  # `other`:
+  # Returns whether the value of `self` is less than or equal to the value of
+  # `other`; `other` must be numeric, but may not be Complex:
   #
-  #     1 <= 0              # => false
-  #     1 <= 1              # => true
-  #     1 <= 2              # => true
-  #     1 <= 0.5            # => false
-  #     1 <= Rational(1, 2) # => false
+  #       1 <= 0              # => false
+  #       1 <= 1              # => true
+  #       1 <= 2              # => true
+  #       1 <= 0.5            # => false
+  #       1 <= Rational(1, 2) # => false
   #
-  # Raises an exception if the comparison cannot be made.
+  #     Raises an exception if the comparison cannot be made.
   #
   def <=: (Numeric) -> bool
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self <=> other  ->  -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
+  # Compares `self` and `other`.
+  #
   # Returns:
   #
-  # *   -1, if `self` is less than `other`.
-  # *   0, if `self` is equal to `other`.
-  # *   1, if `self` is greater then `other`.
+  # *   `-1`, if `self` is less than `other`.
+  # *   `0`, if `self` is equal to `other`.
+  # *   `1`, if `self` is greater then `other`.
   # *   `nil`, if `self` and `other` are incomparable.
   #
   # Examples:
   #
   #     1 <=> 2              # => -1
   #     1 <=> 1              # => 0
-  #     1 <=> 0              # => 1
-  #     1 <=> 'foo'          # => nil
-  #
   #     1 <=> 1.0            # => 0
   #     1 <=> Rational(1, 1) # => 0
   #     1 <=> Complex(1, 0)  # => 0
+  #     1 <=> 0              # => 1
+  #     1 <=> 'foo'          # => nil
   #
-  # This method is the basis for comparisons in module Comparable.
+  # Class Integer includes module Comparable, each of whose methods uses
+  # Integer#<=> for comparison.
   #
   def <=>: (Integer | Rational) -> Integer
          | (untyped) -> Integer?
@@ -955,7 +996,7 @@ class Integer < Numeric
   def magnitude: () -> Integer
 
   # <!-- rdoc-file=numeric.c -->
-  # Returns `self` modulo `other` as a real number.
+  # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational).
   #
   # For integer `n` and real number `r`, these expressions are equivalent:
   #

data/core/io/buffer.rbs

@@ -64,9 +64,9 @@ class IO
   #
   #     File.write('test.txt', 'test data')
   #     # => 9
-  #     buffer = IO::Buffer.map(File.open('test.txt'))
+  #     buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
   #     # =>
-  #     # #<IO::Buffer 0x00007f3f0768c000+9 MAPPED IMMUTABLE>
+  #     # #<IO::Buffer 0x00007f3f0768c000+9 EXTERNAL MAPPED FILE SHARED READONLY>
   #     # ...
   #     buffer.get_string(5, 2) # read 2 bytes, starting from offset 5
   #     # => "da"
@@ -113,7 +113,7 @@ class IO
     #     buffer.get_string(0, 1)
     #     # => "t"
     #     string
-    #     # => "best"
+    #     # => "test"
     #
     #     buffer.resize(100)
     #     # in `resize': Cannot resize external buffer! (IO::Buffer::AccessError)
@@ -131,18 +131,25 @@ class IO
     #   - IO::Buffer.map(file, [size, [offset, [flags]]]) -> io_buffer
     # -->
     # Create an IO::Buffer for reading from `file` by memory-mapping the file.
-    # `file_io` should be a `File` instance, opened for reading.
+    # `file` should be a `File` instance, opened for reading or reading and writing.
+    #
+    # Optional `size` and `offset` of mapping can be specified. Trying to map an
+    # empty file or specify `size` of 0 will raise an error. Valid values for
+    # `offset` are system-dependent.
     #
-    # Optional `size` and `offset` of mapping can be specified.
+    # By default, the buffer is writable and expects the file to be writable. It is
+    # also shared, so several processes can use the same mapping.
     #
-    # By default, the buffer would be immutable (read only); to create a writable
-    # mapping, you need to open a file in read-write mode, and explicitly pass
-    # `flags` argument without IO::Buffer::IMMUTABLE.
+    # You can pass IO::Buffer::READONLY in `flags` argument to make a read-only
+    # buffer; this allows to work with files opened only for reading. Specifying
+    # IO::Buffer::PRIVATE in `flags` creates a private mapping, which will not
+    # impact other processes or the underlying file. It also allows updating a
+    # buffer created from a read-only file.
     #
     #     File.write('test.txt', 'test')
     #
     #     buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
-    #     # => #<IO::Buffer 0x00000001014a0000+4 MAPPED READONLY>
+    #     # => #<IO::Buffer 0x00000001014a0000+4 EXTERNAL MAPPED FILE SHARED READONLY>
     #
     #     buffer.readonly?   # => true
     #
@@ -150,7 +157,7 @@ class IO
     #     # => "test"
     #
     #     buffer.set_string('b', 0)
-    #     # `set_string': Buffer is not writable! (IO::Buffer::AccessError)
+    #     # 'IO::Buffer#set_string': Buffer is not writable! (IO::Buffer::AccessError)
     #
     #     # create read/write mapping: length 4 bytes, offset 0, flags 0
     #     buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0)
@@ -382,6 +389,10 @@ class IO
     # *   `:U64`: unsigned integer, 8 bytes, big-endian
     # *   `:s64`: signed integer, 8 bytes, little-endian
     # *   `:S64`: signed integer, 8 bytes, big-endian
+    # *   `:u128`: unsigned integer, 16 bytes, little-endian
+    # *   `:U128`: unsigned integer, 16 bytes, big-endian
+    # *   `:s128`: signed integer, 16 bytes, little-endian
+    # *   `:S128`: signed integer, 16 bytes, big-endian
     # *   `:f32`: float, 4 bytes, little-endian
     # *   `:F32`: float, 4 bytes, big-endian
     # *   `:f64`: double, 8 bytes, little-endian

data/core/io.rbs

@@ -1373,7 +1373,7 @@ class IO < Object
   # Formats and writes `objects` to the stream.
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:format_specifications.rdoc).
+  # Specifications](rdoc-ref:language/format_specifications.rdoc).
   #
   def printf: (String format_string, *untyped objects) -> nil
 
@@ -2276,7 +2276,7 @@ class IO < Object
   #
   # When called from class IO (but not subclasses of IO), this method has
   # potential security vulnerabilities if called with untrusted input; see
-  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  # [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   def self.binread: (String name, ?Integer? length, ?Integer offset) -> String
 
@@ -2289,7 +2289,7 @@ class IO < Object
   #
   # When called from class IO (but not subclasses of IO), this method has
   # potential security vulnerabilities if called with untrusted input; see
-  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  # [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   def self.binwrite: (String name, _ToS string, ?Integer offset, ?mode: String mode) -> Integer
 
@@ -2354,7 +2354,7 @@ class IO < Object
   # connected to a new stream `io`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # If no block is given, returns the new stream, which depending on given `mode`
   # may be open for reading, writing, or both. The stream should be explicitly
@@ -2529,7 +2529,7 @@ class IO < Object
   #
   # When called from class IO (but not subclasses of IO), this method has
   # potential security vulnerabilities if called with untrusted input; see
-  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  # [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # The first argument must be a string that is the path to a file.
   #
@@ -2686,7 +2686,7 @@ class IO < Object
   #
   # When called from class IO (but not subclasses of IO), this method has
   # potential security vulnerabilities if called with untrusted input; see
-  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  # [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # The first argument must be a string that is the path to a file.
   #
@@ -2729,7 +2729,7 @@ class IO < Object
   #
   # When called from class IO (but not subclasses of IO), this method has
   # potential security vulnerabilities if called with untrusted input; see
-  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  # [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # The first argument must be a string that is the path to a file.
   #
@@ -2954,7 +2954,7 @@ class IO < Object
   #
   # When called from class IO (but not subclasses of IO), this method has
   # potential security vulnerabilities if called with untrusted input; see
-  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  # [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # The first argument must be a string that is the path to a file.
   #

data/core/kernel.rbs

@@ -718,7 +718,7 @@ module Kernel : BasicObject
   # variable `$?` to the process status.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # Examples:
   #
@@ -1004,6 +1004,8 @@ module Kernel : BasicObject
   # With argument `exception` not given, argument `message` and keyword argument
   # `cause` may be given, but argument `backtrace` may not be given.
   #
+  # `cause` can not be given as an only argument.
+  #
   def self?.fail: () -> bot
                 | (string message, ?cause: Exception?) -> bot
                 | (_Exception exception, ?_ToS? message, ?String | Array[String] | Array[Thread::Backtrace::Location] | nil backtrace, ?cause: Exception?) -> bot
@@ -1110,6 +1112,8 @@ module Kernel : BasicObject
   # With argument `exception` not given, argument `message` and keyword argument
   # `cause` may be given, but argument `backtrace` may not be given.
   #
+  # `cause` can not be given as an only argument.
+  #
   alias raise fail
 
   alias self.raise self.fail
@@ -1118,7 +1122,7 @@ module Kernel : BasicObject
   # Returns the string resulting from formatting `objects` into `format_string`.
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:format_specifications.rdoc).
+  # Specifications](rdoc-ref:language/format_specifications.rdoc).
   #
   def self?.format: (String format, *untyped args) -> String
 
@@ -1129,7 +1133,7 @@ module Kernel : BasicObject
   # Returns the string resulting from formatting `objects` into `format_string`.
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:format_specifications.rdoc).
+  # Specifications](rdoc-ref:language/format_specifications.rdoc).
   #
   alias sprintf format
 
@@ -1249,7 +1253,7 @@ module Kernel : BasicObject
   # Creates an IO object connected to the given file.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # With no block given, file stream is returned:
   #
@@ -1327,7 +1331,7 @@ module Kernel : BasicObject
   #     io.write(sprintf(format_string, *objects))
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:format_specifications.rdoc).
+  # Specifications](rdoc-ref:language/format_specifications.rdoc).
   #
   # With the single argument `format_string`, formats `objects` into the string,
   # then writes the formatted string to $stdout:
@@ -1907,7 +1911,7 @@ module Kernel : BasicObject
   # *   Invoking the executable at `exe_path`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # The new process is created using the [exec system
   # call](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/functions/e
@@ -1999,7 +2003,7 @@ module Kernel : BasicObject
   # *   Invoking the executable at `exe_path`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # Returns the process ID (pid) of the new process, without waiting for it to
   # complete.
@@ -2102,7 +2106,7 @@ module Kernel : BasicObject
   # *   Invoking the executable at `exe_path`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
   #
   # Returns:
   #

data/core/method.rbs

@@ -126,7 +126,9 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.call(args, ...)    -> obj
+  #   - meth.call(args, ...) -> obj
+  #   - meth[args, ...] -> obj
+  #   - method === obj -> result_of_method
   # -->
   # Invokes the *meth* with the specified arguments, returning the method's return
   # value.
@@ -135,23 +137,32 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
+  # Using Method#=== allows a method object to be the target of a `when` clause in
+  # a case statement.
+  #
+  #     require 'prime'
+  #
+  #     case 1373
+  #     when Prime.method(:prime?)
+  #       # ...
+  #     end
+  #
   def call: (?) -> untyped
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth << g -> a_proc
+  #   - self << g -> a_proc
   # -->
-  # Returns a proc that is the composition of this method and the given *g*. The
-  # returned proc takes a variable number of arguments, calls *g* with them then
-  # calls this method with the result.
+  # Returns a proc that is the composition of the given `g` and this method.
   #
-  #     def f(x)
-  #       x * x
-  #     end
+  # The returned proc takes a variable number of arguments. It first calls `g`
+  # with the arguments, then calls `self` with the return value of `g`.
+  #
+  #     def f(ary) = ary << 'in f'
   #
   #     f = self.method(:f)
-  #     g = proc {|x| x + x }
-  #     p (f << g).call(2) #=> 16
+  #     g = proc { |ary| ary << 'in proc' }
+  #     (f << g).call([]) # => ["in proc", "in f"]
   #
   def <<: (Proc::_Callable g) -> Proc
 
@@ -163,23 +174,32 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
+  # Using Method#=== allows a method object to be the target of a `when` clause in
+  # a case statement.
+  #
+  #     require 'prime'
+  #
+  #     case 1373
+  #     when Prime.method(:prime?)
+  #       # ...
+  #     end
+  #
   alias === call
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth >> g -> a_proc
+  #   - self >> g -> a_proc
   # -->
-  # Returns a proc that is the composition of this method and the given *g*. The
-  # returned proc takes a variable number of arguments, calls this method with
-  # them then calls *g* with the result.
+  # Returns a proc that is the composition of this method and the given `g`.
   #
-  #     def f(x)
-  #       x * x
-  #     end
+  # The returned proc takes a variable number of arguments. It first calls `self`
+  # with the arguments, then calls `g` with the return value of `self`.
+  #
+  #     def f(ary) = ary << 'in f'
   #
   #     f = self.method(:f)
-  #     g = proc {|x| x + x }
-  #     p (f >> g).call(2) #=> 8
+  #     g = proc { |ary| ary << 'in proc' }
+  #     (f >> g).call([]) # => ["in f", "in proc"]
   #
   def >>: (Proc::_Callable g) -> Proc
 
@@ -191,6 +211,16 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
+  # Using Method#=== allows a method object to be the target of a `when` clause in
+  # a case statement.
+  #
+  #     require 'prime'
+  #
+  #     case 1373
+  #     when Prime.method(:prime?)
+  #       # ...
+  #     end
+  #
   alias [] call
 
   # <!--

data/core/module.rbs

@@ -114,12 +114,15 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - mod < other   ->  true, false, or nil
+  #   - self < other -> true, false, or nil
   # -->
-  # Returns true if *mod* is a subclass of *other*. Returns `false` if *mod* is
-  # the same as *other* or *mod* is an ancestor of *other*. Returns `nil` if
-  # there's no relationship between the two. (Think of the relationship in terms
-  # of the class definition: "class A < B" implies "A < B".)
+  # Returns whether `self` is a subclass of `other`, or `nil` if there is no
+  # relationship between the two:
+  #
+  #     Float < Numeric # => true
+  #     Numeric < Float # => false
+  #     Float < Float   # => false
+  #     Float < Hash    # => nil
   #
   def <: (Module other) -> bool?
 
@@ -135,14 +138,29 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - module <=> other_module   -> -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # Comparison---Returns -1, 0, +1 or nil depending on whether `module` includes
-  # `other_module`, they are the same, or if `module` is included by
-  # `other_module`.
+  # Compares `self` and `other`.
+  #
+  # Returns:
+  #
+  # *   `-1`, if `self` includes `other`, if or `self` is a subclass of `other`.
+  # *   `0`, if `self` and `other` are the same.
+  # *   `1`, if `other` includes `self`, or if `other` is a subclass of `self`.
+  # *   `nil`, if none of the above is true.
+  #
+  # Examples:
   #
-  # Returns `nil` if `module` has no relationship with `other_module`, if
-  # `other_module` is not a module, or if the two values are incomparable.
+  #     # Class Array includes module Enumerable.
+  #              Array <=> Enumerable # => -1
+  #         Enumerable <=> Enumerable # =>  0
+  #         Enumerable <=> Array      # =>  1
+  #     # Class File is a subclass of class IO.
+  #               File <=> IO         # => -1
+  #               File <=> File       # =>  0
+  #                 IO <=> File       # =>  1
+  #     # Class File has no relationship to class String.
+  #               File <=> String     # => nil
   #
   def <=>: (untyped other) -> Integer?
 
@@ -1638,7 +1656,7 @@ class Module < Object
   #     m.name #=> nil
   #
   #     c = Class.new
-  #     c.set_temporary_name("MyClass(with description)")
+  #     c.set_temporary_name("MyClass(with description)") # => MyClass(with description)
   #
   #     c.new # => #<MyClass(with description):0x0....>
   #