rbs 2.8.4 → 3.8.1

data/core/file.rbs

@@ -1,330 +1,853 @@
 # <!-- rdoc-file=file.c -->
-# A File is an abstraction of any file object accessible by the program and is
-# closely associated with class IO.  File includes the methods of module
-# FileTest as class methods, allowing you to write (for example)
-# `File.exist?("foo")`.
-#
-# In the description of File methods, *permission bits* are a platform-specific
-# set of bits that indicate permissions of a file. On Unix-based systems,
-# permissions are viewed as a set of three octets, for the owner, the group, and
-# the rest of the world. For each of these entities, permissions may be set to
-# read, write, or execute the file:
-#
-# The permission bits `0644` (in octal) would thus be interpreted as read/write
-# for owner, and read-only for group and other. Higher-order bits may also be
-# used to indicate the type of file (plain, directory, pipe, socket, and so on)
-# and various other special features. If the permissions are for a directory,
-# the meaning of the execute bit changes; when set the directory can be
-# searched.
-#
-# On non-Posix operating systems, there may be only the ability to make a file
-# read-only or read-write. In this case, the remaining permission bits will be
-# synthesized to resemble typical values. For instance, on Windows NT the
-# default permission bits are `0644`, which means read/write for owner,
-# read-only for all others. The only change that can be made is to make the file
-# read-only, which is reported as `0444`.
-#
-# Various constants for the methods in File can be found in File::Constants.
+# A File object is a representation of a file in the underlying platform.
 #
-# ## What's Here
+# Class File extends module FileTest, supporting such singleton methods as
+# `File.exist?`.
 #
-# First, what's elsewhere. Class File:
+# ## About the Examples
 #
-# *   Inherits from [class IO](IO.html#class-IO-label-What-27s+Here), in
-#     particular, methods for creating, reading, and writing files
-# *   Includes [module
-#     FileTest](FileTest.html#module-FileTest-label-What-27s+Here). which
-#     provides dozens of additional methods.
+# Many examples here use these variables:
 #
+#     # English text with newlines.
+#     text = <<~EOT
+#       First line
+#       Second line
 #
-# Here, class File provides methods that are useful for:
+#       Fourth line
+#       Fifth line
+#     EOT
 #
-# *   [Creating](#class-File-label-Creating)
-# *   [Querying](#class-File-label-Querying)
-# *   [Settings](#class-File-label-Settings)
-# *   [Other](#class-File-label-Other)
+#     # Russian text.
+#     russian = "\u{442 435 441 442}" # => "тест"
 #
+#     # Binary data.
+#     data = "\u9990\u9991\u9992\u9993\u9994"
 #
-# ### Creating
+#     # Text file.
+#     File.write('t.txt', text)
 #
-#     ::new
-# :       Opens the file at the given path; returns the file.
+#     # File with Russian text.
+#     File.write('t.rus', russian)
 #
-#     ::open
-# :       Same as ::new, but when given a block will yield the file to the
-#         block, and close the file upon exiting the block.
+#     # File with binary data.
+#     f = File.new('t.dat', 'wb:UTF-16')
+#     f.write(data)
+#     f.close
 #
-#     ::link
-# :       Creates a new name for an existing file using a hard link.
+# ## Access Modes
 #
-#     ::mkfifo
-# :       Returns the FIFO file created at the given path.
+# Methods File.new and File.open each create a File object for a given file
+# path.
 #
-#     ::symlink
-# :       Creates a symbolic link for the given file path.
+# ### String Access Modes
 #
+# Methods File.new and File.open each may take string argument `mode`, which:
 #
+# *   Begins with a 1- or 2-character [read/write
+#     mode](rdoc-ref:File@Read-2FWrite+Mode).
+# *   May also contain a 1-character [data mode](rdoc-ref:File@Data+Mode).
+# *   May also contain a 1-character [file-create
+#     mode](rdoc-ref:File@File-Create+Mode).
 #
-# ### Querying
+# #### Read/Write Mode
 #
-# *Paths*
+# The read/write `mode` determines:
 #
-#     ::absolute_path
-# :       Returns the absolute file path for the given path.
+# *   Whether the file is to be initially truncated.
 #
-#     ::absolute_path?
-# :       Returns whether the given path is the absolute file path.
+# *   Whether reading is allowed, and if so:
 #
-#     ::basename
-# :       Returns the last component of the given file path.
+#     *   The initial read position in the file.
+#     *   Where in the file reading can occur.
 #
-#     ::dirname
-# :       Returns all but the last component of the given file path.
+# *   Whether writing is allowed, and if so:
 #
-#     ::expand_path
-# :       Returns the absolute file path for the given path, expanding `~` for a
-#         home directory.
+#     *   The initial write position in the file.
+#     *   Where in the file writing can occur.
 #
-#     ::extname
-# :       Returns the file extension for the given file path.
+# These tables summarize:
 #
-#     ::fnmatch? (aliased as ::fnmatch)
-# :       Returns whether the given file path matches the given pattern.
+#     Read/Write Modes for Existing File
 #
-#     ::join
-# :       Joins path components into a single path string.
+#     |------|-----------|----------|----------|----------|-----------|
+#     | R/W  | Initial   |          | Initial  |          | Initial   |
+#     | Mode | Truncate? |  Read    | Read Pos |  Write   | Write Pos |
+#     |------|-----------|----------|----------|----------|-----------|
+#     | 'r'  |    No     | Anywhere |    0     |   Error  |     -     |
+#     | 'w'  |    Yes    |   Error  |    -     | Anywhere |     0     |
+#     | 'a'  |    No     |   Error  |    -     | End only |    End    |
+#     | 'r+' |    No     | Anywhere |    0     | Anywhere |     0     |
+#     | 'w+' |    Yes    | Anywhere |    0     | Anywhere |     0     |
+#     | 'a+' |    No     | Anywhere |   End    | End only |    End    |
+#     |------|-----------|----------|----------|----------|-----------|
 #
-#     ::path
-# :       Returns the string representation of the given path.
+#     Read/Write Modes for \File To Be Created
 #
-#     ::readlink
-# :       Returns the path to the file at the given symbolic link.
+#     |------|----------|----------|----------|-----------|
+#     | R/W  |          | Initial  |          | Initial   |
+#     | Mode |  Read    | Read Pos |  Write   | Write Pos |
+#     |------|----------|----------|----------|-----------|
+#     | 'w'  |   Error  |    -     | Anywhere |     0     |
+#     | 'a'  |   Error  |    -     | End only |     0     |
+#     | 'w+' | Anywhere |    0     | Anywhere |     0     |
+#     | 'a+' | Anywhere |    0     | End only |    End    |
+#     |------|----------|----------|----------|-----------|
 #
-#     ::realdirpath
-# :       Returns the real path for the given file path, where the last
-#         component need not exist.
+# Note that modes `'r'` and `'r+'` are not allowed for a non-existent file
+# (exception raised).
 #
-#     ::realpath
-# :       Returns the real path for the given file path, where all components
-#         must exist.
+# In the tables:
 #
-#     ::split
-# :       Returns an array of two strings: the directory name and basename of
-#         the file at the given path.
+# *   `Anywhere` means that methods IO#rewind, IO#pos=, and IO#seek may be used
+#     to change the file's position, so that allowed reading or writing may
+#     occur anywhere in the file.
+# *   `End only` means that writing can occur only at end-of-file, and that
+#     methods IO#rewind, IO#pos=, and IO#seek do not affect writing.
+# *   `Error` means that an exception is raised if disallowed reading or writing
+#     is attempted.
 #
-#     #path (aliased as #to_path)
-# :       Returns the string representation of the given path.
+# ##### Read/Write Modes for Existing File
 #
+# *   `'r'`:
 #
+#     *   File is not initially truncated:
 #
-# *Times*
+#             f = File.new('t.txt') # => #<File:t.txt>
+#             f.size == 0           # => false
 #
-#     ::atime
-# :       Returns a Time for the most recent access to the given file.
+#     *   File's initial read position is 0:
 #
-#     ::birthtime
-# :       Returns a Time  for the creation of the given file.
+#             f.pos # => 0
 #
-#     ::ctime
-# :       Returns a Time  for the metadata change of the given file.
+#     *   File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:
 #
-#     ::mtime
-# :       Returns a Time for the most recent data modification to the content of
-#         the given file.
+#             f.readline # => "First line\n"
+#             f.readline # => "Second line\n"
 #
-#     #atime
-# :       Returns a Time for the most recent access to `self`.
+#             f.rewind
+#             f.readline # => "First line\n"
 #
-#     #birthtime
-# :       Returns a Time  the creation for `self`.
+#             f.pos = 1
+#             f.readline # => "irst line\n"
 #
-#     #ctime
-# :       Returns a Time for the metadata change of `self`.
+#             f.seek(1, :CUR)
+#             f.readline # => "econd line\n"
 #
-#     #mtime
-# :       Returns a Time for the most recent data modification to the content of
-#         `self`.
+#     *   Writing is not allowed:
 #
+#             f.write('foo') # Raises IOError.
 #
+# *   `'w'`:
 #
-# *Types*
+#     *   File is initially truncated:
 #
-#     ::blockdev?
-# :       Returns whether the file at the given path is a block device.
+#             path = 't.tmp'
+#             File.write(path, text)
+#             f = File.new(path, 'w')
+#             f.size == 0 # => true
 #
-#     ::chardev?
-# :       Returns whether the file at the given path is a character device.
+#     *   File's initial write position is 0:
 #
-#     ::directory?
-# :       Returns whether the file at the given path is a diretory.
+#             f.pos # => 0
 #
-#     ::executable?
-# :       Returns whether the file at the given path is executable by the
-#         effective user and group of the current process.
+#     *   File may be written anywhere (even past end-of-file); see IO#rewind,
+#         IO#pos=, IO#seek:
 #
-#     ::executable_real?
-# :       Returns whether the file at the given path is executable by the real
-#         user and group of the current process.
+#             f.write('foo')
+#             f.flush
+#             File.read(path) # => "foo"
+#             f.pos # => 3
 #
-#     ::exist?
-# :       Returns whether the file at the given path exists.
+#             f.write('bar')
+#             f.flush
+#             File.read(path) # => "foobar"
+#             f.pos # => 6
 #
-#     ::file?
-# :       Returns whether the file at the given path is a regular file.
+#             f.rewind
+#             f.write('baz')
+#             f.flush
+#             File.read(path) # => "bazbar"
+#             f.pos # => 3
 #
-#     ::ftype
-# :       Returns a string giving the type of the file at the given path.
+#             f.pos = 3
+#             f.write('foo')
+#             f.flush
+#             File.read(path) # => "bazfoo"
+#             f.pos # => 6
 #
-#     ::grpowned?
-# :       Returns whether the effective group of the current process owns the
-#         file at the given path.
+#             f.seek(-3, :END)
+#             f.write('bam')
+#             f.flush
+#             File.read(path) # => "bazbam"
+#             f.pos # => 6
 #
-#     ::identical?
-# :       Returns whether the files at two given paths are identical.
+#             f.pos = 8
+#             f.write('bah')  # Zero padding as needed.
+#             f.flush
+#             File.read(path) # => "bazbam\u0000\u0000bah"
+#             f.pos # => 11
 #
-#     ::lstat
-# :       Returns the File::Stat object for the last symbolic link in the given
-#         path.
+#     *   Reading is not allowed:
 #
-#     ::owned?
-# :       Returns whether the effective user of the current process owns the
-#         file at the given path.
+#             f.read # Raises IOError.
 #
-#     ::pipe?
-# :       Returns whether the file at the given path is a pipe.
+# *   `'a'`:
 #
-#     ::readable?
-# :       Returns whether the file at the given path is readable by the
-#         effective user and group of the current process.
+#     *   File is not initially truncated:
 #
-#     ::readable_real?
-# :       Returns whether the file at the given path is readable by the real
-#         user and group of the current process.
+#             path = 't.tmp'
+#             File.write(path, 'foo')
+#             f = File.new(path, 'a')
+#             f.size == 0 # => false
 #
-#     ::setgid?
-# :       Returns whether the setgid bit is set for the file at the given path.
+#     *   File's initial position is 0 (but is ignored):
 #
-#     ::setuid?
-# :       Returns whether the setuid bit is set for the file at the given path.
+#             f.pos # => 0
 #
-#     ::socket?
-# :       Returns whether the file at the given path is a socket.
+#     *   File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek
+#         do not affect writing:
 #
-#     ::stat
-# :       Returns the File::Stat object for the file at the given path.
+#             f.write('bar')
+#             f.flush
+#             File.read(path) # => "foobar"
+#             f.write('baz')
+#             f.flush
+#             File.read(path) # => "foobarbaz"
 #
-#     ::sticky?
-# :       Returns whether the file at the given path has its sticky bit set.
+#             f.rewind
+#             f.write('bat')
+#             f.flush
+#             File.read(path) # => "foobarbazbat"
 #
-#     ::symlink?
-# :       Returns whether the file at the given path is a symbolic link.
+#     *   Reading is not allowed:
 #
-#     ::umask
-# :       Returns the umask value for the current process.
+#             f.read # Raises IOError.
 #
-#     ::world_readable?
-# :       Returns whether the file at the given path is readable by others.
+# *   `'r+'`:
 #
-#     ::world_writable?
-# :       Returns whether the file at the given path is writable by others.
+#     *   File is not initially truncated:
 #
-#     ::writable?
-# :       Returns whether the file at the given path is writable by the
-#         effective user and group of the current process.
+#             path = 't.tmp'
+#             File.write(path, text)
+#             f = File.new(path, 'r+')
+#             f.size == 0 # => false
 #
-#     ::writable_real?
-# :       Returns whether the file at the given path is writable by the real
-#         user and group of the current process.
+#     *   File's initial read position is 0:
 #
-#     #lstat
-# :       Returns the File::Stat object for the last symbolic link in the path
-#         for `self`.
+#             f.pos # => 0
 #
+#     *   File may be read or written anywhere (even past end-of-file); see
+#         IO#rewind, IO#pos=, IO#seek:
 #
+#             f.readline # => "First line\n"
+#             f.readline # => "Second line\n"
 #
-# *Contents*
+#             f.rewind
+#             f.readline # => "First line\n"
 #
-#     ::empty? (aliased as ::zero?)
-# :       Returns whether the file at the given path exists and is empty.
+#             f.pos = 1
+#             f.readline # => "irst line\n"
 #
-#     ::size
-# :       Returns the size (bytes) of the file at the given path.
+#             f.seek(1, :CUR)
+#             f.readline # => "econd line\n"
 #
-#     ::size?
-# :       Returns `nil` if there is no file at the given path, or if that file
-#         is empty; otherwise returns the file size (bytes).
+#             f.rewind
+#             f.write('WWW')
+#             f.flush
+#             File.read(path)
+#             # => "WWWst line\nSecond line\nFourth line\nFifth line\n"
 #
-#     #size
-# :       Returns the size (bytes) of `self`.
+#             f.pos = 10
+#             f.write('XXX')
+#             f.flush
+#             File.read(path)
+#             # => "WWWst lineXXXecond line\nFourth line\nFifth line\n"
 #
+#             f.seek(-6, :END)
+#             # => 0
+#             f.write('YYY')
+#             # => 3
+#             f.flush
+#             # => #<File:t.tmp>
+#             File.read(path)
+#             # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n"
 #
+#             f.seek(2, :END)
+#             f.write('ZZZ') # Zero padding as needed.
+#             f.flush
+#             File.read(path)
+#             # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"
 #
-# ### Settings
+# *   `'a+'`:
 #
-#     ::chmod
-# :       Changes permissions of the file at the given path.
+#     *   File is not initially truncated:
 #
-#     ::chown
-# :       Change ownership of the file at the given path.
+#             path = 't.tmp'
+#             File.write(path, 'foo')
+#             f = File.new(path, 'a+')
+#             f.size == 0 # => false
 #
-#     ::lchmod
-# :       Changes permissions of the last symbolic link in the given path.
+#     *   File's initial read position is 0:
 #
-#     ::lchown
-# :       Change ownership of the last symbolic in the given path.
+#             f.pos # => 0
 #
-#     ::lutime
-# :       For each given file path, sets the access time and modification time
-#         of the last symbolic link in the path.
+#     *   File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek
+#         do not affect writing:
 #
-#     ::rename
-# :       Moves the file at one given path to another given path.
+#             f.write('bar')
+#             f.flush
+#             File.read(path)      # => "foobar"
+#             f.write('baz')
+#             f.flush
+#             File.read(path)      # => "foobarbaz"
 #
-#     ::utime
-# :       Sets the access time and modification time of each file at the given
-#         paths.
+#             f.rewind
+#             f.write('bat')
+#             f.flush
+#             File.read(path) # => "foobarbazbat"
 #
-#     #flock
-# :       Locks or unlocks `self`.
+#     *   File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:
 #
+#             f.rewind
+#             f.read # => "foobarbazbat"
 #
+#             f.pos = 3
+#             f.read # => "barbazbat"
 #
-# ### Other
+#             f.seek(-3, :END)
+#             f.read # => "bat"
+#
+# ##### Read/Write Modes for File To Be Created
+#
+# Note that modes `'r'` and `'r+'` are not allowed for a non-existent file
+# (exception raised).
+#
+# *   `'w'`:
+#
+#     *   File's initial write position is 0:
+#
+#             path = 't.tmp'
+#             FileUtils.rm_f(path)
+#             f = File.new(path, 'w')
+#             f.pos # => 0
+#
+#     *   File may be written anywhere (even past end-of-file); see IO#rewind,
+#         IO#pos=, IO#seek:
+#
+#             f.write('foo')
+#             f.flush
+#             File.read(path) # => "foo"
+#             f.pos # => 3
+#
+#             f.write('bar')
+#             f.flush
+#             File.read(path) # => "foobar"
+#             f.pos # => 6
+#
+#             f.rewind
+#             f.write('baz')
+#             f.flush
+#             File.read(path) # => "bazbar"
+#             f.pos # => 3
+#
+#             f.pos = 3
+#             f.write('foo')
+#             f.flush
+#             File.read(path) # => "bazfoo"
+#             f.pos # => 6
+#
+#             f.seek(-3, :END)
+#             f.write('bam')
+#             f.flush
+#             File.read(path) # => "bazbam"
+#             f.pos # => 6
+#
+#             f.pos = 8
+#             f.write('bah')  # Zero padding as needed.
+#             f.flush
+#             File.read(path) # => "bazbam\u0000\u0000bah"
+#             f.pos # => 11
+#
+#     *   Reading is not allowed:
+#
+#             f.read # Raises IOError.
+#
+# *   `'a'`:
+#
+#     *   File's initial write position is 0:
+#
+#             path = 't.tmp'
+#             FileUtils.rm_f(path)
+#             f = File.new(path, 'a')
+#             f.pos # => 0
+#
+#     *   Writing occurs only at end-of-file:
+#
+#             f.write('foo')
+#             f.pos # => 3
+#             f.write('bar')
+#             f.pos # => 6
+#             f.flush
+#             File.read(path) # => "foobar"
+#
+#             f.rewind
+#             f.write('baz')
+#             f.flush
+#             File.read(path) # => "foobarbaz"
+#
+#     *   Reading is not allowed:
+#
+#             f.read # Raises IOError.
+#
+# *   `'w+'`:
+#
+#     *   File's initial position is 0:
+#
+#             path = 't.tmp'
+#             FileUtils.rm_f(path)
+#             f = File.new(path, 'w+')
+#             f.pos # => 0
+#
+#     *   File may be written anywhere (even past end-of-file); see IO#rewind,
+#         IO#pos=, IO#seek:
+#
+#             f.write('foo')
+#             f.flush
+#             File.read(path) # => "foo"
+#             f.pos # => 3
+#
+#             f.write('bar')
+#             f.flush
+#             File.read(path) # => "foobar"
+#             f.pos # => 6
+#
+#             f.rewind
+#             f.write('baz')
+#             f.flush
+#             File.read(path) # => "bazbar"
+#             f.pos # => 3
+#
+#             f.pos = 3
+#             f.write('foo')
+#             f.flush
+#             File.read(path) # => "bazfoo"
+#             f.pos # => 6
+#
+#             f.seek(-3, :END)
+#             f.write('bam')
+#             f.flush
+#             File.read(path) # => "bazbam"
+#             f.pos # => 6
+#
+#             f.pos = 8
+#             f.write('bah')  # Zero padding as needed.
+#             f.flush
+#             File.read(path) # => "bazbam\u0000\u0000bah"
+#             f.pos # => 11
+#
+#     *   File may be read anywhere (even past end-of-file); see IO#rewind,
+#         IO#pos=, IO#seek:
+#
+#             f.rewind
+#             # => 0
+#             f.read
+#             # => "bazbam\u0000\u0000bah"
+#
+#             f.pos = 3
+#             # => 3
+#             f.read
+#             # => "bam\u0000\u0000bah"
+#
+#             f.seek(-3, :END)
+#             # => 0
+#             f.read
+#             # => "bah"
+#
+# *   `'a+'`:
+#
+#     *   File's initial write position is 0:
+#
+#             path = 't.tmp'
+#             FileUtils.rm_f(path)
+#             f = File.new(path, 'a+')
+#             f.pos # => 0
+#
+#     *   Writing occurs only at end-of-file:
+#
+#             f.write('foo')
+#             f.pos # => 3
+#             f.write('bar')
+#             f.pos # => 6
+#             f.flush
+#             File.read(path) # => "foobar"
+#
+#             f.rewind
+#             f.write('baz')
+#             f.flush
+#             File.read(path) # => "foobarbaz"
+#
+#     *   File may be read anywhere (even past end-of-file); see IO#rewind,
+#         IO#pos=, IO#seek:
+#
+#             f.rewind
+#             f.read # => "foobarbaz"
+#
+#             f.pos = 3
+#             f.read # => "barbaz"
+#
+#             f.seek(-3, :END)
+#             f.read # => "baz"
+#
+#             f.pos = 800
+#             f.read # => ""
+#
+# #### Data Mode
+#
+# 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.
+#
+# If neither is given, the stream defaults to text data.
+#
+# Examples:
+#
+#     File.new('t.txt', 'rt')
+#     File.new('t.dat', 'rb')
+#
+# When the data mode is specified, the read/write mode may not be omitted, and
+# the data mode must precede the file-create mode, if given:
+#
+#     File.new('t.dat', 'b')   # Raises an exception.
+#     File.new('t.dat', 'rxb') # Raises an exception.
+#
+# #### File-Create Mode
+#
+# 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.
+#
+# Example:
+#
+#     File.new('t.tmp', 'wx')
+#
+# When the file-create mode is specified, the read/write mode may not be
+# omitted, and the file-create mode must follow the data mode:
+#
+#     File.new('t.dat', 'x')   # Raises an exception.
+#     File.new('t.dat', 'rxb') # Raises an exception.
+#
+# ### 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 `|`:
+#
+# *   `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.
+#
+# Examples:
+#
+#     File.new('t.txt', File::RDONLY)
+#     File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
+#
+# Note: Method IO#set_encoding does not allow the mode to be specified as an
+# integer.
+#
+# ### File-Create Mode Specified as an Integer
+#
+# 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.
+#
+# ### 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.
 #
-#     ::truncate
-# :       Truncates the file at the given file path to the given size.
+# 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.
 #
-#     ::unlink (aliased as ::delete)
-# :       Deletes the file for each given file path.
+# ### Encodings
 #
-#     #truncate
-# :       Truncates `self` to the given size.
+# Any of the string modes above may specify encodings - either external encoding
+# only or both external and internal encodings - by appending one or both
+# encoding names, separated by colons:
+#
+#     f = File.new('t.dat', 'rb')
+#     f.external_encoding # => #<Encoding:ASCII-8BIT>
+#     f.internal_encoding # => nil
+#     f = File.new('t.dat', 'rb:UTF-16')
+#     f.external_encoding # => #<Encoding:UTF-16 (dummy)>
+#     f.internal_encoding # => nil
+#     f = File.new('t.dat', 'rb:UTF-16:UTF-16')
+#     f.external_encoding # => #<Encoding:UTF-16 (dummy)>
+#     f.internal_encoding # => #<Encoding:UTF-16>
+#     f.close
+#
+# The numerous encoding names are available in array Encoding.name_list:
+#
+#     Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]
+#
+# When the external encoding is set, strings read are tagged by that encoding
+# when reading, and strings written are converted to that encoding when writing.
+#
+# When both external and internal encodings are set, strings read are converted
+# from external to internal encoding, and strings written are converted from
+# 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.
+#
+# Note that the BOM-style encoding option is case insensitive, so `'bom|utf-8'`
+# is also valid.
+#
+# ## File Permissions
+#
+# A File object has *permissions*, an octal integer representing the permissions
+# of an actual file in the underlying platform.
+#
+# Note that file permissions are quite different from the *mode* of a file
+# stream (File object).
+#
+# In a File object, the permissions are available thus, where method `mode`,
+# despite its name, returns permissions:
+#
+#     f = File.new('t.txt')
+#     f.lstat.mode.to_s(8) # => "100644"
+#
+# On a Unix-based operating system, the three low-order octal digits represent
+# the permissions for owner (6), group (4), and world (4). The triplet of bits
+# in each octal digit represent, respectively, read, write, and execute
+# permissions.
+#
+# Permissions `0644` thus represent read-write access for owner and read-only
+# access for group and world. See man pages
+# [open(2)](https://www.unix.com/man-page/bsd/2/open) and
+# [chmod(2)](https://www.unix.com/man-page/bsd/2/chmod).
+#
+# For a directory, the meaning of the execute bit changes: when set, the
+# directory can be searched.
+#
+# Higher-order bits in permissions may indicate the type of file (plain,
+# directory, pipe, socket, etc.) and various other special features.
+#
+# On non-Posix operating systems, permissions may include only read-only or
+# read-write, in which case, the remaining permission will resemble typical
+# values. On Windows, for instance, the default permissions are `0644`; The only
+# change that can be made is to make the file read-only, which is reported as
+# `0444`.
+#
+# For a method that actually creates a file in the underlying platform (as
+# opposed to merely creating a File object), permissions may be specified:
+#
+#     File.new('t.tmp', File::CREAT, 0644)
+#     File.new('t.tmp', File::CREAT, 0444)
+#
+# Permissions may also be changed:
+#
+#     f = File.new('t.tmp', File::CREAT, 0444)
+#     f.chmod(0644)
+#     f.chmod(0444)
+#
+# ## File Constants
+#
+# 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`.
+#
+# ## What's Here
+#
+# First, what's elsewhere. Class File:
+#
+# *   Inherits from [class IO](rdoc-ref:IO@What-27s+Here), in particular,
+#     methods for creating, reading, and writing files
+# *   Includes module FileTest, which provides dozens of additional methods.
+#
+# Here, class File provides methods that are useful for:
+#
+# *   [Creating](rdoc-ref:File@Creating)
+# *   [Querying](rdoc-ref:File@Querying)
+# *   [Settings](rdoc-ref:File@Settings)
+# *   [Other](rdoc-ref:File@Other)
+#
+# ### Creating
+#
+# *   ::new: Opens the file at the given path; returns the file.
+# *   ::open: Same as ::new, but when given a block will yield the file to the
+#     block, and close the file upon exiting the block.
+# *   ::link: Creates a new name for an existing file using a hard link.
+# *   ::mkfifo: Returns the FIFO file created at the given path.
+# *   ::symlink: Creates a symbolic link for the given file path.
+#
+# ### Querying
+#
+# *Paths*
+#
+# *   ::absolute_path: Returns the absolute file path for the given path.
+# *   ::absolute_path?: Returns whether the given path is the absolute file
+#     path.
+# *   ::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.
+# *   ::extname: Returns the file extension for the given file path.
+# *   ::fnmatch? (aliased as ::fnmatch): Returns whether the given file path
+#     matches the given pattern.
+# *   ::join: Joins path components into a single path string.
+# *   ::path: Returns the string representation of the given path.
+# *   ::readlink: Returns the path to the file at the given symbolic link.
+# *   ::realdirpath: Returns the real path for the given file path, where the
+#     last component need not exist.
+# *   ::realpath: Returns the real path for the given file path, where all
+#     components must exist.
+# *   ::split: Returns an array of two strings: the directory name and basename
+#     of the file at the given path.
+# *   #path (aliased as #to_path):  Returns the string representation of the
+#     given path.
+#
+# *Times*
+#
+# *   ::atime: Returns a Time for the most recent access to the given file.
+# *   ::birthtime: Returns a Time  for the creation of the given file.
+# *   ::ctime: Returns a Time  for the metadata change of the given file.
+# *   ::mtime: Returns a Time for the most recent data modification to the
+#     content of the given file.
+# *   #atime: Returns a Time for the most recent access to `self`.
+# *   #birthtime: Returns a Time  the creation for `self`.
+# *   #ctime: Returns a Time for the metadata change of `self`.
+# *   #mtime: Returns a Time for the most recent data modification to the
+#     content of `self`.
+#
+# *Types*
+#
+# *   ::blockdev?: Returns whether the file at the given path is a block device.
+# *   ::chardev?: Returns whether the file at the given path is a character
+#     device.
+# *   ::directory?: Returns whether the file at the given path is a directory.
+# *   ::executable?: Returns whether the file at the given path is executable by
+#     the effective user and group of the current process.
+# *   ::executable_real?: Returns whether the file at the given path is
+#     executable by the real user and group of the current process.
+# *   ::exist?: Returns whether the file at the given path exists.
+# *   ::file?: Returns whether the file at the given path is a regular file.
+# *   ::ftype: Returns a string giving the type of the file at the given path.
+# *   ::grpowned?: Returns whether the effective group of the current process
+#     owns the file at the given path.
+# *   ::identical?: Returns whether the files at two given paths are identical.
+# *   ::lstat: Returns the File::Stat object for the last symbolic link in the
+#     given path.
+# *   ::owned?: Returns whether the effective user of the current process owns
+#     the file at the given path.
+# *   ::pipe?: Returns whether the file at the given path is a pipe.
+# *   ::readable?: Returns whether the file at the given path is readable by the
+#     effective user and group of the current process.
+# *   ::readable_real?: Returns whether the file at the given path is readable
+#     by the real user and group of the current process.
+# *   ::setgid?: Returns whether the setgid bit is set for the file at the given
+#     path.
+# *   ::setuid?: Returns whether the setuid bit is set for the file at the given
+#     path.
+# *   ::socket?: Returns whether the file at the given path is a socket.
+# *   ::stat: Returns the File::Stat object for the file at the given path.
+# *   ::sticky?: Returns whether the file at the given path has its sticky bit
+#     set.
+# *   ::symlink?: Returns whether the file at the given path is a symbolic link.
+# *   ::umask: Returns the umask value for the current process.
+# *   ::world_readable?: Returns whether the file at the given path is readable
+#     by others.
+# *   ::world_writable?: Returns whether the file at the given path is writable
+#     by others.
+# *   ::writable?: Returns whether the file at the given path is writable by the
+#     effective user and group of the current process.
+# *   ::writable_real?: Returns whether the file at the given path is writable
+#     by the real user and group of the current process.
+# *   #lstat: Returns the File::Stat object for the last symbolic link in the
+#     path for `self`.
+#
+# *Contents*
+#
+# *   ::empty? (aliased as ::zero?): Returns whether the file at the given path
+#     exists and is empty.
+# *   ::size: Returns the size (bytes) of the file at the given path.
+# *   ::size?: Returns `nil` if there is no file at the given path, or if that
+#     file is empty; otherwise returns the file size (bytes).
+# *   #size: Returns the size (bytes) of `self`.
+#
+# ### Settings
+#
+# *   ::chmod: Changes permissions of the file at the given path.
+# *   ::chown: Change ownership of the file at the given path.
+# *   ::lchmod: Changes permissions of the last symbolic link in the given path.
+# *   ::lchown: Change ownership of the last symbolic in the given path.
+# *   ::lutime: For each given file path, sets the access time and modification
+#     time of the last symbolic link in the path.
+# *   ::rename: Moves the file at one given path to another given path.
+# *   ::utime: Sets the access time and modification time of each file at the
+#     given paths.
+# *   #flock: Locks or unlocks `self`.
+#
+# ### Other
+#
+# *   ::truncate: Truncates the file at the given file path to the given size.
+# *   ::unlink (aliased as ::delete): Deletes the file for each given file path.
+# *   #truncate: Truncates `self` to the given size.
 #
 class File < IO
   # <!--
   #   rdoc-file=io.c
-  #   - File.new(filename, mode="r" [, opt])            -> file
-  #   - File.new(filename [, mode [, perm]] [, opt])    -> file
+  #   - File.new(path, mode = 'r', perm = 0666, **opts) -> file
   # -->
-  # Opens the file named by `filename` according to the given `mode` and returns a
-  # new File object.
+  # Opens the file at the given `path` according to the given `mode`; creates and
+  # returns a new File object for that file.
   #
-  # See IO.new for a description of `mode` and `opt`.
+  # The new File object is buffered mode (or non-sync mode), unless `filename` is
+  # a tty. See IO#flush, IO#fsync, IO#fdatasync, and IO#sync=.
   #
-  # If a file is being created, permission bits may be given in `perm`.  These
-  # mode and permission bits are platform dependent; on Unix systems, see open(2)
-  # and chmod(2) man pages for details.
+  # Argument `path` must be a valid file path:
   #
-  # The new File object is buffered mode (or non-sync mode), unless `filename` is
-  # a tty. See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= about sync mode.
+  #     f = File.new('/etc/fstab')
+  #     f.close
+  #     f = File.new('t.txt')
+  #     f.close
+  #
+  # Optional argument `mode` (defaults to 'r') must specify a valid mode; see
+  # [Access Modes](rdoc-ref:File@Access+Modes):
+  #
+  #     f = File.new('t.tmp', 'w')
+  #     f.close
+  #     f = File.new('t.tmp', File::RDONLY)
+  #     f.close
   #
-  # ### Examples
+  # Optional argument `perm` (defaults to 0666) must specify valid permissions see
+  # [File Permissions](rdoc-ref:File@File+Permissions):
   #
-  #     f = File.new("testfile", "r")
-  #     f = File.new("newfile",  "w+")
-  #     f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)
+  #     f = File.new('t.tmp', File::CREAT, 0644)
+  #     f.close
+  #     f = File.new('t.tmp', File::CREAT, 0444)
+  #     f.close
   #
-  def initialize: (string | _ToPath | int file_name, ?string | int mode, ?int perm) -> File
+  # Optional keyword arguments `opts` specify:
+  #
+  # *   [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
 
   # <!--
   #   rdoc-file=file.c
@@ -380,28 +903,37 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - birthtime(p1)
+  #   - File.birthtime(file_name)  -> time
   # -->
+  # Returns the birth time for the named file.
+  #
+  # *file_name* can be an IO object.
+  #
+  #     File.birthtime("testfile")   #=> Wed Apr 09 08:53:13 CDT 2003
+  #
+  # If the platform doesn't have birthtime, raises NotImplementedError.
   #
   def self.birthtime: (string | _ToPath | IO file_name) -> Time
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.blockdev?(file_name)   ->  true or false
+  #   - File.blockdev?(filepath) -> true or false
   # -->
-  # Returns `true` if the named file is a block device.
+  # Returns `true` if `filepath` points to a block device, `false` otherwise:
   #
-  # *file_name* can be an IO object.
+  #     File.blockdev?('/dev/sda1')       # => true
+  #     File.blockdev?(File.new('t.tmp')) # => false
   #
   def self.blockdev?: (string | _ToPath | IO file_name) -> bool
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.chardev?(file_name)   ->  true or false
+  #   - File.chardev?(filepath) -> true or false
   # -->
-  # Returns `true` if the named file is a character device.
+  # Returns `true` if `filepath` points to a character device, `false` otherwise.
   #
-  # *file_name* can be an IO object.
+  #     File.chardev?($stdin)     # => true
+  #     File.chardev?('t.txt')     # => false
   #
   def self.chardev?: (string | _ToPath | IO file_name) -> bool
 
@@ -464,14 +996,19 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.directory?(file_name)   ->  true or false
+  #   - File.directory?(path) -> true or false
   # -->
-  # Returns `true` if the named file is a directory, or a symlink that points at a
-  # directory, and `false` otherwise.
+  # With string `object` given, returns `true` if `path` is a string path leading
+  # to a directory, or to a symbolic link to a directory; `false` otherwise:
   #
-  # *file_name* can be an IO object.
+  #     File.directory?('.')              # => true
+  #     File.directory?('foo')            # => false
+  #     File.symlink('.', 'dirlink')      # => 0
+  #     File.directory?('dirlink')        # => true
+  #     File.symlink('t,txt', 'filelink') # => 0
+  #     File.directory?('filelink')       # => false
   #
-  #     File.directory?(".")
+  # Argument `path` can be an IO object.
   #
   def self.directory?: (string | _ToPath | IO path) -> bool
 
@@ -628,10 +1165,13 @@ class File < IO
   #
   #     `*`
   # :       Matches all regular files
+  #
   #     `c*`
   # :       Matches all files beginning with `c`
+  #
   #     `*c`
   # :       Matches all files ending with `c`
+  #
   #     `*c*`
   # :       Matches all files that have `c` in them (including at the beginning or
   #         end).
@@ -640,19 +1180,24 @@ class File < IO
   #     To match hidden files (that start with a `.`) set the File::FNM_DOTMATCH
   #     flag.
   #
+  #
   # `**`
   # :   Matches directories recursively or files expansively.
   #
+  #
   # `?`
   # :   Matches any one character. Equivalent to `/.{1}/` in regexp.
   #
+  #
   # `[set]`
   # :   Matches any one character in `set`.  Behaves exactly like character sets
   #     in Regexp, including set negation (`[^a-z]`).
   #
+  #
   # `\`
   # :   Escapes the next metacharacter.
   #
+  #
   # `{a,b}`
   # :   Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled.
   #     Behaves like a Regexp union (`(?:a|b)`).
@@ -769,7 +1314,7 @@ class File < IO
   #
   #     File.join("usr", "mail", "gumby")   #=> "usr/mail/gumby"
   #
-  def self.join: (*string) -> String
+  def self.join: (*path) -> String
 
   # <!--
   #   rdoc-file=file.c
@@ -806,15 +1351,14 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.lstat(file_name)   -> stat
+  #   - File.lstat(filepath) -> stat
   # -->
-  # Same as File::stat, but does not follow the last symbolic link. Instead,
-  # reports on the link itself.
+  # Like File::stat, but does not follow the last symbolic link; instead, returns
+  # a File::Stat object for the link itself.
   #
-  #     File.symlink("testfile", "link2test")   #=> 0
-  #     File.stat("testfile").size              #=> 66
-  #     File.lstat("link2test").size            #=> 8
-  #     File.stat("link2test").size             #=> 66
+  #     File.symlink('t.txt', 'symlink')
+  #     File.stat('symlink').size  # => 47
+  #     File.lstat('symlink').size # => 5
   #
   def self.lstat: (string | _ToPath file_name) -> File::Stat
 
@@ -853,20 +1397,15 @@ class File < IO
 
   # <!--
   #   rdoc-file=io.c
-  #   - File.open(filename, mode="r" [, opt])                 -> file
-  #   - File.open(filename [, mode [, perm]] [, opt])         -> file
-  #   - File.open(filename, mode="r" [, opt]) {|file| block } -> obj
-  #   - File.open(filename [, mode [, perm]] [, opt]) {|file| block } -> obj
+  #   - File.open(path, mode = 'r', perm = 0666, **opts) -> file
+  #   - File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object
   # -->
-  # With no associated block, File.open is a synonym for File.new. If the optional
-  # code block is given, it will be passed the opened `file` as an argument and
-  # the File object will automatically be closed when the block terminates.  The
-  # value of the block will be returned from File.open.
+  # Creates a new File object, via File.new with the given arguments.
   #
-  # If a file is being created, its initial permissions may be set using the
-  # `perm` parameter.  See File.new for further discussion.
+  # With no block given, returns the File object.
   #
-  # See IO.new for a description of the `mode` and `opt` parameters.
+  # 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
@@ -888,18 +1427,20 @@ class File < IO
   # -->
   # Returns the string representation of the path
   #
-  #     File.path("/dev/null")          #=> "/dev/null"
+  #     File.path(File::NULL)           #=> "/dev/null"
   #     File.path(Pathname.new("/tmp")) #=> "/tmp"
   #
   def self.path: (string | _ToPath path) -> String
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.pipe?(file_name)   ->  true or false
+  #   - File.pipe?(filepath) -> true or false
   # -->
-  # Returns `true` if the named file is a pipe.
+  # Returns `true` if `filepath` points to a pipe, `false` otherwise:
   #
-  # *file_name* can be an IO object.
+  #     File.mkfifo('tmp/fifo')
+  #     File.pipe?('tmp/fifo') # => true
+  #     File.pipe?('t.txt')    # => false
   #
   def self.pipe?: (string | _ToPath | IO file_name) -> bool
 
@@ -1021,11 +1562,13 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.socket?(file_name)   ->  true or false
+  #   - File.socket?(filepath)   ->  true or false
   # -->
-  # Returns `true` if the named file is a socket.
+  # Returns `true` if `filepath` points to a socket, `false` otherwise:
   #
-  # *file_name* can be an IO object.
+  #     require 'socket'
+  #     File.socket?(Socket.new(:INET, :STREAM)) # => true
+  #     File.socket?(File.new('t.txt'))          # => false
   #
   def self.socket?: (string | _ToPath | IO file_name) -> bool
 
@@ -1042,11 +1585,11 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.stat(file_name)   ->  stat
+  #   - File.stat(filepath) ->  stat
   # -->
-  # Returns a File::Stat object for the named file (see File::Stat).
+  # Returns a File::Stat object for the file at `filepath` (see File::Stat):
   #
-  #     File.stat("testfile").mtime   #=> Tue Apr 08 12:58:04 CDT 2003
+  #     File.stat('t.txt').class # => File::Stat
   #
   def self.stat: (string | _ToPath file_name) -> File::Stat
 
@@ -1074,9 +1617,13 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.symlink?(file_name)   ->  true or false
+  #   - File.symlink?(filepath) -> true or false
   # -->
-  # Returns `true` if the named file is a symbolic link.
+  # Returns `true` if `filepath` points to a symbolic link, `false` otherwise:
+  #
+  #     symlink = File.symlink('t.txt', 'symlink')
+  #     File.symlink?('symlink') # => true
+  #     File.symlink?('t.txt')   # => false
   #
   def self.symlink?: (string | _ToPath file_name) -> bool
 
@@ -1202,8 +1749,6 @@ class File < IO
   #
   def self.zero?: (string | _ToPath | IO file_name) -> bool
 
-  public
-
   # <!--
   #   rdoc-file=file.c
   #   - file.atime    -> time
@@ -1269,58 +1814,51 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - file.flock(locking_constant) -> 0 or false
+  #   - flock(locking_constant) -> 0 or false
   # -->
-  # Locks or unlocks a file according to *locking_constant* (a logical *or* of the
-  # values in the table below). Returns `false` if File::LOCK_NB is specified and
-  # the operation would otherwise have blocked. Not available on all platforms.
-  #
-  # Locking constants (in class File):
-  #
-  #     LOCK_EX   | Exclusive lock. Only one process may hold an
-  #               | exclusive lock for a given file at a time.
-  #     ----------+------------------------------------------------
-  #     LOCK_NB   | Don't block when locking. May be combined
-  #               | with other lock options using logical or.
-  #     ----------+------------------------------------------------
-  #     LOCK_SH   | Shared lock. Multiple processes may each hold a
-  #               | shared lock for a given file at the same time.
-  #     ----------+------------------------------------------------
-  #     LOCK_UN   | Unlock.
-  #
+  # 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;
+  # 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.
   # Example:
-  #
-  #     # update a counter using write lock
-  #     # don't use "w" because it truncates the file before lock.
-  #     File.open("counter", File::RDWR|File::CREAT, 0644) {|f|
-  #       f.flock(File::LOCK_EX)
-  #       value = f.read.to_i + 1
-  #       f.rewind
-  #       f.write("#{value}\n")
-  #       f.flush
-  #       f.truncate(f.pos)
-  #     }
-  #
-  #     # read the counter using read lock
-  #     File.open("counter", "r") {|f|
-  #       f.flock(File::LOCK_SH)
-  #       p f.read
-  #     }
+  #     # Update a counter using an exclusive lock.
+  # # Don't use File::WRONLY because it truncates the file.
+  # File.open('counter', File::RDWR | File::CREAT, 0644) do |f|
+  #   f.flock(File::LOCK_EX)
+  #   value = f.read.to_i + 1
+  #   f.rewind
+  #   f.write("#{value}\n")
+  #   f.flush
+  #   f.truncate(f.pos)
+  # end
+  #
+  # # Read the counter using a shared lock.
+  # File.open('counter', 'r') do |f|
+  #   f.flock(File::LOCK_SH)
+  #   f.read
+  # end
   #
   def flock: (int locking_constant) -> (0 | false)
 
   # <!--
   #   rdoc-file=file.c
-  #   - file.lstat   ->  stat
+  #   - lstat -> stat
   # -->
-  # Same as IO#stat, but does not follow the last symbolic link. Instead, reports
-  # on the link itself.
+  # Like File#stat, but does not follow the last symbolic link; instead, returns a
+  # File::Stat object for the link itself:
   #
-  #     File.symlink("testfile", "link2test")   #=> 0
-  #     File.stat("testfile").size              #=> 66
-  #     f = File.new("link2test")
-  #     f.lstat.size                            #=> 8
-  #     f.stat.size                             #=> 66
+  #     File.symlink('t.txt', 'symlink')
+  #     f = File.new('symlink')
+  #     f.stat.size  # => 47
+  #     f.lstat.size # => 11
   #
   def lstat: () -> (File::Stat | nil)
 
@@ -1355,8 +1893,11 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - size()
+  #   - file.size    -> integer
   # -->
+  # Returns the size of *file* in bytes.
+  #
+  #     File.new("testfile").size   #=> 66
   #
   def size: () -> Integer
 
@@ -1411,67 +1952,468 @@ File::SEPARATOR: String
 #
 File::Separator: String
 
+# <!-- rdoc-file=file.c -->
+# Module `File::Constants` defines file-related constants.
+#
+# There are two families of constants here:
+#
+# *   Those having to do with [file
+#     access](rdoc-ref:File::Constants@File+Access).
+# *   Those having to do with [filename
+#     globbing](rdoc-ref:File::Constants@Filename+Globbing+Constants+-28File-3A-
+#     3AFNM_-2A-29).
+#
+# File constants defined for the local process may be retrieved with method
+# File::Constants.constants:
+#
+#     File::Constants.constants.take(5)
+#     # => [:RDONLY, :WRONLY, :RDWR, :APPEND, :CREAT]
+#
+# ## File Access
+#
+# File-access constants may be used with optional argument `mode` in calls to
+# the following methods:
+#
+# *   File.new.
+# *   File.open.
+# *   IO.for_fd.
+# *   IO.new.
+# *   IO.open.
+# *   IO.popen.
+# *   IO.reopen.
+# *   IO.sysopen.
+# *   StringIO.new.
+# *   StringIO.open.
+# *   StringIO#reopen.
+#
+# ### Read/Write Access
+#
+# Read-write access for a stream may be specified by a file-access constant.
+#
+# The constant may be specified as part of a bitwise OR of other such constants.
+#
+# Any combination of the constants in this section may be specified.
+#
+# #### File::RDONLY
+#
+# Flag File::RDONLY specifies the stream should be opened for reading only:
+#
+#     filepath = '/tmp/t.tmp'
+#     f = File.new(filepath, File::RDONLY)
+#     f.write('Foo') # Raises IOError (not opened for writing).
+#
+# #### File::WRONLY
+#
+# Flag File::WRONLY specifies that the stream should be opened for writing only:
+#
+#     f = File.new(filepath, File::WRONLY)
+#     f.read # Raises IOError (not opened for reading).
+#
+# #### File::RDWR
+#
+# Flag File::RDWR specifies that the stream should be opened for both reading
+# and writing:
+#
+#     f = File.new(filepath, File::RDWR)
+#     f.write('Foo') # => 3
+#     f.rewind       # => 0
+#     f.read         # => "Foo"
+#
+# ### File Positioning
+#
+# #### File::APPEND
+#
+# Flag File::APPEND specifies that the stream should be opened in append mode.
+#
+# Before each write operation, the position is set to end-of-stream. The
+# modification of the position and the following write operation are performed
+# as a single atomic step.
+#
+# #### File::TRUNC
+#
+# Flag File::TRUNC specifies that the stream should be truncated at its
+# beginning. If the file exists and is successfully opened for writing, it is to
+# be truncated to position zero; its ctime and mtime are updated.
+#
+# There is no effect on a FIFO special file or a terminal device. The effect on
+# other file types is implementation-defined. The result of using File::TRUNC
+# with File::RDONLY is undefined.
+#
+# ### Creating and Preserving
+#
+# #### File::CREAT
+#
+# Flag File::CREAT specifies that the stream should be created if it does not
+# already exist.
+#
+# If the file exists:
+#
+#     - Raise an exception if File::EXCL is also specified.
+#     - Otherwise, do nothing.
+#
+# If the file does not exist, then it is created. Upon successful completion,
+# the atime, ctime, and mtime of the file are updated, and the ctime and mtime
+# of the parent directory are updated.
+#
+# #### File::EXCL
+#
+# Flag File::EXCL specifies that the stream should not already exist; If flags
+# File::CREAT and File::EXCL are both specified and the stream already exists,
+# an exception is raised.
+#
+# The check for the existence and creation of the file is performed as an atomic
+# operation.
+#
+# If both File::EXCL and File::CREAT are specified and the path names a symbolic
+# link, an exception is raised regardless of the contents of the symbolic link.
+#
+# If File::EXCL is specified and File::CREAT is not specified, the result is
+# undefined.
+#
+# ### POSIX File Constants
+#
+# Some file-access constants are defined only on POSIX-compliant systems; those
+# are:
+#
+# *   File::SYNC.
+# *   File::DSYNC.
+# *   File::RSYNC.
+# *   File::DIRECT.
+# *   File::NOATIME.
+# *   File::NOCTTY.
+# *   File::NOFOLLOW.
+# *   File::TMPFILE.
+#
+# #### File::SYNC, File::RSYNC, and File::DSYNC
+#
+# Flag File::SYNC, File::RSYNC, or File::DSYNC specifies synchronization of I/O
+# operations with the underlying file system.
+#
+# These flags are valid only for POSIX-compliant systems.
+#
+# *   File::SYNC specifies that all write operations (both data and metadata)
+#     are immediately to be flushed to the underlying storage device. This means
+#     that the data is written to the storage device, and the file's metadata
+#     (e.g., file size, timestamps, permissions) are also synchronized. This
+#     guarantees that data is safely stored on the storage medium before
+#     returning control to the calling program. This flag can have a significant
+#     impact on performance since it requires synchronous writes, which can be
+#     slower compared to asynchronous writes.
+#
+# *   File::RSYNC specifies that any read operations on the file will not return
+#     until all outstanding write operations (those that have been issued but
+#     not completed) are also synchronized. This is useful when you want to read
+#     the most up-to-date data, which may still be in the process of being
+#     written.
+#
+# *   File::DSYNC specifies that all *data* write operations are immediately to
+#     be flushed to the underlying storage device; this differs from File::SYNC,
+#     which requires that *metadata* also be synchronized.
+#
+# Note that the behavior of these flags may vary slightly depending on the
+# operating system and filesystem being used. Additionally, using these flags
+# can have an impact on performance due to the synchronous nature of the I/O
+# operations, so they should be used judiciously, especially in
+# performance-critical applications.
+#
+# #### File::NOCTTY
+#
+# Flag File::NOCTTY specifies that if the stream is a terminal device, that
+# device does not become the controlling terminal for the process.
+#
+# Defined only for POSIX-compliant systems.
+#
+# #### File::DIRECT
+#
+# Flag File::DIRECT requests that cache effects of the I/O to and from the
+# stream be minimized.
+#
+# Defined only for POSIX-compliant systems.
+#
+# #### File::NOATIME
+#
+# Flag File::NOATIME specifies that act of opening the stream should not modify
+# its access time (atime).
+#
+# Defined only for POSIX-compliant systems.
+#
+# #### File::NOFOLLOW
+#
+# Flag File::NOFOLLOW specifies that if path is a symbolic link, it should not
+# be followed.
+#
+# Defined only for POSIX-compliant systems.
+#
+# #### File::TMPFILE
+#
+# Flag File::TMPFILE specifies that the opened stream should be a new temporary
+# file.
+#
+# Defined only for POSIX-compliant systems.
+#
+# ### Other File-Access Constants
+#
+# #### File::NONBLOCK
+#
+# When possible, the file is opened in nonblocking mode. Neither the open
+# operation nor any subsequent I/O operations on the file will cause the calling
+# process to wait.
+#
+# #### File::BINARY
+#
+# Flag File::BINARY specifies that the stream is to be accessed in binary mode.
+#
+# #### File::SHARE_DELETE
+#
+# Flag File::SHARE_DELETE enables other processes to open the stream with delete
+# access.
+#
+# Windows only.
+#
+# If the stream is opened for (local) delete access without File::SHARE_DELETE,
+# and another process attempts to open it with delete access, the attempt fails
+# and the stream is not opened for that process.
+#
+# ## Locking
+#
+# Four file constants relate to stream locking; see File#flock:
+#
+# #### File::LOCK_EX
+#
+# Flag File::LOCK_EX specifies an exclusive lock; only one process a a time may
+# lock the stream.
+#
+# #### File::LOCK_NB
+#
+# Flag File::LOCK_NB specifies non-blocking locking for the stream; may be
+# combined with File::LOCK_EX or File::LOCK_SH.
+#
+# #### File::LOCK_SH
+#
+# Flag File::LOCK_SH specifies that multiple processes may lock the stream at
+# the same time.
+#
+# #### File::LOCK_UN
+#
+# Flag File::LOCK_UN specifies that the stream is not to be locked.
+#
+# ## Filename Globbing Constants (File::FNM_*)
+#
+# Filename-globbing constants may be used with optional argument `flags` in
+# calls to the following methods:
+#
+# *   Dir.glob.
+# *   File.fnmatch.
+# *   Pathname#fnmatch.
+# *   Pathname.glob.
+# *   Pathname#glob.
+#
+# The constants are:
+#
+# #### File::FNM_CASEFOLD
+#
+# Flag File::FNM_CASEFOLD makes patterns case insensitive for File.fnmatch (but
+# not Dir.glob).
+#
+# #### File::FNM_DOTMATCH
+#
+# Flag File::FNM_DOTMATCH makes the `'*'` pattern match a filename starting with
+# `'.'`.
+#
+# #### 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*)'`):
+#
+#     pattern = '{LEGAL,BSDL}'
+#     Dir.glob(pattern)      # => ["LEGAL", "BSDL"]
+#     Pathname.glob(pattern) # => [#<Pathname:LEGAL>, #<Pathname:BSDL>]
+#     pathname.glob(pattern) # => [#<Pathname:LEGAL>, #<Pathname:BSDL>]
+#
+# #### File::FNM_NOESCAPE
+#
+# Flag File::FNM_NOESCAPE disables `'\'` escaping.
+#
+# #### File::FNM_PATHNAME
+#
+# Flag File::FNM_PATHNAME specifies that patterns `'*'` and `'?'` do not match
+# the directory separator (the value of constant File::SEPARATOR).
+#
+# #### File::FNM_SHORTNAME
+#
+# Flag File::FNM_SHORTNAME allows patterns to match short names if they exist.
+#
+# Windows only.
+#
+# #### File::FNM_SYSCASE
+#
+# Flag File::FNM_SYSCASE specifies that case sensitivity is the same as in the
+# underlying operating system; effective for File.fnmatch, but not Dir.glob.
+#
+# ## Other Constants
+#
+# #### File::NULL
+#
+# Flag File::NULL contains the string value of the null device:
+#
+# *   On a Unix-like OS, `'/dev/null'`.
+# *   On Windows, `'NUL'`.
+#
 module File::Constants
 end
 
+# <!-- rdoc-file=file.c -->
+# [File::APPEND](rdoc-ref:File::Constants@File-3A-3AAPPEND)
+#
 File::Constants::APPEND: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::BINARY](rdoc-ref:File::Constants@File-3A-3ABINARY)
+#
 File::Constants::BINARY: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::CREAT](rdoc-ref:File::Constants@File-3A-3ACREAT)
+#
 File::Constants::CREAT: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::DIRECT](rdoc-ref:File::Constants@File-3A-3ADIRECT)
+#
 File::Constants::DIRECT: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::DSYNC](rdoc-ref:File::Constants@File-3A-3ASYNC-2C+File-3A-3ARSYNC-2C+an
+# d+File-3A-3ADSYNC)
+#
 File::Constants::DSYNC: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::EXCL](rdoc-ref:File::Constants@File-3A-3AEXCL)
+#
 File::Constants::EXCL: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_CASEFOLD](rdoc-ref:File::Constants@File-3A-3AFNM_CASEFOLD)
+#
 File::Constants::FNM_CASEFOLD: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_DOTMATCH](rdoc-ref:File::Constants@File-3A-3AFNM_DOTMATCH)
+#
 File::Constants::FNM_DOTMATCH: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_EXTGLOB](rdoc-ref:File::Constants@File-3A-3AFNM_EXTGLOB)
+#
 File::Constants::FNM_EXTGLOB: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_NOESCAPE](rdoc-ref:File::Constants@File-3A-3AFNM_NOESCAPE)
+#
 File::Constants::FNM_NOESCAPE: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_PATHNAME](rdoc-ref:File::Constants@File-3A-3AFNM_PATHNAME)
+#
 File::Constants::FNM_PATHNAME: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_SHORTNAME](rdoc-ref:File::Constants@File-3A-3AFNM_SHORTNAME)
+#
 File::Constants::FNM_SHORTNAME: Integer
 
+# <!-- rdoc-file=dir.c -->
+# [File::FNM_SYSCASE](rdoc-ref:File::Constants@File-3A-3AFNM_SYSCASE)
+#
 File::Constants::FNM_SYSCASE: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::LOCK_EX](rdoc-ref:File::Constants@File-3A-3ALOCK_EX)
+#
 File::Constants::LOCK_EX: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::LOCK_NB](rdoc-ref:File::Constants@File-3A-3ALOCK_NB)
+#
 File::Constants::LOCK_NB: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::LOCK_SH](rdoc-ref:File::Constants@File-3A-3ALOCK_SH)
+#
 File::Constants::LOCK_SH: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::LOCK_UN](rdoc-ref:File::Constants@File-3A-3ALOCK_UN)
+#
 File::Constants::LOCK_UN: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::NOATIME](rdoc-ref:File::Constants@File-3A-3ANOATIME)
+#
 File::Constants::NOATIME: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::NOCTTY](rdoc-ref:File::Constants@File-3A-3ANOCTTY)
+#
 File::Constants::NOCTTY: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::NOFOLLOW](rdoc-ref:File::Constants@File-3A-3ANOFOLLOW)
+#
 File::Constants::NOFOLLOW: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::NONBLOCK](rdoc-ref:File::Constants@File-3A-3ANONBLOCK)
+#
 File::Constants::NONBLOCK: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::NULL](rdoc-ref:File::Constants@File-3A-3ANULL)
+#
 File::Constants::NULL: String
 
+# <!-- rdoc-file=file.c -->
+# [File::RDONLY](rdoc-ref:File::Constants@File-3A-3ARDONLY)
+#
 File::Constants::RDONLY: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::RDWR](rdoc-ref:File::Constants@File-3A-3ARDWR)
+#
 File::Constants::RDWR: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::RSYNC](rdoc-ref:File::Constants@File-3A-3ASYNC-2C+File-3A-3ARSYNC-2C+an
+# d+File-3A-3ADSYNC)
+#
 File::Constants::RSYNC: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::SHARE_DELETE](rdoc-ref:File::Constants@File-3A-3ASHARE_DELETE)
+#
 File::Constants::SHARE_DELETE: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::SYNC](rdoc-ref:File::Constants@File-3A-3ASYNC-2C+File-3A-3ARSYNC-2C+and
+# +File-3A-3ADSYNC)
+#
 File::Constants::SYNC: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::TMPFILE](rdoc-ref:File::Constants@File-3A-3ATMPFILE)
+#
 File::Constants::TMPFILE: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::TRUNC](rdoc-ref:File::Constants@File-3A-3ATRUNC)
+#
 File::Constants::TRUNC: Integer
 
+# <!-- rdoc-file=file.c -->
+# [File::WRONLY](rdoc-ref:File::Constants@File-3A-3AWRONLY)
+#
 File::Constants::WRONLY: Integer
 
 # <!-- rdoc-file=file.c -->
@@ -1487,8 +2429,10 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - File::Stat.new(file_name)  -> stat
+  #   - new(p1)
   # -->
+  # 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).
   #
@@ -1522,7 +2466,7 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - stat.birthtime  ->  aTime
+  #   - stat.birthtime  ->  time
   # -->
   # Returns the birth time for *stat*.
   #
@@ -1589,7 +2533,7 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - stat.ctime  ->  aTime
+  #   - stat.ctime  ->  time
   # -->
   # Returns the change time for *stat* (that is, the time directory information
   # about the file was changed, not the file itself).
@@ -1634,14 +2578,12 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.directory?(file_name)   ->  true or false
+  #   - stat.directory?   -> true or false
   # -->
-  # Returns `true` if the named file is a directory, or a symlink that points at a
-  # directory, and `false` otherwise.
-  #
-  # *file_name* can be an IO object.
+  # Returns `true` if *stat* is a directory, `false` otherwise.
   #
-  #     File.directory?(".")
+  #     File.stat("testfile").directory?   #=> false
+  #     File.stat(".").directory?          #=> true
   #
   def directory?: () -> bool
 
@@ -1703,7 +2645,7 @@ class File::Stat < Object
   #   - stat.grpowned?   -> true or false
   # -->
   # Returns true if the effective group id of the process is the same as the group
-  # id of *stat*. On Windows NT, returns `false`.
+  # id of *stat*. On Windows, returns `false`.
   #
   #     File.stat("testfile").grpowned?      #=> true
   #     File.stat("/etc/passwd").grpowned?   #=> false
@@ -1751,7 +2693,7 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - stat.mtime  ->  aTime
+  #   - stat.mtime  ->  time
   # -->
   # Returns the modification time of *stat*.
   #
@@ -1885,7 +2827,7 @@ class File::Stat < Object
   # Returns `nil` if *stat* is a zero-length file, the size of the file otherwise.
   #
   #     File.stat("testfile").size?   #=> 66
-  #     File.stat("/dev/null").size?  #=> nil
+  #     File.stat(File::NULL).size?   #=> nil
   #
   def size?: () -> Integer?