rbs 4.0.0.dev.4 → 4.0.0

data/stdlib/strscan/0/string_scanner.rbs

@@ -1,6 +1,7 @@
 # <!-- rdoc-file=ext/strscan/strscan.c -->
 # Class `StringScanner` supports processing a stored string as a stream;
-# this code creates a new `StringScanner` object with string `'foobarbaz'`:
+# this code creates a new `StringScanner` object with string
+# <code>'foobarbaz'</code>:
 #     require 'strscan'
 # scanner = StringScanner.new('foobarbaz')
 #
@@ -19,16 +20,16 @@
 # ENGLISH_TEXT = 'Hello'
 #
 # Some examples here assume that certain helper methods are defined:
-# *   `put_situation(scanner)`:
+# *   <code>put_situation(scanner)</code>:
 #      Displays the values of the scanner's
 #      methods #pos, #charpos, #rest, and #rest_size.
-# *   `put_match_values(scanner)`:
+# *   <code>put_match_values(scanner)</code>:
 #      Displays the scanner's [match
 #     values](rdoc-ref:StringScanner@Match+Values).
-# *   `match_values_cleared?(scanner)`:
+# *   <code>match_values_cleared?(scanner)</code>:
 #      Returns whether the scanner's [match
 #     values](rdoc-ref:StringScanner@Match+Values) are cleared.
-# See examples [[here]](ext/strscan/helper_methods_md.html).
+# See examples at [helper methods](helper_methods.md).
 # ## The `StringScanner` Object
 # This code creates a `StringScanner` object
 # (we'll call it simply a *scanner*),
@@ -45,7 +46,7 @@
 # The scanner has:
 # *   A *stored string*, which is:
 #     *   Initially set by StringScanner.new(string) to the given `string`
-#          (`'foobarbaz'` in the example above).
+#          (<code>'foobarbaz'</code> in the example above).
 #     *   Modifiable by methods #string=(new_string) and #concat(more_string).
 #     *   Returned by method #string.
 #     More at [Stored String](rdoc-ref:StringScanner@Stored+String) below.
@@ -63,7 +64,7 @@
 #      which is a trailing substring of the stored string;
 #      it extends from the current position to the end of the stored string:
 #     *   Initially set by StringScanner.new(string) to the given `string`
-#          (`'foobarbaz'` in the example above).
+#          (<code>'foobarbaz'</code> in the example above).
 #     *   Returned by method #rest.
 #     *   Modified by any modification to either the stored string or the
 #         position.
@@ -85,10 +86,10 @@
 # and a zero-based *character position*.
 # Each of these methods explicitly sets positions:
 #          Method         |                         Effect
-# ------------------------|--------------------------------------------------------
-#          #reset         |Sets both positions to zero (begining of stored string).
+# ------------------------|---------------------------------------------------------
+#          #reset         |Sets both positions to zero (beginning of stored string).
 #        #terminate       |  Sets both positions to the end of the stored string.
-# #pos=(new_byte_position)|    Sets byte position; adjusts character position.
+# #pos=(new_byte_position)|     Sets byte position; adjusts character position.
 # ### Byte Position (Position)
 # The byte position (or simply *position*)
 # is a zero-based index into the bytes in the scanner's stored string;
@@ -96,7 +97,7 @@
 # When the byte position is:
 # *   Zero (at the beginning), the target substring is the entire stored string.
 # *   Equal to the size of the stored string (at the end),
-#      the target substring is the empty string `''`.
+#      the target substring is the empty string <code>''</code>.
 # To get or set the byte position:
 # *   #pos: returns the byte position.
 # *   #pos=(new_pos): sets the byte position.
@@ -120,7 +121,7 @@
 # *   #charpos: the [character
 #     position](rdoc-ref:StringScanner@Character+Position).
 # *   #rest: the [target substring](rdoc-ref:StringScanner@Target+Substring).
-# *   #rest_size: `rest.size`.
+# *   #rest_size: <code>rest.size</code>.
 # ### Character Position
 # The character position is a zero-based index into the *characters*
 # in the stored string;
@@ -159,7 +160,7 @@
 # #   rest_size: 12
 #
 # ## Target Substring
-# The target substring is the the part of the [stored
+# The target substring is the part of the [stored
 # string](rdoc-ref:StringScanner@Stored+String)
 # that extends from the current [byte
 # position](rdoc-ref:StringScanner@Byte+Position+-28Position-29) to the end of
@@ -290,7 +291,7 @@
 # generally contain the results of the most recent attempted match.
 # Each match value may be thought of as:
 # *   *Clear*: Initially, or after an unsuccessful match attempt:
-#      usually, `false`, `nil`, or `{}`.
+#      usually, `false`, `nil`, or <code>{}</code>.
 # *   *Set*: After a successful match attempt:
 #      `true`, string, array, or hash.
 # Each of these methods clears match values:
@@ -327,10 +328,10 @@
 #     Method     |          Return After Match           |Return After No Match
 # ---------------|---------------------------------------|---------------------
 #      #size     |     Count of captured substrings.     |       +nil+.
-#     #[](n)     |   <tt>n</tt>th captured substring.    |       +nil+.
+#     #[](n)     |       `n`th captured substring.       |       +nil+.
 #    #captures   |   Array of all captured substrings.   |       +nil+.
 # #values_at(*n) |Array of specified captured substrings.|       +nil+.
-# #named_captures|        Hash of named captures.        |    <tt>{}</tt>.
+# #named_captures|        Hash of named captures.        |  <code>{}</code>.
 #
 # See examples below.
 # #### Match Values Examples
@@ -401,7 +402,7 @@
 # ## Fixed-Anchor Property
 # Pattern matching in `StringScanner` is the same as in Ruby's,
 # except for its fixed-anchor property,
-# which determines the meaning of `'\A'`:
+# which determines the meaning of <code>'\A'</code>:
 # *   `false` (the default): matches the current byte position.
 #         scanner = StringScanner.new('foobar')
 # scanner.scan(/\A./) # => "f"
@@ -486,13 +487,13 @@ class StringScanner
   # scanner[:day]   # => "12"
   # scanner[:nope]  # => nil
   #
-  # When there are no captures, only `[0]` returns non-`nil`:
+  # When there are no captures, only <code>[0]</code> returns non-`nil`:
   #     scanner = StringScanner.new('foobarbaz')
   # scanner.exist?(/bar/)
   # scanner[0] # => "bar"
   # scanner[1] # => nil
   #
-  # For a failed match, even `[0]` returns `nil`:
+  # For a failed match, even <code>[0]</code> returns `nil`:
   #     scanner.scan(/nope/) # => nil
   # scanner[0]           # => nil
   # scanner[1]           # => nil
@@ -539,7 +540,8 @@ class StringScanner
   #   - captures -> substring_array or nil
   # -->
   # Returns the array of [captured match
-  # values](rdoc-ref:StringScanner@Captured+Match+Values) at indexes `(1..)`
+  # values](rdoc-ref:StringScanner@Captured+Match+Values) at indexes
+  # <code>(1..)</code>
   # if the most recent match attempt succeeded, or `nil` otherwise:
   #     scanner = StringScanner.new('Fri Dec 12 1975 14:39')
   # scanner.captures         # => nil
@@ -999,7 +1001,7 @@ class StringScanner
   #   rdoc-file=ext/strscan/strscan.c
   #   - peek(length) -> substring
   # -->
-  # Returns the substring `string[pos, length]`;
+  # Returns the substring <code>string[pos, length]</code>;
   # does not update [match values](rdoc-ref:StringScanner@Match+Values) or
   # [positions](rdoc-ref:StringScanner@Positions):
   #     scanner = StringScanner.new('foobarbaz')
@@ -1151,7 +1153,7 @@ class StringScanner
   # Sets both [byte position](rdoc-ref:StringScanner@Byte+Position+-28Position-29)
   # and [character position](rdoc-ref:StringScanner@Character+Position) to zero,
   # and clears [match values](rdoc-ref:StringScanner@Match+Values);
-  # returns `self`:
+  # returns +self+:
   #     scanner = StringScanner.new('foobarbaz')
   # scanner.exist?(/bar/)          # => 6
   # scanner.reset                  # => #<StringScanner 0/9 @ "fooba...">
@@ -1237,7 +1239,7 @@ class StringScanner
   # *   Returns the matched substring.
   # *   Increments the [byte
   #     position](rdoc-ref:StringScanner@Byte+Position+-28Position-29) by
-  #     `substring.bytesize`,
+  #     <code>substring.bytesize</code>,
   #      and may increment the [character
   #     position](rdoc-ref:StringScanner@Character+Position).
   # *   Sets [match values](rdoc-ref:StringScanner@Match+Values).
@@ -1517,7 +1519,7 @@ class StringScanner
   # call-seq:
   #  terminate -> self
   # Sets the scanner to end-of-string;
-  # returns `self`:
+  # returns +self+:
   # *   Sets both [positions](rdoc-ref:StringScanner@Positions) to end-of-stream.
   # *   Clears [match values](rdoc-ref:StringScanner@Match+Values).
   #     scanner = StringScanner.new(HIRAGANA_TEXT)
@@ -1578,7 +1580,7 @@ class StringScanner
   #   - values_at(*specifiers) -> array_of_captures or nil
   # -->
   # Returns an array of captured substrings, or `nil` of none.
-  # For each `specifier`, the returned substring is `[specifier]`;
+  # For each `specifier`, the returned substring is <code>[specifier]</code>;
   # see #[].
   #     scanner = StringScanner.new('Fri Dec 12 1975 14:39')
   # pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /

data/stdlib/tempfile/0/tempfile.rbs

@@ -19,7 +19,7 @@
 #     require 'tempfile'
 #
 #     # Tempfile.create with a block
-#     # The filename are choosen automatically.
+#     # The filename are chosen automatically.
 #     # (You can specify the prefix and suffix of the filename by an optional argument.)
 #     Tempfile.create {|f|
 #       f.puts "foo"
@@ -159,7 +159,7 @@ class Tempfile < File
   # *   Generated filename is unique in that directory.
   # *   Permissions are `0600`; see [File
   #     Permissions](rdoc-ref:File@File+Permissions).
-  # *   Mode is `'w+'` (read/write mode, positioned at the end).
+  # *   Mode is <code>'w+'</code> (read/write mode, positioned at the end).
   #
   # The temporary file removal depends on the keyword argument `anonymous` and
   # whether a block is given or not. See the description about the `anonymous`
@@ -206,8 +206,8 @@ class Tempfile < File
   #
   #         Tempfile.create('foo') # => #<File:/tmp/foo20220505-9795-1gok8l9>
   #
-  # *   An array of two strings `[prefix, suffix]`: the generated filename begins
-  #     with `prefix` and ends with `suffix`:
+  # *   An array of two strings <code>[prefix, suffix]</code>: the generated
+  #     filename begins with `prefix` and ends with `suffix`:
   #
   #         Tempfile.create(%w/foo .jpg/) # => #<File:/tmp/foo20220505-17839-tnjchh.jpg>
   #
@@ -226,16 +226,19 @@ class Tempfile < File
   #
   # The keyword argument `anonymous` specifies when the file is removed.
   #
-  # *   `anonymous=false` (default) without a block: the file is not removed.
-  # *   `anonymous=false` (default) with a block: the file is removed after the
-  #     block exits.
-  # *   `anonymous=true` without a block: the file is removed before returning.
-  # *   `anonymous=true` with a block: the file is removed before the block is
-  #     called.
+  # *   <code>anonymous=false</code> (default) without a block: the file is not
+  #     removed.
+  # *   <code>anonymous=false</code> (default) with a block: the file is removed
+  #     after the block exits.
+  # *   <code>anonymous=true</code> without a block: the file is removed before
+  #     returning.
+  # *   <code>anonymous=true</code> with a block: the file is removed before the
+  #     block is called.
   #
-  # In the first case (`anonymous=false` without a block), the file is not removed
-  # automatically. It should be explicitly closed. It can be used to rename to the
-  # desired filename. If the file is not needed, it should be explicitly removed.
+  # In the first case (<code>anonymous=false</code> without a block), the file is
+  # not removed automatically. It should be explicitly closed. It can be used to
+  # rename to the desired filename. If the file is not needed, it should be
+  # explicitly removed.
   #
   # The File#path method of the created file object returns the temporary
   # directory with a trailing slash when `anonymous` is true.
@@ -248,8 +251,8 @@ class Tempfile < File
   #
   # Implementation note:
   #
-  # The keyword argument +anonymous=true+ is implemented using FILE_SHARE_DELETE
-  # on Windows. O_TMPFILE is used on Linux.
+  # The keyword argument <code>anonymous=true</code> is implemented using
+  # `FILE_SHARE_DELETE` on Windows. `O_TMPFILE` is used on Linux.
   #
   # Related: Tempfile.new.
   #
@@ -283,7 +286,8 @@ class Tempfile < File
   #
   # The call returns the value of the block.
   #
-  # In any case, all arguments (`*args`) will be passed to Tempfile.new.
+  # In any case, all arguments (<code>*args</code>) will be passed to
+  # Tempfile.new.
   #
   #     Tempfile.open('foo', '/home/temp') do |f|
   #        # ... do something with f ...
@@ -318,7 +322,7 @@ class Tempfile < File
   #   - close!()
   # -->
   # Closes and unlinks (deletes) the file. Has the same effect as called
-  # `close(true)`.
+  # <code>close(true)</code>.
   #
   def close!: () -> void
 
@@ -422,7 +426,7 @@ class Tempfile < File
   # If possible, consider instead using Tempfile.create, which:
   #
   # *   Avoids the performance cost of delegation, incurred when Tempfile.new
-  #     calls its superclass `DelegateClass(File)`.
+  #     calls its superclass <code>DelegateClass(File)</code>.
   # *   Does not rely on a finalizer to close and unlink the file, which can be
   #     unreliable.
   #
@@ -433,7 +437,7 @@ class Tempfile < File
   # *   Generated filename is unique in that directory.
   # *   Permissions are `0600`; see [File
   #     Permissions](rdoc-ref:File@File+Permissions).
-  # *   Mode is `'w+'` (read/write mode, positioned at the end).
+  # *   Mode is <code>'w+'</code> (read/write mode, positioned at the end).
   #
   # The underlying file is removed when the Tempfile object dies and is reclaimed
   # by the garbage collector.
@@ -454,8 +458,8 @@ class Tempfile < File
   #
   #         Tempfile.new('foo') # => #<Tempfile:/tmp/foo20220505-17839-1whk2f>
   #
-  # *   An array of two strings `[prefix, suffix]`: the generated filename begins
-  #     with `prefix` and ends with `suffix`:
+  # *   An array of two strings <code>[prefix, suffix]</code>: the generated
+  #     filename begins with `prefix` and ends with `suffix`:
   #
   #         Tempfile.new(%w/foo .jpg/) # => #<Tempfile:/tmp/foo20220505-17839-58xtfi.jpg>
   #

data/stdlib/time/0/time.rbs

@@ -10,12 +10,13 @@ class Time
 
   # <!--
   #   rdoc-file=lib/time.rb
-  #   - zone_offset(zone, year=self.now.year)
+  #   - zone_offset(zone, year=nil)
   # -->
   # Return the number of seconds the specified time zone differs from UTC.
   #
-  # Numeric time zones that include minutes, such as `-10:00` or `+1330` will
-  # work, as will simpler hour-only time zones like `-10` or `+13`.
+  # Numeric time zones that include minutes, such as <code>-10:00</code> or
+  # <code>+1330</code> will work, as will simpler hour-only time zones like
+  # <code>-10</code> or <code>+13</code>.
   #
   # Textual time zones listed in ZoneOffset are also supported.
   #
@@ -120,9 +121,10 @@ class Time
   # Based on this fact, this method only understands the time zone abbreviations
   # described in RFC 822 and the system time zone, in the order named. (i.e. a
   # definition in RFC 822 overrides the system time zone definition.)  The system
-  # time zone is taken from `Time.local(year, 1, 1).zone` and `Time.local(year, 7,
-  # 1).zone`. If the extracted time zone abbreviation does not match any of them,
-  # it is ignored and the given time is regarded as a local time.
+  # time zone is taken from <code>Time.local(year, 1, 1).zone</code> and
+  # <code>Time.local(year, 7, 1).zone</code>. If the extracted time zone
+  # abbreviation does not match any of them, it is ignored and the given time is
+  # regarded as a local time.
   #
   # ArgumentError is raised if Date._parse cannot extract information from `date`
   # or if the Time class cannot represent specified date.

data/stdlib/timeout/0/timeout.rbs

@@ -26,7 +26,7 @@ module Timeout
   #   rdoc-file=lib/timeout.rb
   #   - timeout(sec, klass = nil, message = nil) { |sec| ... }
   # -->
-  # Perform an operation in a block, raising an error if it takes longer than
+  # Perform an operation in a block, raising an exception if it takes longer than
   # `sec` seconds to complete.
   #
   # `sec`
@@ -45,12 +45,20 @@ module Timeout
   #
   #
   # Returns the result of the block **if** the block completed before `sec`
-  # seconds, otherwise throws an exception, based on the value of `klass`.
+  # seconds, otherwise raises an exception, based on the value of `klass`.
   #
-  # The exception thrown to terminate the given block cannot be rescued inside the
-  # block unless `klass` is given explicitly. However, the block can use ensure to
-  # prevent the handling of the exception.  For that reason, this method cannot be
-  # relied on to enforce timeouts for untrusted blocks.
+  # The exception raised to terminate the given block is the given `klass`, or
+  # Timeout::ExitException if `klass` is not given. The reason for that behavior
+  # is that Timeout::Error inherits from RuntimeError and might be caught
+  # unexpectedly by `rescue`. Timeout::ExitException inherits from Exception so it
+  # will only be rescued by `rescue Exception`. Note that the
+  # Timeout::ExitException is translated to a Timeout::Error once it reaches the
+  # Timeout.timeout call, so outside that call it will be a Timeout::Error.
+  #
+  # In general, be aware that the code block may rescue the exception, and in such
+  # a case not respect the timeout. Also, the block can use `ensure` to prevent
+  # the handling of the exception. For those reasons, this method cannot be relied
+  # on to enforce timeouts for untrusted blocks.
   #
   # If a scheduler is defined, it will be used to handle the timeout by invoking
   # Scheduler#timeout_after.
@@ -59,11 +67,59 @@ module Timeout
   # Timeout` into your classes so they have a #timeout method, as well as a module
   # method, so you can call it directly as Timeout.timeout().
   #
+  # #### Ensuring the exception does not fire inside ensure blocks
+  #
+  # When using Timeout.timeout it can be desirable to ensure the timeout exception
+  # does not fire inside an `ensure` block. The simplest and best way to do so it
+  # to put the Timeout.timeout call inside the body of the begin/ensure/end:
+  #
+  #     begin
+  #       Timeout.timeout(sec) { some_long_operation }
+  #     ensure
+  #       cleanup # safe, cannot be interrupt by timeout
+  #     end
+  #
+  # If that is not feasible, e.g. if there are `ensure` blocks inside
+  # `some_long_operation`, they need to not be interrupted by timeout, and it's
+  # not possible to move these ensure blocks outside, one can use
+  # Thread.handle_interrupt to delay the timeout exception like so:
+  #
+  #     Thread.handle_interrupt(Timeout::Error => :never) {
+  #       Timeout.timeout(sec, Timeout::Error) do
+  #         setup # timeout cannot happen here, no matter how long it takes
+  #         Thread.handle_interrupt(Timeout::Error => :immediate) {
+  #           some_long_operation # timeout can happen here
+  #         }
+  #       ensure
+  #         cleanup # timeout cannot happen here, no matter how long it takes
+  #       end
+  #     }
+  #
+  # An important thing to note is the need to pass an exception klass to
+  # Timeout.timeout, otherwise it does not work. Specifically, using
+  # +Thread.handle_interrupt(Timeout::ExitException => ...)+ is unsupported and
+  # causes subtle errors like raising the wrong exception outside the block, do
+  # not use that.
+  #
+  # Note that Thread.handle_interrupt is somewhat dangerous because if setup or
+  # cleanup hangs then the current thread will hang too and the timeout will never
+  # fire. Also note the block might run for longer than `sec` seconds: e.g.
+  # some_long_operation executes for `sec` seconds + whatever time cleanup takes.
+  #
+  # If you want the timeout to only happen on blocking operations one can use
+  # :on_blocking instead of :immediate. However, that means if the block uses no
+  # blocking operations after `sec` seconds, the block will not be interrupted.
+  # ----
+  # <!--
+  #   rdoc-file=lib/timeout.rb
+  #   - timeout(*args, &block)
+  # -->
+  #
   def self?.timeout: [T] (Numeric? sec, ?singleton(Exception) klass, ?String message) { (Numeric sec) -> T } -> T
 end
 
 # <!-- rdoc-file=lib/timeout.rb -->
-# Internal error raised to when a timeout is triggered.
+# Internal exception raised to when a timeout is triggered.
 #
 class Timeout::ExitException < Exception
 end

data/stdlib/tsort/0/cyclic.rbs

@@ -1,5 +1,8 @@
 %a{annotate:rdoc:skip}
 module TSort[Node]
+  # <!-- rdoc-file=lib/tsort.rb -->
+  # Exception class to be raised when a cycle is found.
+  #
   class Cyclic < StandardError
   end
 end

data/stdlib/tsort/0/tsort.rbs

@@ -262,9 +262,9 @@ module TSort[Node] : TSort::_Sortable[Node]
   #   - each_strongly_connected_component() { |nodes| ... }
   # -->
   # The iterator version of the #strongly_connected_components method.
-  # *`obj*.each_strongly_connected_component` is similar to
-  # *`obj*.strongly_connected_components.each`, but modification of *obj* during
-  # the iteration may lead to unexpected results.
+  # <code><em>obj</em>.each_strongly_connected_component</code> is similar to
+  # <code><em>obj</em>.strongly_connected_components.each</code>, but modification
+  # of *obj* during the iteration may lead to unexpected results.
   #
   # #each_strongly_connected_component returns `nil`.
   #
@@ -382,9 +382,10 @@ module TSort[Node] : TSort::_Sortable[Node]
   #   rdoc-file=lib/tsort.rb
   #   - tsort_each() { |node| ... }
   # -->
-  # The iterator version of the #tsort method. *`obj*.tsort_each` is similar to
-  # *`obj*.tsort.each`, but modification of *obj* during the iteration may lead to
-  # unexpected results.
+  # The iterator version of the #tsort method.
+  # <code><em>obj</em>.tsort_each</code> is similar to
+  # <code><em>obj</em>.tsort.each</code>, but modification of *obj* during the
+  # iteration may lead to unexpected results.
   #
   # #tsort_each returns `nil`. If there is a cycle, TSort::Cyclic is raised.
   #

data/stdlib/uri/0/common.rbs

@@ -119,7 +119,7 @@ module URI
   #   rdoc-file=lib/uri/common.rb
   #   - decode_uri_component(str, enc=Encoding::UTF_8)
   # -->
-  # Like URI.decode_www_form_component, except that `'+'` is preserved.
+  # Like URI.decode_www_form_component, except that <code>'+'</code> is preserved.
   #
   def self.decode_uri_component: (String str, ?encoding enc) -> String
 
@@ -131,7 +131,8 @@ module URI
   # ASCII string.
   #
   # The method may be used to decode the body of Net::HTTPResponse object `res`
-  # for which `res['Content-Type']` is `'application/x-www-form-urlencoded'`.
+  # for which <code>res['Content-Type']</code> is
+  # <code>'application/x-www-form-urlencoded'</code>.
   #
   # The returned data is an array of 2-element subarrays; each subarray is a
   # name/value pair (both are strings). Each returned string has encoding `enc`,
@@ -175,8 +176,10 @@ module URI
   #
   # *   Preserves:
   #
-  #     *   Characters `'*'`, `'.'`, `'-'`, and `'_'`.
-  #     *   Character in ranges `'a'..'z'`, `'A'..'Z'`, and `'0'..'9'`.
+  #     *   Characters <code>'*'</code>, <code>'.'</code>, <code>'-'</code>, and
+  #         <code>'_'</code>.
+  #     *   Character in ranges <code>'a'..'z'</code>, <code>'A'..'Z'</code>, and
+  #         <code>'0'..'9'</code>.
   #
   #     Example:
   #
@@ -185,7 +188,7 @@ module URI
   #
   # *   Converts:
   #
-  #     *   Character `'+'` to character `' '`.
+  #     *   Character <code>'+'</code> to character <code>' '</code>.
   #     *   Each "percent notation" to an ASCII character.
   #
   #     Example:
@@ -193,7 +196,7 @@ module URI
   #         URI.decode_www_form_component('Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A')
   #         # => "Here are some punctuation characters: ,;?:"
   #
-  # Related: URI.decode_uri_component (preserves `'+'`).
+  # Related: URI.decode_uri_component (preserves <code>'+'</code>).
   #
   def self.decode_www_form_component: (String str, ?encoding enc) -> String
 
@@ -201,8 +204,8 @@ module URI
   #   rdoc-file=lib/uri/common.rb
   #   - encode_uri_component(str, enc=nil)
   # -->
-  # Like URI.encode_www_form_component, except that `' '` (space) is encoded as
-  # `'%20'` (instead of `'+'`).
+  # Like URI.encode_www_form_component, except that <code>' '</code> (space) is
+  # encoded as <code>'%20'</code> (instead of <code>'+'</code>).
   #
   def self.encode_uri_component: (String str, ?encoding enc) -> String
 
@@ -214,10 +217,10 @@ module URI
   # [Enumerable](rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes) `enum`.
   #
   # The result is suitable for use as form data for an HTTP request whose
-  # `Content-Type` is `'application/x-www-form-urlencoded'`.
+  # <code>Content-Type</code> is <code>'application/x-www-form-urlencoded'</code>.
   #
   # The returned string consists of the elements of `enum`, each converted to one
-  # or more URL-encoded strings, and all joined with character `'&'`.
+  # or more URL-encoded strings, and all joined with character <code>'&'</code>.
   #
   # Simple examples:
   #
@@ -248,7 +251,8 @@ module URI
   #         URI.encode_www_form([['foo', 0], ['bar', :baz, 'bat']])
   #         # => "foo=0&bar=baz"
   #
-  # *   If `ele` is an array of one element, the field is formed from `ele[0]`:
+  # *   If `ele` is an array of one element, the field is formed from
+  #     <code>ele[0]</code>:
   #
   #         URI.encode_www_form_component(ele[0])
   #
@@ -316,8 +320,10 @@ module URI
   #
   # *   Preserves:
   #
-  #     *   Characters `'*'`, `'.'`, `'-'`, and `'_'`.
-  #     *   Character in ranges `'a'..'z'`, `'A'..'Z'`, and `'0'..'9'`.
+  #     *   Characters <code>'*'</code>, <code>'.'</code>, <code>'-'</code>, and
+  #         <code>'_'</code>.
+  #     *   Character in ranges <code>'a'..'z'</code>, <code>'A'..'Z'</code>, and
+  #         <code>'0'..'9'</code>.
   #
   #     Example:
   #
@@ -326,9 +332,9 @@ module URI
   #
   # *   Converts:
   #
-  #     *   Character `' '` to character `'+'`.
+  #     *   Character <code>' '</code> to character <code>'+'</code>.
   #     *   Any other character to "percent notation"; the percent notation for
-  #         character *c* is `'%%%X' % c.ord`.
+  #         character *c* is <code>'%%%X' % c.ord</code>.
   #
   #     Example:
   #
@@ -343,7 +349,8 @@ module URI
   #
   # In either case, the returned string has forced encoding Encoding::US_ASCII.
   #
-  # Related: URI.encode_uri_component (encodes `' '` as `'%20'`).
+  # Related: URI.encode_uri_component (encodes <code>' '</code> as
+  # <code>'%20'</code>).
   #
   def self.encode_www_form_component: (_ToS str, ?encoding? enc) -> String
 
@@ -420,8 +427,8 @@ module URI
   #     URI.parse('http://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top')
   #     # => #<URI::HTTP http://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top>
   #
-  # It's recommended to first ::escape string `uri` if it may contain invalid URI
-  # characters.
+  # It's recommended to first URI::RFC2396_PARSER.escape string `uri` if it may
+  # contain invalid URI characters.
   #
   def self.parse: (_ToStr uri) -> (File | FTP | HTTP | HTTPS | LDAP | LDAPS | MailTo | WS | WSS | Generic)
 
@@ -491,7 +498,8 @@ module URI
   # Returns a new object constructed from the given `scheme`, `arguments`, and
   # `default`:
   #
-  # *   The new object is an instance of `URI.scheme_list[scheme.upcase]`.
+  # *   The new object is an instance of
+  #     <code>URI.scheme_list[scheme.upcase]</code>.
   # *   The object is initialized by calling the class initializer using `scheme`
   #     and `arguments`. See URI::Generic.new.
   #
@@ -535,6 +543,9 @@ URI::ABS_URI: Regexp
 
 URI::ABS_URI_REF: Regexp
 
+# <!-- rdoc-file=lib/uri/common.rb -->
+# The default parser instance.
+#
 URI::DEFAULT_PARSER: URI::RFC2396_Parser
 
 URI::ESCAPED: Regexp
@@ -557,6 +568,14 @@ URI::REL_URI: Regexp
 
 URI::REL_URI_REF: Regexp
 
+# <!-- rdoc-file=lib/uri/common.rb -->
+# The default parser instance for RFC 2396.
+#
+URI::RFC2396_PARSER: URI::RFC2396_Parser
+
+# <!-- rdoc-file=lib/uri/common.rb -->
+# The default parser instance for RFC 3986.
+#
 URI::RFC3986_PARSER: URI::RFC3986_Parser
 
 URI::SCHEME: Regexp
@@ -588,6 +607,7 @@ module Kernel
   # Returns a URI object derived from the given `uri`, which may be a URI string
   # or an existing URI object:
   #
+  #     require 'uri'
   #     # Returns a new URI.
   #     uri = URI('http://github.com/ruby/ruby')
   #     # => #<URI::HTTP http://github.com/ruby/ruby>
@@ -595,5 +615,7 @@ module Kernel
   #     URI(uri)
   #     # => #<URI::HTTP http://github.com/ruby/ruby>
   #
-  def self?.URI: (URI::Generic | String uri) -> URI::Generic
+  # You must require 'uri' to use this method.
+  #
+  def self?.URI: (URI::Generic | string uri) -> URI::Generic
 end