rbs 4.0.0.dev.4 → 4.1.0.pre.2

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]
+module TSort[N]
+  # <!-- rdoc-file=lib/tsort.rb -->
+  # Exception class to be raised when a cycle is found.
+  #
   class Cyclic < StandardError
   end
 end

data/stdlib/tsort/0/interfaces.rbs

@@ -1,20 +1,20 @@
 %a{annotate:rdoc:skip}
-module TSort[Node]
-  interface _Sortable[Node]
+module TSort[N]
+  interface _Sortable[N]
     # #tsort_each_node is used to iterate for all nodes over a graph.
     #
-    def tsort_each_node: () { (Node) -> void } -> void
+    def tsort_each_node: () { (N) -> void } -> void
 
     # #tsort_each_child is used to iterate for child nodes of node.
     #
-    def tsort_each_child: (Node) { (Node) -> void } -> void
+    def tsort_each_child: (N) { (N) -> void } -> void
   end
 
-  interface _EachNode[Node]
-    def call: () { (Node) -> void } -> void
+  interface _EachNode[N]
+    def call: () { (N) -> void } -> void
   end
 
-  interface _EachChild[Node]
-    def call: (Node) { (Node) -> void } -> void
+  interface _EachChild[N]
+    def call: (N) { (N) -> void } -> void
   end
 end

data/stdlib/tsort/0/tsort.rbs

@@ -113,7 +113,7 @@
 #     1.  Tarjan, "Depth First Search and Linear Graph Algorithms",
 # *SIAM Journal on Computing*, Vol. 1, No. 2, pp. 146-160, June 1972.
 #
-module TSort[Node] : TSort::_Sortable[Node]
+module TSort[N] : TSort::_Sortable[N]
   # <!--
   #   rdoc-file=lib/tsort.rb
   #   - each_strongly_connected_component(each_node, each_child) { |nodes| ... }
@@ -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`.
   #
@@ -290,8 +290,8 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     #   [2, 3]
   #     #   [1]
   #
-  def each_strongly_connected_component: () { (Array[Node]) -> void } -> void
-                                       | () -> Enumerator[Array[Node], void]
+  def each_strongly_connected_component: () { (Array[N]) -> void } -> void
+                                       | () -> Enumerator[Array[N], void]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -323,8 +323,8 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     #=> [4]
   #     #   [2, 3]
   #
-  def each_strongly_connected_component_from: (Node, ?untyped id_map, ?untyped stack) { (Array[Node]) -> void } -> void
-                                            | (Node, ?untyped id_map, ?untyped stack) -> Enumerator[Array[Node], void]
+  def each_strongly_connected_component_from: (N, ?untyped id_map, ?untyped stack) { (Array[N]) -> void } -> void
+                                            | (N, ?untyped id_map, ?untyped stack) -> Enumerator[Array[N], void]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -349,7 +349,7 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     graph = G.new({1=>[2], 2=>[3, 4], 3=>[2], 4=>[]})
   #     p graph.strongly_connected_components #=> [[4], [2, 3], [1]]
   #
-  def strongly_connected_components: () -> Array[Array[Node]]
+  def strongly_connected_components: () -> Array[Array[N]]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -376,15 +376,16 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     graph = G.new({1=>[2], 2=>[3, 4], 3=>[2], 4=>[]})
   #     p graph.tsort # raises TSort::Cyclic
   #
-  def tsort: () -> Array[Node]
+  def tsort: () -> Array[N]
 
   # <!--
   #   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.
   #
@@ -404,6 +405,6 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     #   3
   #     #   1
   #
-  def tsort_each: () { (Node) -> void } -> void
-                | () -> Enumerator[Node, void]
+  def tsort_each: () { (N) -> void } -> void
+                | () -> Enumerator[N, void]
 end

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

data/stdlib/uri/0/file.rbs

@@ -27,8 +27,8 @@ module URI
     # The components should be provided either as an Array, or as a Hash with keys
     # formed by preceding the component names with a colon.
     #
-    # If an Array is used, the components must be passed in the order `[host,
-    # path]`.
+    # If an Array is used, the components must be passed in the order <code>[host,
+    # path]</code>.
     #
     # A path from e.g. the File class should be escaped before being passed.
     #
@@ -43,7 +43,7 @@ module URI
     #       :path => '/ruby/src'})
     #     uri2.to_s  # => "file://host.example.com/ruby/src"
     #
-    #     uri3 = URI::File.build({:path => URI::escape('/path/my file.txt')})
+    #     uri3 = URI::File.build({:path => URI::RFC2396_PARSER.escape('/path/my file.txt')})
     #     uri3.to_s  # => "file:///path/my%20file.txt"
     #
     def self.build: (Array[String] args) -> URI::File

data/stdlib/uri/0/generic.rbs

@@ -145,7 +145,7 @@ module URI
     #
     # At first, tries to create a new URI::Generic instance using
     # URI::Generic::build. But, if exception URI::InvalidComponentError is raised,
-    # then it does URI::Escape.escape all URI components and tries again.
+    # then it does URI::RFC2396_PARSER.escape all URI components and tries again.
     #
     def self.build2: (Array[nil | String | Integer]) -> URI::Generic
                    | ({ scheme: String?, userinfo: String?, host: String?, port: Integer?, registry: String?, path: String?, opaque: String?, query: String?, fragment: String? }) -> instance
@@ -293,7 +293,7 @@ module URI
     # -->
     # Returns the parser to be used.
     #
-    # Unless a URI::Parser is defined, DEFAULT_PARSER is used.
+    # Unless the `parser` is defined, DEFAULT_PARSER is used.
     #
     def parser: () -> untyped
 
@@ -317,7 +317,7 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - check_scheme(v)
     # -->
-    # Checks the scheme `v` component against the URI::Parser Regexp for :SCHEME.
+    # Checks the scheme `v` component against the `parser` Regexp for :SCHEME.
     #
     def check_scheme: (String? v) -> true
 
@@ -374,8 +374,8 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - check_user(v)
     # -->
-    # Checks the user `v` component for RFC2396 compliance and against the
-    # URI::Parser Regexp for :USERINFO.
+    # Checks the user `v` component for RFC2396 compliance and against the `parser`
+    # Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined, with a user component
     # defined.
@@ -387,7 +387,7 @@ module URI
     #   - check_password(v, user = @user)
     # -->
     # Checks the password `v` component for RFC2396 compliance and against the
-    # URI::Parser Regexp for :USERINFO.
+    # `parser` Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined, with a user component
     # defined.
@@ -424,7 +424,7 @@ module URI
     #
     #     uri = URI.parse("http://john:S3nsit1ve@my.example.com")
     #     uri.user = "sam"
-    #     uri.to_s  #=> "http://sam:V3ry_S3nsit1ve@my.example.com"
+    #     uri.to_s  #=> "http://sam@my.example.com"
     #
     def user=: (String? user) -> String?
 
@@ -489,8 +489,8 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - split_userinfo(ui)
     # -->
-    # Returns the userinfo `ui` as `[user, password]` if properly formatted as
-    # 'user:password'.
+    # Returns the userinfo `ui` as <code>[user, password]</code> if properly
+    # formatted as 'user:password'.
     #
     def split_userinfo: (String ui) -> Array[String | nil]
 
@@ -530,8 +530,8 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - check_host(v)
     # -->
-    # Checks the host `v` component for RFC2396 compliance and against the
-    # URI::Parser Regexp for :HOST.
+    # Checks the host `v` component for RFC2396 compliance and against the `parser`
+    # Regexp for :HOST.
     #
     # Can not have a registry or opaque component defined, with a host component
     # defined.
@@ -611,8 +611,8 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - check_port(v)
     # -->
-    # Checks the port `v` component for RFC2396 compliance and against the
-    # URI::Parser Regexp for :PORT.
+    # Checks the port `v` component for RFC2396 compliance and against the `parser`
+    # Regexp for :PORT.
     #
     # Can not have a registry or opaque component defined, with a port component
     # defined.
@@ -670,8 +670,8 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - check_path(v)
     # -->
-    # Checks the path `v` component for RFC2396 compliance and against the
-    # URI::Parser Regexp for :ABS_PATH and :REL_PATH.
+    # Checks the path `v` component for RFC2396 compliance and against the `parser`
+    # Regexp for :ABS_PATH and :REL_PATH.
     #
     # Can not have a opaque component defined, with a path component defined.
     #
@@ -742,7 +742,7 @@ module URI
     #   - check_opaque(v)
     # -->
     # Checks the opaque `v` component for RFC2396 compliance and against the
-    # URI::Parser Regexp for :OPAQUE.
+    # `parser` Regexp for :OPAQUE.
     #
     # Can not have a host, port, user, or path component defined, with an opaque
     # component defined.
@@ -781,8 +781,7 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - fragment=(v)
     # -->
-    # Checks the fragment `v` component against the URI::Parser Regexp for
-    # :FRAGMENT.
+    # Checks the fragment `v` component against the `parser` Regexp for :FRAGMENT.
     #
     # ## Args
     #
@@ -910,6 +909,13 @@ module URI
     #
     def merge: (URI::Generic | string oth) -> URI::Generic
 
+    # <!--
+    #   rdoc-file=lib/uri/generic.rb
+    #   - +(oth)
+    # -->
+    #
+    alias + merge
+
     # :stopdoc:
     def route_from_path: (String src, String dst) -> String
 
@@ -1010,6 +1016,7 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - hash()
     # -->
+    # Returns the hash value.
     #
     def hash: () -> Integer
 
@@ -1017,6 +1024,7 @@ module URI
     #   rdoc-file=lib/uri/generic.rb
     #   - eql?(oth)
     # -->
+    # Compares with *oth* for Hash.
     #
     def eql?: (URI::Generic oth) -> bool
 

data/stdlib/uri/0/http.rbs

@@ -32,8 +32,8 @@ module URI
     # The components should be provided either as an Array, or as a Hash with keys
     # formed by preceding the component names with a colon.
     #
-    # If an Array is used, the components must be passed in the order `[userinfo,
-    # host, port, path, query, fragment]`.
+    # If an Array is used, the components must be passed in the order
+    # <code>[userinfo, host, port, path, query, fragment]</code>.
     #
     # Example:
     #

data/stdlib/uri/0/ldap.rbs

@@ -38,8 +38,8 @@ module URI
     # The components should be provided either as an Array, or as a Hash with keys
     # formed by preceding the component names with a colon.
     #
-    # If an Array is used, the components must be passed in the order `[host, port,
-    # dn, attributes, scope, filter, extensions]`.
+    # If an Array is used, the components must be passed in the order <code>[host,
+    # port, dn, attributes, scope, filter, extensions]</code>.
     #
     # Example:
     #

data/stdlib/uri/0/mailto.rbs

@@ -15,13 +15,13 @@ module URI
     # Creates a new URI::MailTo object from components, with syntax checking.
     #
     # Components can be provided as an Array or Hash. If an Array is used, the
-    # components must be supplied as `[to, headers]`.
+    # components must be supplied as <code>[to, headers]</code>.
     #
     # If a Hash is used, the keys are the component names preceded by colons.
     #
     # The headers can be supplied as a pre-encoded string, such as
-    # `"subject=subscribe&cc=address"`, or as an Array of Arrays like `[['subject',
-    # 'subscribe'], ['cc', 'address']]`.
+    # <code>"subject=subscribe&cc=address"</code>, or as an Array of Arrays like
+    # <code>[['subject', 'subscribe'], ['cc', 'address']]</code>.
     #
     # Examples:
     #