rbs 4.0.0.dev.4 → 4.0.0

data/core/kernel.rbs

@@ -73,15 +73,18 @@
 # ### IO
 #
 # *   ::pp: Prints the given objects in pretty form.
-# *   #gets: Returns and assigns to `$_` the next line from the current input.
+# *   #gets: Returns and assigns to <code>$_</code> the next line from the
+#     current input.
 # *   #open: Creates an IO object connected to the given stream, file, or
 #     subprocess.
 # *   #p:  Prints the given objects' inspect output to the standard output.
 # *   #print: Prints the given objects to standard output without a newline.
 # *   #printf: Prints the string resulting from applying the given format string
 #     to any additional arguments.
-# *   #putc: Equivalent to <tt.$stdout.putc(object)</tt> for the given object.
-# *   #puts: Equivalent to `$stdout.puts(*objects)` for the given objects.
+# *   #putc: Equivalent to <code>$stdout.putc(object)</code> for the given
+#     object.
+# *   #puts: Equivalent to <code>$stdout.puts(*objects)</code> for the given
+#     objects.
 # *   #readline: Similar to #gets, but raises an exception at the end of file.
 # *   #readlines: Returns an array of the remaining lines from the current
 #     input.
@@ -102,7 +105,7 @@
 #
 # ### Subprocesses
 #
-# *   [\`command`](rdoc-ref:Kernel#`): Returns the standard output of running
+# *   [`command`](rdoc-ref:Kernel#`): Returns the standard output of running
 #     `command` in a subshell.
 # *   #exec: Replaces current process with a new process.
 # *   #fork: Forks the current process into two processes.
@@ -150,7 +153,7 @@ module Kernel : BasicObject
   #   - caller(range)                -> array or nil
   # -->
   # Returns the current execution stack---an array containing strings in the form
-  # `file:line` or `file:line: in `method'`.
+  # <code>file:line</code> or <code>file:line: in `method'</code>.
   #
   # The optional *start* parameter determines the number of initial stack entries
   # to omit from the top of the stack.
@@ -204,8 +207,9 @@ module Kernel : BasicObject
   # Optionally you can pass a range, which will return an array containing the
   # entries within the specified range.
   #
-  def self?.caller_locations: (?Integer start_or_range, ?Integer length) -> ::Array[Thread::Backtrace::Location]?
-                            | (?::Range[Integer] start_or_range) -> ::Array[Thread::Backtrace::Location]?
+  def self?.caller_locations: (Integer start_or_range, ?Integer length) -> ::Array[Thread::Backtrace::Location]?
+                            | (::Range[Integer] start_or_range) -> ::Array[Thread::Backtrace::Location]?
+                            | () -> ::Array[Thread::Backtrace::Location]
 
   # <!--
   #   rdoc-file=vm_eval.c
@@ -216,10 +220,10 @@ module Kernel : BasicObject
   #
   #     catch(1) { 123 }            # => 123
   #
-  # If `throw(tag2, val)` is called, Ruby searches up its stack for a `catch`
-  # block whose `tag` has the same `object_id` as *tag2*. When found, the block
-  # stops executing and returns *val* (or `nil` if no second argument was given to
-  # `throw`).
+  # If <code>throw(tag2, val)</code> is called, Ruby searches up its stack for a
+  # `catch` block whose `tag` has the same `object_id` as *tag2*. When found, the
+  # block stops executing and returns *val* (or `nil` if no second argument was
+  # given to `throw`).
   #
   #     catch(1) { throw(1, 456) }  # => 456
   #     catch(1) { throw(1) }       # => nil
@@ -230,8 +234,8 @@ module Kernel : BasicObject
   #     catch(1) {|x| x + 2 }       # => 3
   #
   # When no `tag` is given, `catch` yields a new unique object (as from
-  # `Object.new`) as the block parameter. This object can then be used as the
-  # argument to `throw`, and will match the correct `catch` block.
+  # <code>Object.new</code>) as the block parameter. This object can then be used
+  # as the argument to `throw`, and will match the correct `catch` block.
   #
   #     catch do |obj_A|
   #       catch do |obj_B|
@@ -295,7 +299,7 @@ module Kernel : BasicObject
   #   - block_given?   -> true or false
   # -->
   # Returns `true` if `yield` would execute a block in the current context. The
-  # `iterator?` form is mildly deprecated.
+  # <code>iterator?</code> form is mildly deprecated.
   #
   #     def try
   #       if block_given?
@@ -421,7 +425,8 @@ module Kernel : BasicObject
   #     Array({foo: 0, bar: 1}) # => [[:foo, 0], [:bar, 1]]
   #     Array(0..4)             # => [0, 1, 2, 3, 4]
   #
-  # Returns `object` in an array, `[object]`, if `object` cannot be converted:
+  # Returns `object` in an array, <code>[object]</code>, if `object` cannot be
+  # converted:
   #
   #     Array(:foo)             # => [:foo]
   #
@@ -437,8 +442,8 @@ module Kernel : BasicObject
   # Returns a new Complex object if the arguments are valid; otherwise raises an
   # exception if `exception` is `true`; otherwise returns `nil`.
   #
-  # With Numeric arguments `real` and `imag`, returns `Complex.rect(real, imag)`
-  # if the arguments are valid.
+  # With Numeric arguments `real` and `imag`, returns <code>Complex.rect(real,
+  # imag)</code> if the arguments are valid.
   #
   # With string argument `s`, returns a new Complex object if the argument is
   # valid; the string may have:
@@ -448,7 +453,7 @@ module Kernel : BasicObject
   #     coordinates](rdoc-ref:Complex@Rectangular+Coordinates):
   #
   #     *   Sign-separated real and imaginary numeric substrings (with trailing
-  #         character `'i'`):
+  #         character <code>'i'</code>):
   #
   #             Complex('1+2i')  # => (1+2i)
   #             Complex('+1+2i') # => (1+2i)
@@ -456,13 +461,15 @@ module Kernel : BasicObject
   #             Complex('-1+2i') # => (-1+2i)
   #             Complex('-1-2i') # => (-1-2i)
   #
-  #     *   Real-only numeric string (without trailing character `'i'`):
+  #     *   Real-only numeric string (without trailing character
+  #         <code>'i'</code>):
   #
   #             Complex('1')  # => (1+0i)
   #             Complex('+1') # => (1+0i)
   #             Complex('-1') # => (-1+0i)
   #
-  #     *   Imaginary-only numeric string (with trailing character `'i'`):
+  #     *   Imaginary-only numeric string (with trailing character
+  #         <code>'i'</code>):
   #
   #             Complex('1i')  # => (0+1i)
   #             Complex('+1i') # => (0+1i)
@@ -489,10 +496,10 @@ module Kernel : BasicObject
   #   - Float(arg, exception: true)    -> float or nil
   # -->
   # Returns *arg* converted to a float. Numeric types are converted directly, and
-  # with exception to String and `nil`, the rest are converted using *arg*`.to_f`.
-  # Converting a String with invalid characters will result in an ArgumentError.
-  # Converting `nil` generates a TypeError. Exceptions can be suppressed by
-  # passing `exception: false`.
+  # with exception to String and `nil`, the rest are converted using
+  # *arg*<code>.to_f</code>. Converting a String with invalid characters will
+  # result in an ArgumentError. Converting `nil` generates a TypeError. Exceptions
+  # can be suppressed by passing <code>exception: false</code>.
   #
   #     Float(1)                 #=> 1.0
   #     Float("123.456")         #=> 123.456
@@ -515,7 +522,8 @@ module Kernel : BasicObject
   #     *   A hash, returns `object`.
   #     *   An empty array or `nil`, returns an empty hash.
   #
-  # *   Otherwise, if `object.to_hash` returns a hash, returns that hash.
+  # *   Otherwise, if <code>object.to_hash</code> returns a hash, returns that
+  #     hash.
   # *   Otherwise, returns TypeError.
   #
   # Examples:
@@ -621,7 +629,7 @@ module Kernel : BasicObject
   #   - Rational(x, y, exception: true)  ->  rational or nil
   #   - Rational(arg, exception: true)   ->  rational or nil
   # -->
-  # Returns `x/y` or `arg` as a Rational.
+  # Returns <code>x/y</code> or `arg` as a Rational.
   #
   #     Rational(2, 3)   #=> (2/3)
   #     Rational(5)      #=> (5/1)
@@ -697,7 +705,7 @@ module Kernel : BasicObject
   # Returns the canonicalized absolute path of the directory of the file from
   # which this method is called. It means symlinks in the path is resolved. If
   # `__FILE__` is `nil`, it returns `nil`. The return value equals to
-  # `File.dirname(File.realpath(__FILE__))`.
+  # <code>File.dirname(File.realpath(__FILE__))</code>.
   #
   def self?.__dir__: () -> String?
 
@@ -714,20 +722,20 @@ module Kernel : BasicObject
   #   rdoc-file=io.c
   #   - `command` -> string
   # -->
-  # Returns the `$stdout` output from running `command` in a subshell; sets global
-  # variable `$?` to the process status.
+  # Returns the <code>$stdout</code> output from running `command` in a subshell;
+  # sets global variable <code>$?</code> 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:
   #
   #     $ `date`                 # => "Wed Apr  9 08:56:30 CDT 2003\n"
   #     $ `echo oops && exit 99` # => "oops\n"
   #     $ $?                     # => #<Process::Status: pid 17088 exit 99>
-  #     $ $?.status              # => 99>
+  #     $ $?.exitstatus          # => 99
   #
-  # The built-in syntax `%x{...}` uses this method.
+  # The built-in syntax <code>%x{...}</code> uses this method.
   #
   def self?.`: (String arg0) -> String
 
@@ -736,7 +744,8 @@ module Kernel : BasicObject
   #   - abort
   #   - Process.abort(msg = nil)
   # -->
-  # Terminates execution immediately, effectively by calling `Kernel.exit(false)`.
+  # Terminates execution immediately, effectively by calling
+  # <code>Kernel.exit(false)</code>.
   #
   # If string argument `msg` is given, it is written to STDERR prior to
   # termination; otherwise, if an exception was raised, prints its message and
@@ -759,7 +768,7 @@ module Kernel : BasicObject
   #     do_at_exit("goodbye ")
   #     exit
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     goodbye cruel world
   #
@@ -777,6 +786,8 @@ module Kernel : BasicObject
   # If *const* is defined as autoload, the file name to be loaded is replaced with
   # *filename*.  If *const* is defined but not as autoload, does nothing.
   #
+  # Files that are currently being loaded must not be registered for autoload.
+  #
   def self?.autoload: (interned _module, String filename) -> NilClass
 
   # <!--
@@ -984,13 +995,14 @@ module Kernel : BasicObject
   #     end
   #     # => #<RuntimeError: RuntimeError>
   #
-  # If keyword argument `cause` is not given, the cause is the value of `$!`.
+  # If keyword argument `cause` is not given, the cause is the value of
+  # <code>$!</code>.
   #
   # See [Cause](rdoc-ref:exceptions.md@Cause).
   #
   # In the alternate calling sequence, where argument `exception` *not* given,
-  # raises a new exception of the class given by `$!`, or of class RuntimeError if
-  # `$!` is `nil`:
+  # raises a new exception of the class given by <code>$!</code>, or of class
+  # RuntimeError if <code>$!</code> is `nil`:
   #
   #     begin
   #       raise
@@ -1002,9 +1014,11 @@ 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
+                | (_Exception exception, ?string | _ToS message, ?String | Array[String] | Array[Thread::Backtrace::Location] | nil backtrace, ?cause: Exception?) -> bot
                 | (_Exception exception, ?cause: Exception?, **untyped) -> bot
 
   # <!--
@@ -1090,13 +1104,14 @@ module Kernel : BasicObject
   #     end
   #     # => #<RuntimeError: RuntimeError>
   #
-  # If keyword argument `cause` is not given, the cause is the value of `$!`.
+  # If keyword argument `cause` is not given, the cause is the value of
+  # <code>$!</code>.
   #
   # See [Cause](rdoc-ref:exceptions.md@Cause).
   #
   # In the alternate calling sequence, where argument `exception` *not* given,
-  # raises a new exception of the class given by `$!`, or of class RuntimeError if
-  # `$!` is `nil`:
+  # raises a new exception of the class given by <code>$!</code>, or of class
+  # RuntimeError if <code>$!</code> is `nil`:
   #
   #     begin
   #       raise
@@ -1108,6 +1123,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
@@ -1116,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).
   #
   def self?.format: (String format, *untyped args) -> String
 
@@ -1127,7 +1144,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
 
@@ -1139,29 +1156,29 @@ module Kernel : BasicObject
   #   - gets(limit [, getline_args])      -> string or nil
   #   - gets(sep, limit [, getline_args]) -> string or nil
   # -->
-  # Returns (and assigns to `$_`) the next line from the list of files in `ARGV`
-  # (or `$*`), or from standard input if no files are present on the command line.
-  # Returns `nil` at end of file. The optional argument specifies the record
-  # separator. The separator is included with the contents of each record. A
-  # separator of `nil` reads the entire contents, and a zero-length separator
-  # reads the input one paragraph at a time, where paragraphs are divided by two
-  # consecutive newlines.  If the first argument is an integer, or optional second
-  # argument is given, the returning string would not be longer than the given
-  # value in bytes.  If multiple filenames are present in `ARGV`, `gets(nil)` will
-  # read the contents one file at a time.
+  # Returns (and assigns to <code>$_</code>) the next line from the list of files
+  # in `ARGV` (or <code>$*</code>), or from standard input if no files are present
+  # on the command line. Returns `nil` at end of file. The optional argument
+  # specifies the record separator. The separator is included with the contents of
+  # each record. A separator of `nil` reads the entire contents, and a zero-length
+  # separator reads the input one paragraph at a time, where paragraphs are
+  # divided by two consecutive newlines.  If the first argument is an integer, or
+  # optional second argument is given, the returning string would not be longer
+  # than the given value in bytes.  If multiple filenames are present in `ARGV`,
+  # <code>gets(nil)</code> will read the contents one file at a time.
   #
   #     ARGV << "testfile"
   #     print while gets
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     This is line one
   #     This is line two
   #     This is line three
   #     And so on...
   #
-  # The style of programming using `$_` as an implicit parameter is gradually
-  # losing favor in the Ruby community.
+  # The style of programming using <code>$_</code> as an implicit parameter is
+  # gradually losing favor in the Ruby community.
   #
   def self?.gets: (?String sep, ?Integer limit, ?chomp: boolish) -> String?
 
@@ -1170,8 +1187,9 @@ module Kernel : BasicObject
   #   - global_variables    -> array
   # -->
   # Returns an array of the names of global variables. This includes special
-  # regexp global variables such as `$~` and `$+`, but does not include the
-  # numbered regexp global variables (`$1`, `$2`, etc.).
+  # regexp global variables such as <code>$~</code> and <code>$+</code>, but does
+  # not include the numbered regexp global variables (<code>$1</code>,
+  # <code>$2</code>, etc.).
   #
   #     global_variables.grep /std/   #=> [:$stdin, :$stdout, :$stderr]
   #
@@ -1190,10 +1208,10 @@ module Kernel : BasicObject
   # the file will be loaded using the relative path from the current directory.
   #
   # Otherwise, the file will be searched for in the library directories listed in
-  # `$LOAD_PATH` (`$:`). If the file is found in a directory, it will attempt to
-  # load the file relative to that directory.  If the file is not found in any of
-  # the directories in `$LOAD_PATH`, the file will be loaded using the relative
-  # path from the current directory.
+  # <code>$LOAD_PATH</code> (<code>$:</code>). If the file is found in a
+  # directory, it will attempt to load the file relative to that directory.  If
+  # the file is not found in any of the directories in <code>$LOAD_PATH</code>,
+  # the file will be loaded using the relative path from the current directory.
   #
   # If the file doesn't exist when there is an attempt to load it, a LoadError
   # will be raised.
@@ -1218,6 +1236,7 @@ module Kernel : BasicObject
   #     loop do
   #       print "Input: "
   #       line = gets
+  #       # break if q, Q is entered or EOF signal (Ctrl-D on Unix, Ctrl-Z on windows) is sent
   #       break if !line or line =~ /^q/i
   #       # ...
   #     end
@@ -1245,9 +1264,6 @@ 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).
-  #
   # With no block given, file stream is returned:
   #
   #     open('t.txt') # => #<File:t.txt>
@@ -1270,18 +1286,19 @@ module Kernel : BasicObject
   #   rdoc-file=io.c
   #   - print(*objects) -> nil
   # -->
-  # Equivalent to `$stdout.print(*objects)`, this method is the straightforward
-  # way to write to `$stdout`.
+  # Equivalent to <code>$stdout.print(*objects)</code>, this method is the
+  # straightforward way to write to <code>$stdout</code>.
   #
-  # Writes the given objects to `$stdout`; returns `nil`. Appends the output
-  # record separator `$OUTPUT_RECORD_SEPARATOR` `$\`), if it is not `nil`.
+  # Writes the given objects to <code>$stdout</code>; returns `nil`. Appends the
+  # output record separator <code>$OUTPUT_RECORD_SEPARATOR</code>
+  # <code>$\</code>), if it is not `nil`.
   #
   # With argument `objects` given, for each object:
   #
   # *   Converts via its method `to_s` if not a string.
   # *   Writes to `stdout`.
   # *   If not the last object, writes the output field separator
-  #     `$OUTPUT_FIELD_SEPARATOR` (`$,` if it is not `nil`.
+  #     <code>$OUTPUT_FIELD_SEPARATOR</code> (<code>$,</code> if it is not `nil`.
   #
   # With default separators:
   #
@@ -1306,8 +1323,8 @@ module Kernel : BasicObject
   #
   #     0,0.0,0/1,0+0i,zero,zero
   #
-  # With no argument given, writes the content of `$_` (which is usually the most
-  # recent user input):
+  # With no argument given, writes the content of <code>$_</code> (which is
+  # usually the most recent user input):
   #
   #     gets  # Sets $_ to the most recent user input.
   #     print # Prints $_.
@@ -1324,7 +1341,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:
@@ -1429,7 +1446,7 @@ module Kernel : BasicObject
   # -->
   # prints arguments in pretty form.
   #
-  # `#pp` returns argument(s).
+  # <code>#pp</code> returns argument(s).
   #
   def self?.pp: [T] (T arg0) -> T
               | (untyped, untyped, *untyped) -> Array[untyped]
@@ -1439,19 +1456,20 @@ module Kernel : BasicObject
   #   rdoc-file=random.c
   #   - rand(max=0)    -> number
   # -->
-  # If called without an argument, or if `max.to_i.abs == 0`, rand returns a
-  # pseudo-random floating point number between 0.0 and 1.0, including 0.0 and
-  # excluding 1.0.
+  # If called without an argument, or if <code>max.to_i.abs == 0</code>, rand
+  # returns a pseudo-random floating point number between 0.0 and 1.0, including
+  # 0.0 and excluding 1.0.
   #
   #     rand        #=> 0.2725926052826416
   #
-  # When `max.abs` is greater than or equal to 1, `rand` returns a pseudo-random
-  # integer greater than or equal to 0 and less than `max.to_i.abs`.
+  # When <code>max.abs</code> is greater than or equal to 1, `rand` returns a
+  # pseudo-random integer greater than or equal to 0 and less than
+  # <code>max.to_i.abs</code>.
   #
   #     rand(100)   #=> 12
   #
   # When `max` is a Range, `rand` returns a random number where
-  # `range.member?(number) == true`.
+  # <code>range.member?(number) == true</code>.
   #
   # Negative or floating point values for `max` are allowed, but may give
   # surprising results.
@@ -1463,7 +1481,9 @@ module Kernel : BasicObject
   # Kernel.srand may be used to ensure that sequences of random numbers are
   # reproducible between different runs of a program.
   #
-  # See also Random.rand.
+  # Related: Random.rand.
+  #     rand(100.0)        # => 64 (Integer because max.to_i is 100)
+  #     Random.rand(100.0) # => 30.315320967824523
   #
   def self?.rand: (?0) -> Float
                 | (int arg0) -> Integer
@@ -1550,7 +1570,7 @@ module Kernel : BasicObject
   # When RubyGems is required, Kernel#require is replaced with our own which is
   # capable of loading gems on demand.
   #
-  # When you call `require 'x'`, this is what happens:
+  # When you call <code>require 'x'</code>, this is what happens:
   # *   If the file can be loaded from the existing Ruby loadpath, it is.
   # *   Otherwise, installed gems are searched for a file that matches. If it's
   #     found in gem 'y', that gem is activated (added to the loadpath).
@@ -1585,7 +1605,9 @@ module Kernel : BasicObject
   # IO objects.
   #
   # Argument `timeout` is a numeric value (such as integer or float) timeout
-  # interval in seconds.
+  # interval in seconds. `timeout` can also be `nil` or
+  # <code>Float::INFINITY</code>. `nil` and <code>Float::INFINITY</code> means no
+  # timeout.
   #
   # The method monitors the IO objects given in all three arrays, waiting for some
   # to be ready; returns a 3-element array whose elements are:
@@ -1660,8 +1682,8 @@ module Kernel : BasicObject
   #
   # The writability notified by select(2) doesn't show how many bytes are
   # writable. IO#write method blocks until given whole string is written. So,
-  # `IO#write(two or more bytes)` can block after writability is notified by
-  # IO.select.  IO#write_nonblock is required to avoid the blocking.
+  # <code>IO#write(two or more bytes)</code> can block after writability is
+  # notified by IO.select.  IO#write_nonblock is required to avoid the blocking.
   #
   # Blocking write (#write) can be emulated using #write_nonblock and IO.select as
   # follows: IO::WaitReadable should also be rescued for SSL renegotiation in
@@ -1729,11 +1751,6 @@ module Kernel : BasicObject
   def self?.sleep: (?nil) -> bot
                  | (Time::_Timeout duration) -> Integer
 
-  %a{deprecated}
-  interface _Divmod
-    def divmod: (Numeric) -> [ Numeric, Numeric ]
-  end
-
   # <!--
   #   rdoc-file=io.c
   #   - syscall(integer_callno, *arguments)   -> integer
@@ -1773,58 +1790,58 @@ module Kernel : BasicObject
   # *   Each of these tests operates only on the entity at `path0`,
   #      and returns `true` or `false`;
   #      for a non-existent entity, returns `false` (does not raise exception):
-  #  Character  |Test
-  # ------------|-------------------------------------------------------------------------
-  # <tt>'b'</tt>|Whether the entity is a block device.
-  # <tt>'c'</tt>|Whether the entity is a character device.
-  # <tt>'d'</tt>|Whether the entity is a directory.
-  # <tt>'e'</tt>|Whether the entity is an existing entity.
-  # <tt>'f'</tt>|Whether the entity is an existing regular file.
-  # <tt>'g'</tt>|Whether the entity's setgid bit is set.
-  # <tt>'G'</tt>|Whether the entity's group ownership is equal to the caller's.
-  # <tt>'k'</tt>|Whether the entity's sticky bit is set.
-  # <tt>'l'</tt>|Whether the entity is a symbolic link.
-  # <tt>'o'</tt>|Whether the entity is owned by the caller's effective uid.
-  # <tt>'O'</tt>|Like <tt>'o'</tt>, but uses the real uid (not the effective uid).
-  # <tt>'p'</tt>|Whether the entity is a FIFO device (named pipe).
-  # <tt>'r'</tt>|Whether the entity is readable by the caller's effective uid/gid.
-  # <tt>'R'</tt>|Like <tt>'r'</tt>, but uses the real uid/gid (not the effective uid/gid).
-  # <tt>'S'</tt>|Whether the entity is a socket.
-  # <tt>'u'</tt>|Whether the entity's setuid bit is set.
-  # <tt>'w'</tt>|Whether the entity is writable by the caller's effective uid/gid.
-  # <tt>'W'</tt>|Like <tt>'w'</tt>, but uses the real uid/gid (not the effective uid/gid).
-  # <tt>'x'</tt>|Whether the entity is executable by the caller's effective uid/gid.
-  # <tt>'X'</tt>|Like <tt>'x'</tt>, but uses the real uid/gid (not the effective uid/git).
-  # <tt>'z'</tt>|Whether the entity exists and is of length zero.
+  #    Character    |Test
+  # ----------------|-----------------------------------------------------------------------------
+  # <code>'b'</code>|Whether the entity is a block device.
+  # <code>'c'</code>|Whether the entity is a character device.
+  # <code>'d'</code>|Whether the entity is a directory.
+  # <code>'e'</code>|Whether the entity is an existing entity.
+  # <code>'f'</code>|Whether the entity is an existing regular file.
+  # <code>'g'</code>|Whether the entity's setgid bit is set.
+  # <code>'G'</code>|Whether the entity's group ownership is equal to the caller's.
+  # <code>'k'</code>|Whether the entity's sticky bit is set.
+  # <code>'l'</code>|Whether the entity is a symbolic link.
+  # <code>'o'</code>|Whether the entity is owned by the caller's effective uid.
+  # <code>'O'</code>|Like <code>'o'</code>, but uses the real uid (not the effective uid).
+  # <code>'p'</code>|Whether the entity is a FIFO device (named pipe).
+  # <code>'r'</code>|Whether the entity is readable by the caller's effective uid/gid.
+  # <code>'R'</code>|Like <code>'r'</code>, but uses the real uid/gid (not the effective uid/gid).
+  # <code>'S'</code>|Whether the entity is a socket.
+  # <code>'u'</code>|Whether the entity's setuid bit is set.
+  # <code>'w'</code>|Whether the entity is writable by the caller's effective uid/gid.
+  # <code>'W'</code>|Like <code>'w'</code>, but uses the real uid/gid (not the effective uid/gid).
+  # <code>'x'</code>|Whether the entity is executable by the caller's effective uid/gid.
+  # <code>'X'</code>|Like <code>'x'</code>, but uses the real uid/gid (not the effective uid/git).
+  # <code>'z'</code>|Whether the entity exists and is of length zero.
   # *   This test operates only on the entity at `path0`,
-  #      and returns an integer size or `nil`:
-  #  Character  |Test
-  # ------------|--------------------------------------------------------------------------------------------
-  # <tt>'s'</tt>|Returns positive integer size if the entity exists and has non-zero length, +nil+ otherwise.
+  #      and returns an integer size or +nil+:
+  #    Character    |Test
+  # ----------------|--------------------------------------------------------------------------------------------
+  # <code>'s'</code>|Returns positive integer size if the entity exists and has non-zero length, +nil+ otherwise.
   # *   Each of these tests operates only on the entity at `path0`,
   #      and returns a Time object;
   #      raises an exception if the entity does not exist:
-  #  Character  |Test
-  # ------------|--------------------------------------
-  # <tt>'A'</tt>|Last access time for the entity.
-  # <tt>'C'</tt>|Last change time for the entity.
-  # <tt>'M'</tt>|Last modification time for the entity.
+  #    Character    |Test
+  # ----------------|--------------------------------------
+  # <code>'A'</code>|Last access time for the entity.
+  # <code>'C'</code>|Last change time for the entity.
+  # <code>'M'</code>|Last modification time for the entity.
   # *   Each of these tests operates on the modification time (`mtime`)
   #      of each of the entities at `path0` and `path1`,
   #      and returns a `true` or `false`;
   #      returns `false` if either entity does not exist:
-  #  Character  |Test
-  # ------------|---------------------------------------------------------------
-  # <tt>'<'</tt>|Whether the `mtime` at `path0` is less than that at `path1`.
-  # <tt>'='</tt>|Whether the `mtime` at `path0` is equal to that at `path1`.
-  # <tt>'>'</tt>|Whether the `mtime` at `path0` is greater than that at `path1`.
+  #    Character    |Test
+  # ----------------|---------------------------------------------------------------
+  # <code>'<'</code>|Whether the `mtime` at `path0` is less than that at `path1`.
+  # <code>'='</code>|Whether the `mtime` at `path0` is equal to that at `path1`.
+  # <code>'>'</code>|Whether the `mtime` at `path0` is greater than that at `path1`.
   # *   This test operates on the content of each of the entities at `path0` and
   #     `path1`,
   #      and returns a `true` or `false`;
   #      returns `false` if either entity does not exist:
-  #  Character  |Test
-  # ------------|---------------------------------------------
-  # <tt>'-'</tt>|Whether the entities exist and are identical.
+  #    Character    |Test
+  # ----------------|---------------------------------------------
+  # <code>'-'</code>|Whether the entities exist and are identical.
   #
   def self?.test: (String | Integer cmd, String | IO file1, ?String | IO file2) -> (TrueClass | FalseClass | Time | nil | Integer)
 
@@ -1843,14 +1860,14 @@ module Kernel : BasicObject
   #   rdoc-file=warning.rb
   #   - warn(*msgs, uplevel: nil, category: nil)   -> nil
   # -->
-  # If warnings have been disabled (for example with the `-W0` flag), does
-  # nothing.  Otherwise, converts each of the messages to strings, appends a
+  # If warnings have been disabled (for example with the <code>-W0</code> flag),
+  # does nothing.  Otherwise, converts each of the messages to strings, appends a
   # newline character to the string if the string does not end in a newline, and
   # calls Warning.warn with the string.
   #
   #     warn("warning 1", "warning 2")
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     warning 1
   #     warning 2
@@ -1870,12 +1887,13 @@ module Kernel : BasicObject
   #
   #     bar
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     baz.rb:6: warning: invalid call to foo
   #
   # If `category` keyword argument is given, passes the category to
-  # `Warning.warn`.  The category given must be one of the following categories:
+  # <code>Warning.warn</code>.  The category given must be one of the following
+  # categories:
   #
   # :deprecated
   # :   Used for warning for deprecated functionality that may be removed in the
@@ -1901,7 +1919,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
@@ -1920,7 +1938,7 @@ module Kernel : BasicObject
   #     word or special built-in, or if it contains one or more meta characters.
   # *   `exe_path` otherwise.
   #
-  # **Argument `command_line`**
+  # <strong>Argument `command_line`</strong>
   #
   # String argument `command_line` is a command line to be passed to a shell; it
   # must begin with a shell reserved word, begin with a special built-in, or
@@ -1943,7 +1961,7 @@ module Kernel : BasicObject
   #
   # Raises an exception if the new process could not execute.
   #
-  # **Argument `exe_path`**
+  # <strong>Argument `exe_path`</strong>
   #
   # Argument `exe_path` is one of the following:
   #
@@ -1977,8 +1995,8 @@ module Kernel : BasicObject
   #
   # Raises an exception if the new process could not execute.
   #
-  def self?.exec: (String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> bot
-                | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> bot
+  def self?.exec: (String command, *String args, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: bool, ?chdir: String) -> bot
+                | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: bool, ?chdir: String) -> bot
 
   type redirect_fd = Integer | :in | :out | :err | IO | String | [ String ] | [ String, string | int ] | [ String, string | int, int ] | [ :child, int ] | :close
 
@@ -1993,7 +2011,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.
@@ -2020,7 +2038,7 @@ module Kernel : BasicObject
   #     word or special built-in, or if it contains one or more meta characters.
   # *   `exe_path` otherwise.
   #
-  # **Argument `command_line`**
+  # <strong>Argument `command_line`</strong>
   #
   # String argument `command_line` is a command line to be passed to a shell; it
   # must begin with a shell reserved word, begin with a special built-in, or
@@ -2049,7 +2067,7 @@ module Kernel : BasicObject
   #
   # Raises an exception if the new process could not execute.
   #
-  # **Argument `exe_path`**
+  # <strong>Argument `exe_path`</strong>
   #
   # Argument `exe_path` is one of the following:
   #
@@ -2082,8 +2100,8 @@ module Kernel : BasicObject
   #
   # Raises an exception if the new process could not execute.
   #
-  def self?.spawn: (String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> Integer
-                 | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> Integer
+  def self?.spawn: (String command, *String args, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: bool, ?chdir: String) -> Integer
+                 | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: bool, ?chdir: String) -> Integer
 
   # <!--
   #   rdoc-file=process.c
@@ -2096,7 +2114,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:
   #
@@ -2107,7 +2125,7 @@ module Kernel : BasicObject
   # Raises an exception (instead of returning `false` or `nil`) if keyword
   # argument `exception` is set to `true`.
   #
-  # Assigns the command's error status to `$?`.
+  # Assigns the command's error status to <code>$?</code>.
   #
   # The new process is created using the [system system
   # call](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/functions/s
@@ -2126,7 +2144,7 @@ module Kernel : BasicObject
   #     word or special built-in, or if it contains one or more meta characters.
   # *   `exe_path` otherwise.
   #
-  # **Argument `command_line`**
+  # <strong>Argument `command_line`</strong>
   #
   # String argument `command_line` is a command line to be passed to a shell; it
   # must begin with a shell reserved word, begin with a special built-in, or
@@ -2138,7 +2156,7 @@ module Kernel : BasicObject
   #     system('date > /nop/date.tmp')                  # => false
   #     system('date > /nop/date.tmp', exception: true) # Raises RuntimeError.
   #
-  # Assigns the command's error status to `$?`:
+  # Assigns the command's error status to <code>$?</code>:
   #
   #     system('exit')                             # => true  # Built-in.
   #     $?                                         # => #<Process::Status: pid 640610 exit 0>
@@ -2158,7 +2176,7 @@ module Kernel : BasicObject
   #
   # Raises an exception if the new process could not execute.
   #
-  # **Argument `exe_path`**
+  # <strong>Argument `exe_path`</strong>
   #
   # Argument `exe_path` is one of the following:
   #
@@ -2175,7 +2193,7 @@ module Kernel : BasicObject
   #
   #     Mon Aug 28 11:43:10 AM CDT 2023
   #
-  # Assigns the command's error status to `$?`:
+  # Assigns the command's error status to <code>$?</code>:
   #
   #     system('/usr/bin/date') # => true
   #     $?                      # => #<Process::Status: pid 645605 exit 0>
@@ -2200,8 +2218,51 @@ module Kernel : BasicObject
   #
   # Raises an exception if the new process could not execute.
   #
-  def self?.system: (String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String, ?exception: bool) -> (NilClass | FalseClass | TrueClass)
-                  | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String, ?exception: bool) -> (NilClass | FalseClass | TrueClass)
+  def self?.system: (String command, *String args, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: bool, ?chdir: String, ?exception: bool) -> (NilClass | FalseClass | TrueClass)
+                  | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: bool, ?chdir: String, ?exception: bool) -> (NilClass | FalseClass | TrueClass)
+
+  # An interface used with `trace_var` (and `untrace_var`) for custom command types.
+  interface _Tracer
+    # Called whenever the global variable that's being traced changes; the argument is the new value.
+    def call: (untyped argument) -> void
+  end
+
+  # <!--
+  #   rdoc-file=eval.c
+  #   - trace_var(symbol, cmd )             -> nil
+  #   - trace_var(symbol) {|val| block }    -> nil
+  # -->
+  # Controls tracing of assignments to global variables. The parameter `symbol`
+  # identifies the variable (as either a string name or a symbol identifier).
+  # *cmd* (which may be a string or a `Proc` object) or block is executed whenever
+  # the variable is assigned. The block or `Proc` object receives the variable's
+  # new value as a parameter. Also see #untrace_var.
+  #
+  #     trace_var :$_, proc {|v| puts "$_ is now '#{v}'" }
+  #     $_ = "hello"
+  #     $_ = ' there'
+  #
+  # <em>produces:</em>
+  #
+  #     $_ is now 'hello'
+  #     $_ is now ' there'
+  #
+  def self?.trace_var: (interned name, String | _Tracer cmd) -> nil
+                     | (interned name) { (untyped value) -> void } -> nil
+                     | (interned name, nil) -> Array[String | _Tracer]?
+
+  # <!--
+  #   rdoc-file=eval.c
+  #   - untrace_var(symbol [, cmd] )   -> array or nil
+  # -->
+  # Removes tracing for the specified command on the given global variable and
+  # returns `nil`. If no command is specified, removes all tracing for that
+  # variable and returns an array containing the commands actually removed.
+  #
+  def self?.untrace_var: (interned name, ?nil) -> Array[String | _Tracer]
+                       | (interned name, String cmd) -> [String]?
+                       | [T < _Tracer] (interned name, T cmd) -> [T]?
+                       | (interned name, untyped cmd) -> nil
 
   # <!--
   #   rdoc-file=object.c
@@ -2248,8 +2309,8 @@ module Kernel : BasicObject
   # -->
   # Produces a shallow copy of *obj*---the instance variables of *obj* are copied,
   # but not the objects they reference. #clone copies the frozen value state of
-  # *obj*, unless the `:freeze` keyword argument is given with a false or true
-  # value. See also the discussion under Object#dup.
+  # *obj*, unless the <code>:freeze</code> keyword argument is given with a false
+  # or true value. See also the discussion under Object#dup.
   #
   #     class Klass
   #        attr_accessor :str