rbs 4.0.0.dev.4 → 4.0.0

data/stdlib/fileutils/0/fileutils.rbs

@@ -95,8 +95,10 @@
 # paths to filesystem entries:
 #
 # *   If the argument is a string, that value is the path.
-# *   If the argument has method `:to_path`, it is converted via that method.
-# *   If the argument has method `:to_str`, it is converted via that method.
+# *   If the argument has method <code>:to_path</code>, it is converted via that
+#     method.
+# *   If the argument has method <code>:to_str</code>, it is converted via that
+#     method.
 #
 # ## About the Examples
 #
@@ -132,7 +134,7 @@
 # TOCTTOU, vulnerability that can exist when:
 #
 # *   An ancestor directory of the entry at the target path is world writable;
-#     such directories include `/tmp`.
+#     such directories include <code>/tmp</code>.
 # *   The directory tree at the target path includes:
 #
 #     *   A world-writable descendant directory.
@@ -146,14 +148,14 @@
 # Also available are these methods, each of which calls
 # FileUtils.remove_entry_secure:
 #
-# *   FileUtils.rm_r with keyword argument `secure: true`.
-# *   FileUtils.rm_rf with keyword argument `secure: true`.
+# *   FileUtils.rm_r with keyword argument <code>secure: true</code>.
+# *   FileUtils.rm_rf with keyword argument <code>secure: true</code>.
 #
 # Finally, this method for moving entries calls FileUtils.remove_entry_secure if
 # the source and destination are on different file systems (which means that the
 # "move" is really a copy and remove):
 #
-# *   FileUtils.mv with keyword argument `secure: true`.
+# *   FileUtils.mv with keyword argument <code>secure: true</code>.
 #
 # Method FileUtils.remove_entry_secure removes securely by applying a special
 # pre-process:
@@ -184,7 +186,8 @@ module FileUtils
 
   type mode = Integer | String
 
-  type path = string | _ToPath
+  %a{deprecated: Use top-level `path` instead}
+  type path = ::path
 
   type pathlist = path | Array[path]
 
@@ -213,7 +216,7 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.cd('..')
   #         FileUtils.cd('fileutils')
@@ -248,7 +251,7 @@ module FileUtils
   # -->
   # Changes permissions on the entries at the paths given in `list` (a single path
   # or an array of paths) to the permissions given by `mode`; returns `list` if it
-  # is an array, `[list]` otherwise:
+  # is an array, <code>[list]</code> otherwise:
   #
   # *   Modifies each entry that is a regular file using
   #     [File.chmod](rdoc-ref:File.chmod).
@@ -267,30 +270,33 @@ module FileUtils
   #
   # *   String `mode`: represents the permissions to be set:
   #
-  #     The string is of the form `[targets][[operator][perms[,perms]]`, where:
+  #     The string is of the form
+  #     <code>[targets][[operator][perms[,perms]]</code>, where:
   #
   #     *   `targets` may be any combination of these letters:
   #
-  #         *   `'u'`: permissions apply to the file's owner.
-  #         *   `'g'`: permissions apply to users in the file's group.
-  #         *   `'o'`: permissions apply to other users not in the file's group.
-  #         *   `'a'` (the default): permissions apply to all users.
+  #         *   <code>'u'</code>: permissions apply to the file's owner.
+  #         *   <code>'g'</code>: permissions apply to users in the file's group.
+  #         *   <code>'o'</code>: permissions apply to other users not in the
+  #             file's group.
+  #         *   <code>'a'</code> (the default): permissions apply to all users.
   #
   #     *   `operator` may be one of these letters:
   #
-  #         *   `'+'`: adds permissions.
-  #         *   `'-'`: removes permissions.
-  #         *   `'='`: sets (replaces) permissions.
+  #         *   <code>'+'</code>: adds permissions.
+  #         *   <code>'-'</code>: removes permissions.
+  #         *   <code>'='</code>: sets (replaces) permissions.
   #
   #     *   `perms` (may be repeated, with separating commas) may be any
   #         combination of these letters:
   #
-  #         *   `'r'`: Read.
-  #         *   `'w'`: Write.
-  #         *   `'x'`: Execute (search, for a directory).
-  #         *   `'X'`: Search (for a directories only; must be used with `'+'`)
-  #         *   `'s'`: Uid or gid.
-  #         *   `'t'`: Sticky bit.
+  #         *   <code>'r'</code>: Read.
+  #         *   <code>'w'</code>: Write.
+  #         *   <code>'x'</code>: Execute (search, for a directory).
+  #         *   <code>'X'</code>: Search (for a directories only; must be used
+  #             with <code>'+'</code>)
+  #         *   <code>'s'</code>: Uid or gid.
+  #         *   <code>'t'</code>: Sticky bit.
   #
   #     Examples:
   #
@@ -299,8 +305,8 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `noop: true` - does not change permissions; returns `nil`.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>noop: true</code> - does not change permissions; returns `nil`.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.chmod(0755, 'src0.txt', noop: true, verbose: true)
   #         FileUtils.chmod(0644, ['src0.txt', 'src0.dat'], noop: true, verbose: true)
@@ -332,7 +338,7 @@ module FileUtils
   # -->
   # Changes the owner and group on the entries at the paths given in `list` (a
   # single path or an array of paths) to the given `user` and `group`; returns
-  # `list` if it is an array, `[list]` otherwise:
+  # `list` if it is an array, <code>[list]</code> otherwise:
   #
   # *   Modifies each entry that is a regular file using
   #     [File.chown](rdoc-ref:File.chown).
@@ -344,10 +350,10 @@ module FileUtils
   #
   # User and group:
   #
-  # *   Argument `user` may be a user name or a user id; if `nil` or `-1`, the
-  #     user is not changed.
-  # *   Argument `group` may be a group name or a group id; if `nil` or `-1`, the
-  #     group is not changed.
+  # *   Argument `user` may be a user name or a user id; if `nil` or
+  #     <code>-1</code>, the user is not changed.
+  # *   Argument `group` may be a group name or a group id; if `nil` or
+  #     <code>-1</code>, the group is not changed.
   # *   The user must be a member of the group.
   #
   # Examples:
@@ -373,8 +379,8 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `noop: true` - does not change permissions; returns `nil`.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>noop: true</code> - does not change permissions; returns `nil`.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.chown('user2', 'group1', 'src0.txt', noop: true, verbose: true)
   #         FileUtils.chown(1004, 1004, 'src0.txt', noop: true, verbose: true)
@@ -522,11 +528,13 @@ module FileUtils
   # symbolic links; other file types (FIFO streams, device files, etc.) are not
   # supported.
   #
-  # Keyword arguments:
+  # Optional arguments:
   #
-  # *   `dereference_root: true` - if `src` is a symbolic link, follows the link.
-  # *   `preserve: true` - preserves file times.
-  # *   `remove_destination: true` - removes `dest` before copying files.
+  # *   `dereference_root` - if `src` is a symbolic link, follows the link
+  #     (`false` by default).
+  # *   `preserve` - preserves file times (`false` by default).
+  # *   `remove_destination` - removes `dest` before copying files (`false` by
+  #     default).
   #
   # Related: [methods for copying](rdoc-ref:FileUtils@Copying).
   #
@@ -547,12 +555,13 @@ module FileUtils
   #     FileUtils.copy_file('src0.txt', 'dest0.txt')
   #     File.file?('dest0.txt') # => true
   #
-  # Keyword arguments:
+  # Optional arguments:
   #
-  # *   `dereference: false` - if `src` is a symbolic link, does not follow the
-  #     link.
-  # *   `preserve: true` - preserves file times.
-  # *   `remove_destination: true` - removes `dest` before copying files.
+  # *   `dereference` - if `src` is a symbolic link, follows the link (`true` by
+  #     default).
+  # *   `preserve` - preserves file times (`false` by default).
+  # *   `remove_destination` - removes `dest` before copying files (`false` by
+  #     default).
   #
   # Related: [methods for copying](rdoc-ref:FileUtils@Copying).
   #
@@ -587,7 +596,7 @@ module FileUtils
   #     File.file?('dest0.txt')  # => true
   #
   # If `src` is the path to a file and `dest` is the path to a directory, copies
-  # `src` to `dest/src`:
+  # `src` to <code>dest/src</code>:
   #
   #     FileUtils.touch('src1.txt')
   #     FileUtils.mkdir('dest1')
@@ -606,9 +615,9 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `preserve: true` - preserves file times.
-  # *   `noop: true` - does not copy files.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>preserve: true</code> - preserves file times.
+  # *   <code>noop: true</code> - does not copy files.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.cp('src0.txt', 'dest0.txt', noop: true, verbose: true)
   #         FileUtils.cp('src1.txt', 'dest1', noop: true, verbose: true)
@@ -671,8 +680,8 @@ module FileUtils
   #     #        |-- src2.txt
   #     #        `-- src3.txt
   #
-  # If `src` and `dest` are both paths to directories, creates links `dest/src`
-  # and descendents pointing to `src` and its descendents:
+  # If `src` and `dest` are both paths to directories, creates links
+  # <code>dest/src</code> and descendents pointing to `src` and its descendents:
   #
   #     tree('src1')
   #     # => src1
@@ -696,7 +705,7 @@ module FileUtils
   #
   # If `src` is an array of paths to entries and `dest` is the path to a
   # directory, for each path `filepath` in `src`, creates a link at
-  # `dest/filepath` pointing to that path:
+  # <code>dest/filepath</code> pointing to that path:
   #
   #     tree('src2')
   #     # => src2
@@ -719,11 +728,12 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `dereference_root: false` - if `src` is a symbolic link, does not
-  #     dereference it.
-  # *   `noop: true` - does not create links.
-  # *   `remove_destination: true` - removes `dest` before creating links.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>dereference_root: false</code> - if `src` is a symbolic link, does
+  #     not dereference it.
+  # *   <code>noop: true</code> - does not create links.
+  # *   <code>remove_destination: true</code> - removes `dest` before creating
+  #     links.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.cp_lr('src0', 'dest0', noop: true, verbose: true)
   #         FileUtils.cp_lr('src1', 'dest1', noop: true, verbose: true)
@@ -736,7 +746,7 @@ module FileUtils
   #         cp -lr src2/sub0 src2/sub1 dest2
   #
   # Raises an exception if `dest` is the path to an existing file or directory and
-  # keyword argument `remove_destination: true` is not given.
+  # keyword argument <code>remove_destination: true</code> is not given.
   #
   # Related: [methods for copying](rdoc-ref:FileUtils@Copying).
   #
@@ -763,7 +773,7 @@ module FileUtils
   #     File.file?('dest0.txt')  # => true
   #
   # If `src` is the path to a file and `dest` is the path to a directory, copies
-  # `src` to `dest/src`:
+  # `src` to <code>dest/src</code>:
   #
   #     FileUtils.touch('src1.txt')
   #     FileUtils.mkdir('dest1')
@@ -793,7 +803,7 @@ module FileUtils
   #     #    `-- src3.txt
   #
   # If `src` and `dest` are paths to directories, recursively copies `src` to
-  # `dest/src`:
+  # <code>dest/src</code>:
   #
   #     tree('src3')
   #     # => src3
@@ -821,12 +831,13 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `dereference_root: false` - if `src` is a symbolic link, does not
-  #     dereference it.
-  # *   `noop: true` - does not copy files.
-  # *   `preserve: true` - preserves file times.
-  # *   `remove_destination: true` - removes `dest` before copying files.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>dereference_root: false</code> - if `src` is a symbolic link, does
+  #     not dereference it.
+  # *   <code>noop: true</code> - does not copy files.
+  # *   <code>preserve: true</code> - preserves file times.
+  # *   <code>remove_destination: true</code> - removes `dest` before copying
+  #     files.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.cp_r('src0.txt', 'dest0.txt', noop: true, verbose: true)
   #         FileUtils.cp_r('src1.txt', 'dest1', noop: true, verbose: true)
@@ -883,8 +894,8 @@ module FileUtils
   #     FileUtils.install('src1.txt', 'dest1.txt')
   #     File.read('dest1.txt') # => "aaa\n"
   #
-  # If `dest` is a directory entry, copies from `src` to `dest/src`, overwriting
-  # if necessary:
+  # If `dest` is a directory entry, copies from `src` to <code>dest/src</code>,
+  # overwriting if necessary:
   #
   #     File.read('src2.txt')       # => "aaa\n"
   #     File.read('dest2/src2.txt') # => "bbb\n"
@@ -892,7 +903,7 @@ module FileUtils
   #     File.read('dest2/src2.txt') # => "aaa\n"
   #
   # If `src` is an array of paths and `dest` points to a directory, copies each
-  # path `path` in `src` to `dest/path`:
+  # path `path` in `src` to <code>dest/path</code>:
   #
   #     File.file?('src3.txt') # => true
   #     File.file?('src3.dat') # => true
@@ -903,16 +914,16 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `group: *group`* - changes the group if not `nil`, using
+  # *   <code>group: <i>group</i></code> - changes the group if not `nil`, using
   #     [File.chown](rdoc-ref:File.chown).
-  # *   `mode: *permissions`* - changes the permissions. using
+  # *   <code>mode: <i>permissions</i></code> - changes the permissions. using
   #     [File.chmod](rdoc-ref:File.chmod).
-  # *   `noop: true` - does not copy entries; returns `nil`.
-  # *   `owner: *owner`* - changes the owner if not `nil`, using
+  # *   <code>noop: true</code> - does not copy entries; returns `nil`.
+  # *   <code>owner: <i>owner</i></code> - changes the owner if not `nil`, using
   #     [File.chown](rdoc-ref:File.chown).
-  # *   `preserve: true` - preserve timestamps using
+  # *   <code>preserve: true</code> - preserve timestamps using
   #     [File.utime](rdoc-ref:File.utime).
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.install('src0.txt', 'dest0.txt', noop: true, verbose: true)
   #         FileUtils.install('src1.txt', 'dest1.txt', noop: true, verbose: true)
@@ -963,13 +974,15 @@ module FileUtils
   #     File.file?('dest1/dir1/t2.txt') # => true
   #     File.file?('dest1/dir1/t3.txt') # => true
   #
-  # Keyword arguments:
+  # Optional arguments:
   #
-  # *   `dereference_root: true` - dereferences `src` if it is a symbolic link.
-  # *   `remove_destination: true` - removes `dest` before creating links.
+  # *   `dereference_root` - dereferences `src` if it is a symbolic link (`false`
+  #     by default).
+  # *   `remove_destination` - removes `dest` before creating links (`false` by
+  #     default).
   #
   # Raises an exception if `dest` is the path to an existing file or directory and
-  # keyword argument `remove_destination: true` is not given.
+  # optional argument `remove_destination` is not given.
   #
   # Related: FileUtils.ln (has different options).
   #
@@ -994,8 +1007,8 @@ module FileUtils
   #     Dir.children('tmp1/')                    # => ["t.lnk"]
   #
   # When `src` is the path to an existing file and `dest` is the path to an
-  # existing directory, creates a hard link at `dest/src` pointing to `src`;
-  # returns zero:
+  # existing directory, creates a hard link at <code>dest/src</code> pointing to
+  # `src`; returns zero:
   #
   #     Dir.children('tmp2')               # => ["t.dat"]
   #     Dir.children('tmp3')               # => []
@@ -1004,7 +1017,7 @@ module FileUtils
   #
   # When `src` is an array of paths to existing files and `dest` is the path to an
   # existing directory, then for each path `target` in `src`, creates a hard link
-  # at `dest/target` pointing to `target`; returns `src`:
+  # at <code>dest/target</code> pointing to `target`; returns `src`:
   #
   #     Dir.children('tmp4/')                               # => []
   #     FileUtils.ln(['tmp0/t.txt', 'tmp2/t.dat'], 'tmp4/') # => ["tmp0/t.txt", "tmp2/t.dat"]
@@ -1012,9 +1025,9 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `force: true` - overwrites `dest` if it exists.
-  # *   `noop: true` - does not create links.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>force: true</code> - overwrites `dest` if it exists.
+  # *   <code>noop: true</code> - does not create links.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.ln('tmp0/t.txt', 'tmp1/t.lnk', verbose: true)
   #         FileUtils.ln('tmp2/t.dat', 'tmp3', verbose: true)
@@ -1067,8 +1080,8 @@ module FileUtils
   #         File.symlink?('dest0.txt') # => true
   #
   # *   When `dest` is the path to an existing file, creates a symbolic link at
-  #     `dest` pointing to `src` if and only if keyword argument `force: true` is
-  #     given (raises an exception otherwise):
+  #     `dest` pointing to `src` if and only if keyword argument <code>force:
+  #     true</code> is given (raises an exception otherwise):
   #
   #         FileUtils.touch('src1.txt')
   #         FileUtils.touch('dest1.txt')
@@ -1077,8 +1090,8 @@ module FileUtils
   #
   #         FileUtils.ln_s('src1.txt', 'dest1.txt') # Raises Errno::EEXIST.
   #
-  # If `dest` is the path to a directory, creates a symbolic link at `dest/src`
-  # pointing to `src`:
+  # If `dest` is the path to a directory, creates a symbolic link at
+  # <code>dest/src</code> pointing to `src`:
   #
   #     FileUtils.touch('src2.txt')
   #     FileUtils.mkdir('destdir2')
@@ -1086,8 +1099,8 @@ module FileUtils
   #     File.symlink?('destdir2/src2.txt') # => true
   #
   # If `src` is an array of paths to existing files and `dest` is a directory, for
-  # each child `child` in `src` creates a symbolic link `dest/child` pointing to
-  # `child`:
+  # each child `child` in `src` creates a symbolic link <code>dest/child</code>
+  # pointing to `child`:
   #
   #     FileUtils.mkdir('srcdir3')
   #     FileUtils.touch('srcdir3/src0.txt')
@@ -1099,10 +1112,10 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `force: true` - overwrites `dest` if it exists.
-  # *   `relative: false` - create links relative to `dest`.
-  # *   `noop: true` - does not create links.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>force: true</code> - overwrites `dest` if it exists.
+  # *   <code>relative: false</code> - create links relative to `dest`.
+  # *   <code>noop: true</code> - does not create links.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.ln_s('src0.txt', 'dest0.txt', noop: true, verbose: true)
   #         FileUtils.ln_s('src1.txt', 'destdir1', noop: true, verbose: true)
@@ -1138,7 +1151,8 @@ module FileUtils
   #   rdoc-file=lib/fileutils.rb
   #   - ln_sf(src, dest, noop: nil, verbose: nil)
   # -->
-  # Like FileUtils.ln_s, but always with keyword argument `force: true` given.
+  # Like FileUtils.ln_s, but always with keyword argument <code>force: true</code>
+  # given.
   #
   def self?.ln_sf: (pathlist src, path dest, ?noop: boolish, ?verbose: boolish) -> void
 
@@ -1155,23 +1169,25 @@ module FileUtils
   #   - mkdir(list, mode: nil, noop: nil, verbose: nil)
   # -->
   # Creates directories at the paths in the given `list` (a single path or an
-  # array of paths); returns `list` if it is an array, `[list]` otherwise.
+  # array of paths); returns `list` if it is an array, <code>[list]</code>
+  # otherwise.
   #
   # Argument `list` or its elements should be [interpretable as
   # paths](rdoc-ref:FileUtils@Path+Arguments).
   #
   # With no keyword arguments, creates a directory at each `path` in `list` by
-  # calling: `Dir.mkdir(path, mode)`; see [Dir.mkdir](rdoc-ref:Dir.mkdir):
+  # calling: <code>Dir.mkdir(path, mode)</code>; see
+  # [Dir.mkdir](rdoc-ref:Dir.mkdir):
   #
   #     FileUtils.mkdir(%w[tmp0 tmp1]) # => ["tmp0", "tmp1"]
   #     FileUtils.mkdir('tmp4')        # => ["tmp4"]
   #
   # Keyword arguments:
   #
-  # *   `mode: *mode`* - also calls `File.chmod(mode, path)`; see
-  #     [File.chmod](rdoc-ref:File.chmod).
-  # *   `noop: true` - does not create directories.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>mode: <i>mode</i></code> - also calls <code>File.chmod(mode,
+  #     path)</code>; see [File.chmod](rdoc-ref:File.chmod).
+  # *   <code>noop: true</code> - does not create directories.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.mkdir(%w[tmp0 tmp1], verbose: true)
   #         FileUtils.mkdir(%w[tmp2 tmp3], mode: 0700, verbose: true)
@@ -1194,24 +1210,24 @@ module FileUtils
   # -->
   # Creates directories at the paths in the given `list` (a single path or an
   # array of paths), also creating ancestor directories as needed; returns `list`
-  # if it is an array, `[list]` otherwise.
+  # if it is an array, <code>[list]</code> otherwise.
   #
   # Argument `list` or its elements should be [interpretable as
   # paths](rdoc-ref:FileUtils@Path+Arguments).
   #
   # With no keyword arguments, creates a directory at each `path` in `list`, along
-  # with any needed ancestor directories, by calling: `Dir.mkdir(path, mode)`; see
-  # [Dir.mkdir](rdoc-ref:Dir.mkdir):
+  # with any needed ancestor directories, by calling: <code>Dir.mkdir(path,
+  # mode)</code>; see [Dir.mkdir](rdoc-ref:Dir.mkdir):
   #
   #     FileUtils.mkdir_p(%w[tmp0/tmp1 tmp2/tmp3]) # => ["tmp0/tmp1", "tmp2/tmp3"]
   #     FileUtils.mkdir_p('tmp4/tmp5')             # => ["tmp4/tmp5"]
   #
   # Keyword arguments:
   #
-  # *   `mode: *mode`* - also calls `File.chmod(mode, path)`; see
-  #     [File.chmod](rdoc-ref:File.chmod).
-  # *   `noop: true` - does not create directories.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>mode: <i>mode</i></code> - also calls <code>File.chmod(mode,
+  #     path)</code>; see [File.chmod](rdoc-ref:File.chmod).
+  # *   <code>noop: true</code> - does not create directories.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.mkdir_p(%w[tmp0 tmp1], verbose: true)
   #         FileUtils.mkdir_p(%w[tmp2 tmp3], mode: 0700, verbose: true)
@@ -1269,8 +1285,8 @@ module FileUtils
   # If `src` and `dest` are on different file systems, first copies, then removes
   # `src`.
   #
-  # May cause a local vulnerability if not called with keyword argument `secure:
-  # true`; see [Avoiding the TOCTTOU
+  # May cause a local vulnerability if not called with keyword argument
+  # <code>secure: true</code>; see [Avoiding the TOCTTOU
   # Vulnerability](rdoc-ref:FileUtils@Avoiding+the+TOCTTOU+Vulnerability).
   #
   # If `src` is the path to a single file or directory and `dest` does not exist,
@@ -1307,13 +1323,13 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `force: true` - if the move includes removing `src` (that is, if `src` and
-  #     `dest` are on different file systems), ignores raised exceptions of
-  #     StandardError and its descendants.
-  # *   `noop: true` - does not move files.
-  # *   `secure: true` - removes `src` securely; see details at
+  # *   <code>force: true</code> - if the move includes removing `src` (that is,
+  #     if `src` and `dest` are on different file systems), ignores raised
+  #     exceptions of StandardError and its descendants.
+  # *   <code>noop: true</code> - does not move files.
+  # *   <code>secure: true</code> - removes `src` securely; see details at
   #     FileUtils.remove_entry_secure.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.mv('src0', 'dest0', noop: true, verbose: true)
   #         FileUtils.mv(['src1.txt', 'src1'], 'dest1', noop: true, verbose: true)
@@ -1464,7 +1480,7 @@ module FileUtils
   #   - rm(list, force: nil, noop: nil, verbose: nil)
   # -->
   # Removes entries at the paths in the given `list` (a single path or an array of
-  # paths) returns `list`, if it is an array, `[list]` otherwise.
+  # paths) returns `list`, if it is an array, <code>[list]</code> otherwise.
   #
   # Argument `list` or its elements should be [interpretable as
   # paths](rdoc-ref:FileUtils@Path+Arguments).
@@ -1476,10 +1492,10 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `force: true` - ignores raised exceptions of StandardError and its
-  #     descendants.
-  # *   `noop: true` - does not remove files; returns `nil`.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>force: true</code> - ignores raised exceptions of StandardError and
+  #     its descendants.
+  # *   <code>noop: true</code> - does not remove files; returns `nil`.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.rm(['src0.dat', 'src0.txt'], noop: true, verbose: true)
   #
@@ -1541,13 +1557,13 @@ module FileUtils
   #   - rm_r(list, force: nil, noop: nil, verbose: nil, secure: nil)
   # -->
   # Removes entries at the paths in the given `list` (a single path or an array of
-  # paths); returns `list`, if it is an array, `[list]` otherwise.
+  # paths); returns `list`, if it is an array, <code>[list]</code> otherwise.
   #
   # Argument `list` or its elements should be [interpretable as
   # paths](rdoc-ref:FileUtils@Path+Arguments).
   #
-  # May cause a local vulnerability if not called with keyword argument `secure:
-  # true`; see [Avoiding the TOCTTOU
+  # May cause a local vulnerability if not called with keyword argument
+  # <code>secure: true</code>; see [Avoiding the TOCTTOU
   # Vulnerability](rdoc-ref:FileUtils@Avoiding+the+TOCTTOU+Vulnerability).
   #
   # For each file path, removes the file at that path:
@@ -1572,12 +1588,12 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `force: true` - ignores raised exceptions of StandardError and its
-  #     descendants.
-  # *   `noop: true` - does not remove entries; returns `nil`.
-  # *   `secure: true` - removes `src` securely; see details at
+  # *   <code>force: true</code> - ignores raised exceptions of StandardError and
+  #     its descendants.
+  # *   <code>noop: true</code> - does not remove entries; returns `nil`.
+  # *   <code>secure: true</code> - removes `src` securely; see details at
   #     FileUtils.remove_entry_secure.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.rm_r(['src0.dat', 'src0.txt'], noop: true, verbose: true)
   #         FileUtils.rm_r('src1', noop: true, verbose: true)
@@ -1602,8 +1618,8 @@ module FileUtils
   # Argument `list` or its elements should be [interpretable as
   # paths](rdoc-ref:FileUtils@Path+Arguments).
   #
-  # May cause a local vulnerability if not called with keyword argument `secure:
-  # true`; see [Avoiding the TOCTTOU
+  # May cause a local vulnerability if not called with keyword argument
+  # <code>secure: true</code>; see [Avoiding the TOCTTOU
   # Vulnerability](rdoc-ref:FileUtils@Avoiding+the+TOCTTOU+Vulnerability).
   #
   # See FileUtils.rm_r for keyword arguments.
@@ -1631,22 +1647,24 @@ module FileUtils
   #   - rmdir(list, parents: nil, noop: nil, verbose: nil)
   # -->
   # Removes directories at the paths in the given `list` (a single path or an
-  # array of paths); returns `list`, if it is an array, `[list]` otherwise.
+  # array of paths); returns `list`, if it is an array, <code>[list]</code>
+  # otherwise.
   #
   # Argument `list` or its elements should be [interpretable as
   # paths](rdoc-ref:FileUtils@Path+Arguments).
   #
   # With no keyword arguments, removes the directory at each `path` in `list`, by
-  # calling: `Dir.rmdir(path)`; see [Dir.rmdir](rdoc-ref:Dir.rmdir):
+  # calling: <code>Dir.rmdir(path)</code>; see [Dir.rmdir](rdoc-ref:Dir.rmdir):
   #
   #     FileUtils.rmdir(%w[tmp0/tmp1 tmp2/tmp3]) # => ["tmp0/tmp1", "tmp2/tmp3"]
   #     FileUtils.rmdir('tmp4/tmp5')             # => ["tmp4/tmp5"]
   #
   # Keyword arguments:
   #
-  # *   `parents: true` - removes successive ancestor directories if empty.
-  # *   `noop: true` - does not remove directories.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>parents: true</code> - removes successive ancestor directories if
+  #     empty.
+  # *   <code>noop: true</code> - does not remove directories.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.rmdir(%w[tmp0/tmp1 tmp2/tmp3], parents: true, verbose: true)
   #         FileUtils.rmdir('tmp4/tmp5', parents: true, verbose: true)
@@ -1669,7 +1687,7 @@ module FileUtils
   # -->
   # Updates modification times (mtime) and access times (atime) of the entries
   # given by the paths in `list` (a single path or an array of paths); returns
-  # `list` if it is an array, `[list]` otherwise.
+  # `list` if it is an array, <code>[list]</code> otherwise.
   #
   # By default, creates an empty file for any path to a non-existent entry; use
   # keyword argument `nocreate` to raise an exception instead.
@@ -1693,11 +1711,12 @@ module FileUtils
   #
   # Keyword arguments:
   #
-  # *   `mtime: *time`* - sets the entry's mtime to the given time, instead of the
-  #     current time.
-  # *   `nocreate: true` - raises an exception if the entry does not exist.
-  # *   `noop: true` - does not touch entries; returns `nil`.
-  # *   `verbose: true` - prints an equivalent command:
+  # *   <code>mtime: <i>time</i></code> - sets the entry's mtime to the given
+  #     time, instead of the current time.
+  # *   <code>nocreate: true</code> - raises an exception if the entry does not
+  #     exist.
+  # *   <code>noop: true</code> - does not touch entries; returns `nil`.
+  # *   <code>verbose: true</code> - prints an equivalent command:
   #
   #         FileUtils.touch('src0.txt', noop: true, verbose: true)
   #         FileUtils.touch(['src0.txt', 'src0.dat'], noop: true, verbose: true)