rbs 4.0.0.dev.4 → 4.0.0

data/core/file.rbs

@@ -2,7 +2,7 @@
 # A File object is a representation of a file in the underlying platform.
 #
 # Class File extends module FileTest, supporting such singleton methods as
-# `File.exist?`.
+# <code>File.exist?</code>.
 #
 # ## About the Examples
 #
@@ -93,8 +93,8 @@
 #     | 'a+' | Anywhere |    0     | End only |    End    |
 #     |------|----------|----------|----------|-----------|
 #
-# Note that modes `'r'` and `'r+'` are not allowed for a non-existent file
-# (exception raised).
+# Note that modes <code>'r'</code> and <code>'r+'</code> are not allowed for a
+# non-existent file (exception raised).
 #
 # In the tables:
 #
@@ -108,7 +108,7 @@
 #
 # ##### Read/Write Modes for Existing File
 #
-# *   `'r'`:
+# *   <code>'r'</code>:
 #
 #     *   File is not initially truncated:
 #
@@ -137,7 +137,7 @@
 #
 #             f.write('foo') # Raises IOError.
 #
-# *   `'w'`:
+# *   <code>'w'</code>:
 #
 #     *   File is initially truncated:
 #
@@ -191,7 +191,7 @@
 #
 #             f.read # Raises IOError.
 #
-# *   `'a'`:
+# *   <code>'a'</code>:
 #
 #     *   File is not initially truncated:
 #
@@ -223,7 +223,7 @@
 #
 #             f.read # Raises IOError.
 #
-# *   `'r+'`:
+# *   <code>'r+'</code>:
 #
 #     *   File is not initially truncated:
 #
@@ -278,7 +278,7 @@
 #             File.read(path)
 #             # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"
 #
-# *   `'a+'`:
+# *   <code>'a+'</code>:
 #
 #     *   File is not initially truncated:
 #
@@ -319,10 +319,10 @@
 #
 # ##### Read/Write Modes for File To Be Created
 #
-# Note that modes `'r'` and `'r+'` are not allowed for a non-existent file
-# (exception raised).
+# Note that modes <code>'r'</code> and <code>'r+'</code> are not allowed for a
+# non-existent file (exception raised).
 #
-# *   `'w'`:
+# *   <code>'w'</code>:
 #
 #     *   File's initial write position is 0:
 #
@@ -372,7 +372,7 @@
 #
 #             f.read # Raises IOError.
 #
-# *   `'a'`:
+# *   <code>'a'</code>:
 #
 #     *   File's initial write position is 0:
 #
@@ -399,7 +399,7 @@
 #
 #             f.read # Raises IOError.
 #
-# *   `'w+'`:
+# *   <code>'w+'</code>:
 #
 #     *   File's initial position is 0:
 #
@@ -463,7 +463,7 @@
 #             f.read
 #             # => "bah"
 #
-# *   `'a+'`:
+# *   <code>'a+'</code>:
 #
 #     *   File's initial write position is 0:
 #
@@ -506,12 +506,13 @@
 # To specify whether data is to be treated as text or as binary data, either of
 # the following may be suffixed to any of the string read/write modes above:
 #
-# *   `'t'`: Text data; sets the default external encoding to `Encoding::UTF_8`;
-#     on Windows, enables conversion between EOL and CRLF and enables
-#     interpreting `0x1A` as an end-of-file marker.
-# *   `'b'`: Binary data; sets the default external encoding to
-#     `Encoding::ASCII_8BIT`; on Windows, suppresses conversion between EOL and
-#     CRLF and disables interpreting `0x1A` as an end-of-file marker.
+# *   <code>'t'</code>: Text data; sets the default external encoding to
+#     <code>Encoding::UTF_8</code>; on Windows, enables conversion between EOL
+#     and CRLF and enables interpreting `0x1A` as an end-of-file marker.
+# *   <code>'b'</code>: Binary data; sets the default external encoding to
+#     <code>Encoding::ASCII_8BIT</code>; on Windows, suppresses conversion
+#     between EOL and CRLF and disables interpreting `0x1A` as an end-of-file
+#     marker.
 #
 # If neither is given, the stream defaults to text data.
 #
@@ -530,8 +531,8 @@
 #
 # The following may be suffixed to any writable string mode above:
 #
-# *   `'x'`: Creates the file if it does not exist; raises an exception if the
-#     file exists.
+# *   <code>'x'</code>: Creates the file if it does not exist; raises an
+#     exception if the file exists.
 #
 # Example:
 #
@@ -546,12 +547,12 @@
 # ### Integer Access Modes
 #
 # When mode is an integer it must be one or more of the following constants,
-# which may be combined by the bitwise OR operator `|`:
+# which may be combined by the bitwise OR operator <code>|</code>:
 #
-# *   `File::RDONLY`: Open for reading only.
-# *   `File::WRONLY`: Open for writing only.
-# *   `File::RDWR`: Open for reading and writing.
-# *   `File::APPEND`: Open for appending only.
+# *   <code>File::RDONLY</code>: Open for reading only.
+# *   <code>File::WRONLY</code>: Open for writing only.
+# *   <code>File::RDWR</code>: Open for reading and writing.
+# *   <code>File::APPEND</code>: Open for appending only.
 #
 # Examples:
 #
@@ -565,19 +566,19 @@
 #
 # These constants may also be ORed into the integer mode:
 #
-# *   `File::CREAT`: Create file if it does not exist.
-# *   `File::EXCL`: Raise an exception if `File::CREAT` is given and the file
-#     exists.
+# *   <code>File::CREAT</code>: Create file if it does not exist.
+# *   <code>File::EXCL</code>: Raise an exception if <code>File::CREAT</code> is
+#     given and the file exists.
 #
 # ### Data Mode Specified as an Integer
 #
 # Data mode cannot be specified as an integer. When the stream access mode is
 # given as an integer, the data mode is always text, never binary.
 #
-# Note that although there is a constant `File::BINARY`, setting its value in an
-# integer stream mode has no effect; this is because, as documented in
-# File::Constants, the `File::BINARY` value disables line code conversion, but
-# does not change the external encoding.
+# Note that although there is a constant <code>File::BINARY</code>, setting its
+# value in an integer stream mode has no effect; this is because, as documented
+# in File::Constants, the <code>File::BINARY</code> value disables line code
+# conversion, but does not change the external encoding.
 #
 # ### Encodings
 #
@@ -608,14 +609,14 @@
 # internal to external encoding. For further details about transcoding input and
 # output, see [Encodings](rdoc-ref:encodings.rdoc@Encodings).
 #
-# If the external encoding is `'BOM|UTF-8'`, `'BOM|UTF-16LE'` or
-# `'BOM|UTF16-BE'`, Ruby checks for a Unicode BOM in the input document to help
-# determine the encoding. For UTF-16 encodings the file open mode must be
-# binary. If the BOM is found, it is stripped and the external encoding from the
-# BOM is used.
+# If the external encoding is <code>'BOM|UTF-8'</code>,
+# <code>'BOM|UTF-16LE'</code> or <code>'BOM|UTF16-BE'</code>, Ruby checks for a
+# Unicode BOM in the input document to help determine the encoding. For UTF-16
+# encodings the file open mode must be binary. If the BOM is found, it is
+# stripped and the external encoding from the BOM is used.
 #
-# Note that the BOM-style encoding option is case insensitive, so `'bom|utf-8'`
-# is also valid.
+# Note that the BOM-style encoding option is case insensitive, so
+# <code>'bom|utf-8'</code> is also valid.
 #
 # ## File Permissions
 #
@@ -669,7 +670,7 @@
 #
 # Various constants for use in File and IO methods may be found in module
 # File::Constants; an array of their names is returned by
-# `File::Constants.constants`.
+# <code>File::Constants.constants</code>.
 #
 # ## What's Here
 #
@@ -705,7 +706,7 @@
 # *   ::basename: Returns the last component of the given file path.
 # *   ::dirname: Returns all but the last component of the given file path.
 # *   ::expand_path: Returns the absolute file path for the given path,
-#     expanding `~` for a home directory.
+#     expanding <code>~</code> for a home directory.
 # *   ::extname: Returns the file extension for the given file path.
 # *   ::fnmatch? (aliased as ::fnmatch): Returns whether the given file path
 #     matches the given pattern.
@@ -847,7 +848,30 @@ class File < IO
   # *   [Open Options](rdoc-ref:IO@Open+Options).
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  def initialize: (string | _ToPath | int file_name, ?string | int mode, ?int perm) -> void
+  def initialize: (
+    path | int file_name,
+    ?string | int mode,
+    ?int perm,
+    # open options
+    ?mode: Integer | String,
+    ?flags: Integer,
+    ?external_encoding: encoding,
+    ?internal_encoding: encoding,
+    ?encoding: encoding,
+    ?textmode: boolish,
+    ?binmode: boolish,
+    ?autoclose: boolish,
+    ?path: path,
+    # encoding options
+    ?invalid: :replace | nil,
+    ?undef: :replace | nil,
+    ?replace: String | nil,
+    ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+    ?xml: :text | :attr | nil,
+    ?cr_newline: bool,
+    ?crlf_newline: bool,
+    ?universal_newline: bool
+  ) -> void
 
   # <!--
   #   rdoc-file=file.c
@@ -856,12 +880,12 @@ class File < IO
   # Converts a pathname to an absolute pathname. Relative paths are referenced
   # from the current working directory of the process unless *dir_string* is
   # given, in which case it will be used as the starting point. If the given
-  # pathname starts with a ```~`'' it is NOT expanded, it is treated as a normal
-  # directory name.
+  # pathname starts with a ``<code>~</code>'' it is NOT expanded, it is treated as
+  # a normal directory name.
   #
   #     File.absolute_path("~oracle/bin")       #=> "<relative_path>/~oracle/bin"
   #
-  def self.absolute_path: (string | _ToPath file_name, ?string | _ToPath dir_string) -> String
+  def self.absolute_path: (path file_name, ?path dir_string) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -871,7 +895,7 @@ class File < IO
   #
   #     File.absolute_path?("c:/foo")     #=> false (on Linux), true (on Windows)
   #
-  def self.absolute_path?: (string | _ToPath file_name) -> bool
+  def self.absolute_path?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -883,7 +907,7 @@ class File < IO
   #
   #     File.atime("testfile")   #=> Wed Apr 09 08:51:48 CDT 2003
   #
-  def self.atime: (string | _ToPath | IO file_name) -> Time
+  def self.atime: (path | IO file_name) -> Time
 
   # <!--
   #   rdoc-file=file.c
@@ -899,7 +923,7 @@ class File < IO
   #     File.basename("/home/gumby/work/ruby.rb", ".rb")   #=> "ruby"
   #     File.basename("/home/gumby/work/ruby.rb", ".*")    #=> "ruby"
   #
-  def self.basename: (string | _ToPath file_name, ?string suffix) -> String
+  def self.basename: (path file_name, ?string suffix) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -913,7 +937,7 @@ class File < IO
   #
   # If the platform doesn't have birthtime, raises NotImplementedError.
   #
-  def self.birthtime: (string | _ToPath | IO file_name) -> Time
+  def self.birthtime: (path | IO file_name) -> Time
 
   # <!--
   #   rdoc-file=file.c
@@ -924,7 +948,7 @@ class File < IO
   #     File.blockdev?('/dev/sda1')       # => true
   #     File.blockdev?(File.new('t.tmp')) # => false
   #
-  def self.blockdev?: (string | _ToPath | IO file_name) -> bool
+  def self.blockdev?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -935,7 +959,7 @@ class File < IO
   #     File.chardev?($stdin)     # => true
   #     File.chardev?('t.txt')     # => false
   #
-  def self.chardev?: (string | _ToPath | IO file_name) -> bool
+  def self.chardev?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -943,12 +967,12 @@ class File < IO
   # -->
   # Changes permission bits on the named file(s) to the bit pattern represented by
   # *mode_int*. Actual effects are operating system dependent (see the beginning
-  # of this section). On Unix systems, see `chmod(2)` for details. Returns the
-  # number of files processed.
+  # of this section). On Unix systems, see <code>chmod(2)</code> for details.
+  # Returns the number of files processed.
   #
   #     File.chmod(0644, "testfile", "out")   #=> 2
   #
-  def self.chmod: (int mode, *string | _ToPath file_name) -> Integer
+  def self.chmod: (int mode, *path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -962,7 +986,7 @@ class File < IO
   #
   #     File.chown(nil, 100, "testfile")
   #
-  def self.chown: (int? owner, int? group, *string | _ToPath file_name) -> Integer
+  def self.chown: (int? owner, int? group, *path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -977,7 +1001,7 @@ class File < IO
   #
   #     File.ctime("testfile")   #=> Wed Apr 09 08:53:13 CDT 2003
   #
-  def self.ctime: (string | _ToPath | IO file_name) -> Time
+  def self.ctime: (path | IO file_name) -> Time
 
   # <!--
   #   rdoc-file=file.c
@@ -986,9 +1010,9 @@ class File < IO
   # -->
   # Deletes the named files, returning the number of names passed as arguments.
   # Raises an exception on any error. Since the underlying implementation relies
-  # on the `unlink(2)` system call, the type of exception raised depends on its
-  # error type (see https://linux.die.net/man/2/unlink) and has the form of e.g.
-  # Errno::ENOENT.
+  # on the <code>unlink(2)</code> system call, the type of exception raised
+  # depends on its error type (see https://linux.die.net/man/2/unlink) and has the
+  # form of e.g. Errno::ENOENT.
   #
   # See also Dir::rmdir.
   #
@@ -1010,7 +1034,7 @@ class File < IO
   #
   # Argument `path` can be an IO object.
   #
-  def self.directory?: (string | _ToPath | IO path) -> bool
+  def self.directory?: (path | IO path) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1028,7 +1052,7 @@ class File < IO
   #     File.dirname("/home/gumby/work/ruby.rb", 2) #=> "/home/gumby"
   #     File.dirname("/home/gumby/work/ruby.rb", 4) #=> "/"
   #
-  def self.dirname: (string | _ToPath file_name, ?Integer level) -> String
+  def self.dirname: (path file_name, ?Integer level) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1054,7 +1078,7 @@ class File < IO
   # Note that some OS-level security features may cause this to return true even
   # though the file is not executable by the effective user/group.
   #
-  def self.executable?: (string | _ToPath file_name) -> bool
+  def self.executable?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1070,7 +1094,7 @@ class File < IO
   # Note that some OS-level security features may cause this to return true even
   # though the file is not executable by the real user/group.
   #
-  def self.executable_real?: (string | _ToPath file_name) -> bool
+  def self.executable_real?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1082,7 +1106,7 @@ class File < IO
   #
   # "file exists" means that stat() or fstat() system call is successful.
   #
-  def self.exist?: (string | _ToPath | IO file_name) -> bool
+  def self.exist?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1091,9 +1115,9 @@ class File < IO
   # Converts a pathname to an absolute pathname. Relative paths are referenced
   # from the current working directory of the process unless `dir_string` is
   # given, in which case it will be used as the starting point. The given pathname
-  # may start with a ```~`'', which expands to the process owner's home directory
-  # (the environment variable `HOME` must be set correctly). ```~`*user*'' expands
-  # to the named user's home directory.
+  # may start with a ``<code>~</code>'', which expands to the process owner's home
+  # directory (the environment variable `HOME` must be set correctly).
+  # ``<code>~</code>*user*'' expands to the named user's home directory.
   #
   #     File.expand_path("~oracle/bin")           #=> "/home/oracle/bin"
   #
@@ -1107,9 +1131,9 @@ class File < IO
   #     #=> ".../path/to/project/lib/mygem.rb"
   #
   # So first it resolves the parent of __FILE__, that is bin/, then go to the
-  # parent, the root of the project and appends `lib/mygem.rb`.
+  # parent, the root of the project and appends <code>lib/mygem.rb</code>.
   #
-  def self.expand_path: (string | _ToPath file_name, ?string | _ToPath dir_string) -> String
+  def self.expand_path: (path file_name, ?path dir_string) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1135,7 +1159,7 @@ class File < IO
   #     File.extname(".profile")        #=> ""
   #     File.extname(".profile.sh")     #=> ".sh"
   #
-  def self.extname: (string | _ToPath path) -> String
+  def self.extname: (path path) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1148,7 +1172,7 @@ class File < IO
   # If the `file` argument is a symbolic link, it will resolve the symbolic link
   # and use the file referenced by the link.
   #
-  def self.file?: (string | _ToPath | IO file) -> bool
+  def self.file?: (path | IO file) -> bool
 
   # <!--
   #   rdoc-file=dir.rb
@@ -1159,48 +1183,48 @@ class File < IO
   # regular expression; instead it follows rules similar to shell filename
   # globbing.  It may contain the following metacharacters:
   #
-  # `*`
+  # <code>*</code>
   # :   Matches any file. Can be restricted by other values in the glob.
-  #     Equivalent to `/.*/x` in regexp.
+  #     Equivalent to <code>/.*/x</code> in regexp.
   #
-  #     `*`
+  #     <code>*</code>
   # :       Matches all regular files
   #
-  #     `c*`
+  #     <code>c*</code>
   # :       Matches all files beginning with `c`
   #
-  #     `*c`
+  #     <code>*c</code>
   # :       Matches all files ending with `c`
   #
-  #     `*c*`
+  #     <code>*c*</code>
   # :       Matches all files that have `c` in them (including at the beginning or
   #         end).
   #
   #
-  #     To match hidden files (that start with a `.`) set the File::FNM_DOTMATCH
-  #     flag.
+  #     To match hidden files (that start with a <code>.</code>) set the
+  #     File::FNM_DOTMATCH flag.
   #
   #
-  # `**`
+  # <code>**</code>
   # :   Matches directories recursively or files expansively.
   #
   #
-  # `?`
-  # :   Matches any one character. Equivalent to `/.{1}/` in regexp.
+  # <code>?</code>
+  # :   Matches any one character. Equivalent to <code>/.{1}/</code> in regexp.
   #
   #
-  # `[set]`
+  # <code>[set]</code>
   # :   Matches any one character in `set`.  Behaves exactly like character sets
-  #     in Regexp, including set negation (`[^a-z]`).
+  #     in Regexp, including set negation (<code>[^a-z]</code>).
   #
   #
-  # `\`
+  # <code>\</code>
   # :   Escapes the next metacharacter.
   #
   #
-  # `{a,b}`
+  # <code>{a,b}</code>
   # :   Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled.
-  #     Behaves like a Regexp union (`(?:a|b)`).
+  #     Behaves like a Regexp union (<code>(?:a|b)</code>).
   #
   #
   # `flags` is a bitwise OR of the `FNM_XXX` constants. The same glob pattern and
@@ -1252,7 +1276,7 @@ class File < IO
   #     File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME)    #=> false
   #     File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true
   #
-  def self.fnmatch: (string pattern, string | _ToPath path, ?int flags) -> bool
+  def self.fnmatch: (string pattern, path path, ?int flags) -> bool
 
   # <!--
   #   rdoc-file=dir.rb
@@ -1273,7 +1297,7 @@ class File < IO
   #     File.ftype("/dev/tty")            #=> "characterSpecial"
   #     File.ftype("/tmp/.X11-unix/X0")   #=> "socket"
   #
-  def self.ftype: (string | _ToPath file_name) -> String
+  def self.ftype: (path file_name) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1284,7 +1308,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.grpowned?: (string | _ToPath | IO file_name) -> bool
+  def self.grpowned?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1304,13 +1328,13 @@ class File < IO
   #     open("d", "w") {}
   #     p File.identical?("a", "d")      #=> false
   #
-  def self.identical?: (string | _ToPath | IO file_1, string | _ToPath | IO file_2) -> bool
+  def self.identical?: (path | IO file_1, path | IO file_2) -> bool
 
   # <!--
   #   rdoc-file=file.c
   #   - File.join(string, ...)  ->  string
   # -->
-  # Returns a new string formed by joining the strings using `"/"`.
+  # Returns a new string formed by joining the strings using <code>"/"</code>.
   #
   #     File.join("usr", "mail", "gumby")   #=> "usr/mail/gumby"
   #
@@ -1324,7 +1348,7 @@ class File < IO
   # change the permissions associated with the link, not the file referenced by
   # the link). Often not available.
   #
-  def self.lchmod: (int mode, *string | _ToPath file_name) -> Integer
+  def self.lchmod: (int mode, *path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -1334,7 +1358,7 @@ class File < IO
   # change the owner associated with the link, not the file referenced by the
   # link). Often not available. Returns number of files in the argument list.
   #
-  def self.lchown: (int? owner, int? group, *string | _ToPath file_name) -> Integer
+  def self.lchown: (int? owner, int? group, *path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -1347,7 +1371,7 @@ class File < IO
   #     File.link("testfile", ".testfile")   #=> 0
   #     IO.readlines(".testfile")[0]         #=> "This is line one\n"
   #
-  def self.link: (string | _ToPath old_name, string | _ToPath new_name) -> 0
+  def self.link: (path old_name, path new_name) -> 0
 
   # <!--
   #   rdoc-file=file.c
@@ -1360,7 +1384,7 @@ class File < IO
   #     File.stat('symlink').size  # => 47
   #     File.lstat('symlink').size # => 5
   #
-  def self.lstat: (string | _ToPath file_name) -> File::Stat
+  def self.lstat: (path file_name) -> File::Stat
 
   # <!--
   #   rdoc-file=file.c
@@ -1371,7 +1395,7 @@ class File < IO
   # opposed to its referent; for the inverse behavior, see File.utime. Returns the
   # number of file names in the argument list.
   #
-  def self.lutime: (Time | Numeric atime, Time | Numeric mtime, *string | _ToPath file_name) -> Integer
+  def self.lutime: (Time | Numeric atime, Time | Numeric mtime, *path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -1381,7 +1405,7 @@ class File < IO
   # FIFO's permissions. It is modified by the process's umask in the usual way:
   # the permissions of the created file are (mode & ~umask).
   #
-  def self.mkfifo: (string | _ToPath file_name, ?int mode) -> 0
+  def self.mkfifo: (path file_name, ?int mode) -> 0
 
   # <!--
   #   rdoc-file=file.c
@@ -1393,7 +1417,7 @@ class File < IO
   #
   #     File.mtime("testfile")   #=> Tue Apr 08 12:58:04 CDT 2003
   #
-  def self.mtime: (string | _ToPath | IO file_name) -> Time
+  def self.mtime: (path | IO file_name) -> Time
 
   # <!--
   #   rdoc-file=io.c
@@ -1407,19 +1431,65 @@ class File < IO
   # With a block given, calls the block with the File object and returns the
   # block's value.
   #
-  def self.open: (string | _ToPath | int file_name, ?string | int mode, ?int perm) -> instance
-               | [T] (string | _ToPath | int file_name, ?string | int mode, ?int perm) { (File) -> T } -> T
+  def self.open: (
+    path | int file_name,
+    ?string | int mode,
+    ?int perm,
+    # open options
+    ?mode: Integer | String,
+    ?flags: Integer,
+    ?external_encoding: encoding,
+    ?internal_encoding: encoding,
+    ?encoding: encoding,
+    ?textmode: boolish,
+    ?binmode: boolish,
+    ?autoclose: boolish,
+    ?path: path,
+    # encoding options
+    ?invalid: :replace | nil,
+    ?undef: :replace | nil,
+    ?replace: String | nil,
+    ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+    ?xml: :text | :attr | nil,
+    ?cr_newline: bool,
+    ?crlf_newline: bool,
+    ?universal_newline: bool
+  ) -> instance
+               | [T] (
+      path | int file_name,
+      ?string | int mode,
+      ?int perm,
+      # open options
+      ?mode: Integer | String,
+      ?flags: Integer,
+      ?external_encoding: encoding,
+      ?internal_encoding: encoding,
+      ?encoding: encoding,
+      ?textmode: boolish,
+      ?binmode: boolish,
+      ?autoclose: boolish,
+      ?path: path,
+      # encoding options
+      ?invalid: :replace | nil,
+      ?undef: :replace | nil,
+      ?replace: String | nil,
+      ?fallback: Hash[string, string] | ^(String) -> string | Method | nil,
+      ?xml: :text | :attr | nil,
+      ?cr_newline: bool,
+      ?crlf_newline: bool,
+      ?universal_newline: bool
+    ) { (File) -> T } -> T
 
   # <!--
   #   rdoc-file=file.c
   #   - File.owned?(file_name)   -> true or false
   # -->
-  # Returns `true` if the named file exists and the effective used id of the
+  # Returns `true` if the named file exists and the effective user id of the
   # calling process is the owner of the file.
   #
   # *file_name* can be an IO object.
   #
-  def self.owned?: (string | _ToPath | IO file_name) -> bool
+  def self.owned?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1427,10 +1497,27 @@ class File < IO
   # -->
   # Returns the string representation of the path
   #
-  #     File.path(File::NULL)           #=> "/dev/null"
-  #     File.path(Pathname.new("/tmp")) #=> "/tmp"
+  #        File.path(File::NULL)           #=> "/dev/null"
+  #        File.path(Pathname.new("/tmp")) #=> "/tmp"
+  #
+  # If `path` is not a String:
+  #
+  # 1.  If it has the `to_path` method, that method will be called to coerce to a
+  #     String.
+  #
+  # 2.  Otherwise, or if the coerced result is not a String too, the standard
+  #     coersion using `to_str` method will take place on that object. (See also
+  #     String.try_convert)
+  #
+  # The coerced string must satisfy the following conditions:
+  #
+  # 1.  It must be in an ASCII-compatible encoding; otherwise, an
+  #     Encoding::CompatibilityError is raised.
   #
-  def self.path: (string | _ToPath path) -> String
+  # 2.  It must not contain the NUL character (<code>\0</code>); otherwise, an
+  #     ArgumentError is raised.
+  #
+  def self.path: (path path) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1442,7 +1529,7 @@ class File < IO
   #     File.pipe?('tmp/fifo') # => true
   #     File.pipe?('t.txt')    # => false
   #
-  def self.pipe?: (string | _ToPath | IO file_name) -> bool
+  def self.pipe?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1454,7 +1541,7 @@ class File < IO
   # Note that some OS-level security features may cause this to return true even
   # though the file is not readable by the effective user/group.
   #
-  def self.readable?: (string | _ToPath file_name) -> bool
+  def self.readable?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1466,7 +1553,7 @@ class File < IO
   # Note that some OS-level security features may cause this to return true even
   # though the file is not readable by the real user/group.
   #
-  def self.readable_real?: (string | _ToPath file_name) -> bool
+  def self.readable_real?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1478,7 +1565,7 @@ class File < IO
   #     File.symlink("testfile", "link2test")   #=> 0
   #     File.readlink("link2test")              #=> "testfile"
   #
-  def self.readlink: (string | _ToPath link_name) -> String
+  def self.readlink: (path link_name) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1492,7 +1579,7 @@ class File < IO
   #
   # The last component of the real pathname can be nonexistent.
   #
-  def self.realdirpath: (string | _ToPath pathname, ?string | _ToPath dir_string) -> String
+  def self.realdirpath: (path pathname, ?path dir_string) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1506,7 +1593,7 @@ class File < IO
   #
   # All components of the pathname must exist when this method is called.
   #
-  def self.realpath: (string | _ToPath pathname, ?string | _ToPath dir_string) -> String
+  def self.realpath: (path pathname, ?path dir_string) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -1517,7 +1604,7 @@ class File < IO
   #
   #     File.rename("afile", "afile.bak")   #=> 0
   #
-  def self.rename: (string | _ToPath old_name, string | _ToPath new_name) -> 0
+  def self.rename: (path old_name, path new_name) -> 0
 
   # <!--
   #   rdoc-file=file.c
@@ -1527,7 +1614,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.setgid?: (string | _ToPath | IO file_name) -> bool
+  def self.setgid?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1537,7 +1624,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.setuid?: (string | _ToPath | IO file_name) -> bool
+  def self.setuid?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1547,7 +1634,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.size: (string | _ToPath | IO file_name) -> Integer
+  def self.size: (path | IO file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -1558,7 +1645,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.size?: (string | _ToPath | IO file_name) -> Integer?
+  def self.size?: (path | IO file_name) -> Integer?
 
   # <!--
   #   rdoc-file=file.c
@@ -1570,7 +1657,7 @@ class File < IO
   #     File.socket?(Socket.new(:INET, :STREAM)) # => true
   #     File.socket?(File.new('t.txt'))          # => false
   #
-  def self.socket?: (string | _ToPath | IO file_name) -> bool
+  def self.socket?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1581,7 +1668,7 @@ class File < IO
   #
   #     File.split("/home/gumby/.profile")   #=> ["/home/gumby", ".profile"]
   #
-  def self.split: (string | _ToPath file_name) -> [ String, String ]
+  def self.split: (path file_name) -> [ String, String ]
 
   # <!--
   #   rdoc-file=file.c
@@ -1591,7 +1678,7 @@ class File < IO
   #
   #     File.stat('t.txt').class # => File::Stat
   #
-  def self.stat: (string | _ToPath file_name) -> File::Stat
+  def self.stat: (path file_name) -> File::Stat
 
   # <!--
   #   rdoc-file=file.c
@@ -1601,7 +1688,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.sticky?: (string | _ToPath | IO file_name) -> bool
+  def self.sticky?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1613,7 +1700,7 @@ class File < IO
   #
   #     File.symlink("testfile", "link2test")   #=> 0
   #
-  def self.symlink: (string | _ToPath old_name, string | _ToPath new_name) -> 0
+  def self.symlink: (path old_name, path new_name) -> 0
 
   # <!--
   #   rdoc-file=file.c
@@ -1625,7 +1712,7 @@ class File < IO
   #     File.symlink?('symlink') # => true
   #     File.symlink?('t.txt')   # => false
   #
-  def self.symlink?: (string | _ToPath file_name) -> bool
+  def self.symlink?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1640,7 +1727,7 @@ class File < IO
   #     File.truncate("out", 5)   #=> 0
   #     File.size("out")          #=> 5
   #
-  def self.truncate: (string | _ToPath file_name, int length) -> 0
+  def self.truncate: (path file_name, int length) -> 0
 
   # <!--
   #   rdoc-file=file.c
@@ -1664,13 +1751,13 @@ class File < IO
   # -->
   # Deletes the named files, returning the number of names passed as arguments.
   # Raises an exception on any error. Since the underlying implementation relies
-  # on the `unlink(2)` system call, the type of exception raised depends on its
-  # error type (see https://linux.die.net/man/2/unlink) and has the form of e.g.
-  # Errno::ENOENT.
+  # on the <code>unlink(2)</code> system call, the type of exception raised
+  # depends on its error type (see https://linux.die.net/man/2/unlink) and has the
+  # form of e.g. Errno::ENOENT.
   #
   # See also Dir::rmdir.
   #
-  def self.unlink: (*string | _ToPath file_name) -> Integer
+  def self.unlink: (*path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -1681,7 +1768,7 @@ class File < IO
   # than the link itself; for the inverse behavior see File.lutime. Returns the
   # number of file names in the argument list.
   #
-  def self.utime: (Time | Numeric atime, Time | Numeric mtime, *string | _ToPath file_name) -> Integer
+  def self.utime: (Time | Numeric atime, Time | Numeric mtime, *path file_name) -> Integer
 
   # <!--
   #   rdoc-file=file.c
@@ -1689,7 +1776,7 @@ class File < IO
   # -->
   # If *file_name* is readable by others, returns an integer representing the file
   # permission bits of *file_name*. Returns `nil` otherwise. The meaning of the
-  # bits is platform dependent; on Unix systems, see `stat(2)`.
+  # bits is platform dependent; on Unix systems, see <code>stat(2)</code>.
   #
   # *file_name* can be an IO object.
   #
@@ -1697,7 +1784,7 @@ class File < IO
   #     m = File.world_readable?("/etc/passwd")
   #     sprintf("%o", m)                              #=> "644"
   #
-  def self.world_readable?: (string | _ToPath | IO file_name) -> Integer?
+  def self.world_readable?: (path | IO file_name) -> Integer?
 
   # <!--
   #   rdoc-file=file.c
@@ -1705,7 +1792,7 @@ class File < IO
   # -->
   # If *file_name* is writable by others, returns an integer representing the file
   # permission bits of *file_name*. Returns `nil` otherwise. The meaning of the
-  # bits is platform dependent; on Unix systems, see `stat(2)`.
+  # bits is platform dependent; on Unix systems, see <code>stat(2)</code>.
   #
   # *file_name* can be an IO object.
   #
@@ -1713,7 +1800,7 @@ class File < IO
   #     m = File.world_writable?("/tmp")
   #     sprintf("%o", m)                              #=> "777"
   #
-  def self.world_writable?: (string | _ToPath | IO file_name) -> Integer?
+  def self.world_writable?: (path | IO file_name) -> Integer?
 
   # <!--
   #   rdoc-file=file.c
@@ -1725,7 +1812,7 @@ class File < IO
   # Note that some OS-level security features may cause this to return true even
   # though the file is not writable by the effective user/group.
   #
-  def self.writable?: (string | _ToPath file_name) -> bool
+  def self.writable?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1737,7 +1824,7 @@ class File < IO
   # Note that some OS-level security features may cause this to return true even
   # though the file is not writable by the real user/group.
   #
-  def self.writable_real?: (string | _ToPath file_name) -> bool
+  def self.writable_real?: (path file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1747,7 +1834,7 @@ class File < IO
   #
   # *file_name* can be an IO object.
   #
-  def self.zero?: (string | _ToPath | IO file_name) -> bool
+  def self.zero?: (path | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
@@ -1778,7 +1865,8 @@ class File < IO
   # -->
   # Changes permission bits on *file* to the bit pattern represented by
   # *mode_int*. Actual effects are platform dependent; on Unix systems, see
-  # `chmod(2)` for details. Follows symbolic links. Also see File#lchmod.
+  # <code>chmod(2)</code> for details. Follows symbolic links. Also see
+  # File#lchmod.
   #
   #     f = File.new("out", "w");
   #     f.chmod(0644)   #=> 0
@@ -1816,18 +1904,18 @@ class File < IO
   #   rdoc-file=file.c
   #   - flock(locking_constant) -> 0 or false
   # -->
-  # Locks or unlocks file `self` according to the given `locking_constant`,
+  # Locks or unlocks file +self+ according to the given `locking_constant`,
   # a bitwise OR of the values in the table below.
   # Not available on all platforms.
-  # Returns `false` if `File::LOCK_NB` is specified and the operation would have
-  # blocked;
+  # Returns `false` if <code>File::LOCK_NB</code> is specified and the operation
+  # would have blocked;
   # otherwise returns `0`.
-  #    Constant    |    Lock    |                                                    Effect
-  # ---------------|------------|--------------------------------------------------------------------------------------------------------------
-  # +File::LOCK_EX+| Exclusive  |                      Only one process may hold an exclusive lock for +self+ at a time.
-  # +File::LOCK_NB+|Non-blocking|No blocking; may be combined with +File::LOCK_SH+ or +File::LOCK_EX+ using the bitwise OR operator <tt>|</tt>.
-  # +File::LOCK_SH+|   Shared   |                 Multiple processes may each hold a shared lock for +self+ at the same time.
-  # +File::LOCK_UN+|   Unlock   |                                Remove an existing lock held by this process.
+  #    Constant    |    Lock    |                                                      Effect
+  # ---------------|------------|------------------------------------------------------------------------------------------------------------------
+  # +File::LOCK_EX+| Exclusive  |                        Only one process may hold an exclusive lock for +self+ at a time.
+  # +File::LOCK_NB+|Non-blocking|No blocking; may be combined with +File::LOCK_SH+ or +File::LOCK_EX+ using the bitwise OR operator <code>|</code>.
+  # +File::LOCK_SH+|   Shared   |                   Multiple processes may each hold a shared lock for +self+ at the same time.
+  # +File::LOCK_UN+|   Unlock   |                                  Remove an existing lock held by this process.
   # Example:
   #     # Update a counter using an exclusive lock.
   # # Don't use File::WRONLY because it truncates the file.
@@ -1953,7 +2041,7 @@ File::SEPARATOR: String
 File::Separator: String
 
 # <!-- rdoc-file=file.c -->
-# Module `File::Constants` defines file-related constants.
+# Module <code>File::Constants</code> defines file-related constants.
 #
 # There are two families of constants here:
 #
@@ -2217,14 +2305,14 @@ File::Separator: String
 #
 # #### File::FNM_DOTMATCH
 #
-# Flag File::FNM_DOTMATCH makes the `'*'` pattern match a filename starting with
-# `'.'`.
+# Flag File::FNM_DOTMATCH makes the <code>'*'</code> pattern match a filename
+# starting with <code>'.'</code>.
 #
 # #### File::FNM_EXTGLOB
 #
-# Flag File::FNM_EXTGLOB enables pattern `'{*a*,*b*}'`, which matches pattern
-# '*a*' and pattern '*b*'; behaves like a [regexp union](rdoc-ref:Regexp.union)
-# (e.g., `'(?:*a*|*b*)'`):
+# Flag File::FNM_EXTGLOB enables pattern <code>'{_a_,_b_}'</code>, which matches
+# pattern '*a*' and pattern '*b*'; behaves like a [regexp
+# union](rdoc-ref:Regexp.union) (e.g., <code>'(?:_a_|_b_)'</code>):
 #
 #     pattern = '{LEGAL,BSDL}'
 #     Dir.glob(pattern)      # => ["LEGAL", "BSDL"]
@@ -2233,12 +2321,13 @@ File::Separator: String
 #
 # #### File::FNM_NOESCAPE
 #
-# Flag File::FNM_NOESCAPE disables `'\'` escaping.
+# Flag File::FNM_NOESCAPE disables <code>'\'</code> escaping.
 #
 # #### File::FNM_PATHNAME
 #
-# Flag File::FNM_PATHNAME specifies that patterns `'*'` and `'?'` do not match
-# the directory separator (the value of constant File::SEPARATOR).
+# Flag File::FNM_PATHNAME specifies that patterns <code>'*'</code> and
+# <code>'?'</code> do not match the directory separator (the value of constant
+# File::SEPARATOR).
 #
 # #### File::FNM_SHORTNAME
 #
@@ -2257,8 +2346,8 @@ File::Separator: String
 #
 # Flag File::NULL contains the string value of the null device:
 #
-# *   On a Unix-like OS, `'/dev/null'`.
-# *   On Windows, `'NUL'`.
+# *   On a Unix-like OS, <code>'/dev/null'</code>.
+# *   On Windows, <code>'NUL'</code>.
 #
 module File::Constants
 end
@@ -2429,10 +2518,8 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - new(p1)
+  #   - File::Stat.new(file_name)  -> stat
   # -->
-  # File::Stat.new(file_name)  -> stat
-  #
   # Create a File::Stat object for the given file name (raising an exception if
   # the file doesn't exist).
   #
@@ -2440,16 +2527,31 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - stat <=> other_stat    -> -1, 0, 1, nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # Compares File::Stat objects by comparing their respective modification times.
+  # Compares `self` and `other`, by comparing their modification times; that is,
+  # by comparing <code>self.mtime</code> and <code>other.mtime</code>.
+  #
+  # Returns:
+  #
+  # *   <code>-1</code>, if <code>self.mtime</code> is earlier.
+  # *   `0`, if the two values are equal.
+  # *   `1`, if <code>self.mtime</code> is later.
+  # *   `nil`, if `other` is not a File::Stat object.
+  #
+  # Examples:
   #
-  # `nil` is returned if `other_stat` is not a File::Stat object
+  #     stat0 = File.stat('README.md')
+  #     stat1 = File.stat('NEWS.md')
+  #     stat0.mtime         # => 2025-12-20 15:33:05.6972341 -0600
+  #     stat1.mtime         # => 2025-12-20 16:02:08.2672945 -0600
+  #     stat0 <=> stat1     # => -1
+  #     stat0 <=> stat0.dup # => 0
+  #     stat1 <=> stat0     # => 1
+  #     stat0 <=> :foo      # => nil
   #
-  #     f1 = File.new("f1", "w")
-  #     sleep 1
-  #     f2 = File.new("f2", "w")
-  #     f1.stat <=> f2.stat   #=> -1
+  # Class File::Stat includes module Comparable, each of whose methods uses
+  # File::Stat#<=> for comparison.
   #
   def <=>: (File::Stat other) -> Integer
          | (untyped) -> nil
@@ -2558,7 +2660,7 @@ class File::Stat < Object
   #   rdoc-file=file.c
   #   - stat.dev_major   -> integer
   # -->
-  # Returns the major part of `File_Stat#dev` or `nil`.
+  # Returns the major part of <code>File_Stat#dev</code> or `nil`.
   #
   #     File.stat("/dev/fd1").dev_major   #=> 2
   #     File.stat("/dev/tty").dev_major   #=> 5
@@ -2569,7 +2671,7 @@ class File::Stat < Object
   #   rdoc-file=file.c
   #   - stat.dev_minor   -> integer
   # -->
-  # Returns the minor part of `File_Stat#dev` or `nil`.
+  # Returns the minor part of <code>File_Stat#dev</code> or `nil`.
   #
   #     File.stat("/dev/fd1").dev_minor   #=> 1
   #     File.stat("/dev/tty").dev_minor   #=> 0
@@ -2603,7 +2705,8 @@ class File::Stat < Object
   #   rdoc-file=file.c
   #   - stat.executable_real?    -> true or false
   # -->
-  # Same as `executable?`, but tests using the real owner of the process.
+  # Same as <code>executable?</code>, but tests using the real owner of the
+  # process.
   #
   def executable_real?: () -> bool
 
@@ -2683,7 +2786,7 @@ class File::Stat < Object
   #   - stat.mode   -> integer
   # -->
   # Returns an integer representing the permission bits of *stat*. The meaning of
-  # the bits is platform dependent; on Unix systems, see `stat(2)`.
+  # the bits is platform dependent; on Unix systems, see <code>stat(2)</code>.
   #
   #     File.chmod(0644, "testfile")   #=> 1
   #     s = File.stat("testfile")
@@ -2750,7 +2853,7 @@ class File::Stat < Object
   #   rdoc-file=file.c
   #   - stat.rdev_major   -> integer
   # -->
-  # Returns the major part of `File_Stat#rdev` or `nil`.
+  # Returns the major part of <code>File_Stat#rdev</code> or `nil`.
   #
   #     File.stat("/dev/fd1").rdev_major   #=> 2
   #     File.stat("/dev/tty").rdev_major   #=> 5
@@ -2761,7 +2864,7 @@ class File::Stat < Object
   #   rdoc-file=file.c
   #   - stat.rdev_minor   -> integer
   # -->
-  # Returns the minor part of `File_Stat#rdev` or `nil`.
+  # Returns the minor part of <code>File_Stat#rdev</code> or `nil`.
   #
   #     File.stat("/dev/fd1").rdev_minor   #=> 1
   #     File.stat("/dev/tty").rdev_minor   #=> 0
@@ -2884,7 +2987,7 @@ class File::Stat < Object
   # -->
   # If *stat* is readable by others, returns an integer representing the file
   # permission bits of *stat*. Returns `nil` otherwise. The meaning of the bits is
-  # platform dependent; on Unix systems, see `stat(2)`.
+  # platform dependent; on Unix systems, see <code>stat(2)</code>.
   #
   #     m = File.stat("/etc/passwd").world_readable?  #=> 420
   #     sprintf("%o", m)                              #=> "644"
@@ -2897,7 +3000,7 @@ class File::Stat < Object
   # -->
   # If *stat* is writable by others, returns an integer representing the file
   # permission bits of *stat*. Returns `nil` otherwise. The meaning of the bits is
-  # platform dependent; on Unix systems, see `stat(2)`.
+  # platform dependent; on Unix systems, see <code>stat(2)</code>.
   #
   #     m = File.stat("/tmp").world_writable?         #=> 511
   #     sprintf("%o", m)                              #=> "777"