rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/core/io.rbs

@@ -1,230 +1,94 @@
 # <!-- rdoc-file=io.c -->
-# The IO class is the basis for all input and output in Ruby. An I/O stream may
-# be *duplexed* (that is, bidirectional), and so may use more than one native
-# operating system stream.
+# An instance of class IO (commonly called a *stream*) represents an
+# input/output stream in the underlying operating system. Class IO is the basis
+# for input and output in Ruby.
 #
-# Many of the examples in this section use the File class, the only standard
-# subclass of IO. The two classes are closely associated.  Like the File class,
-# the Socket library subclasses from IO (such as TCPSocket or UDPSocket).
-#
-# The Kernel#open method can create an IO (or File) object for these types of
-# arguments:
-#
-# *   A plain string represents a filename suitable for the underlying operating
-#     system.
-#
-# *   A string starting with `"|"` indicates a subprocess. The remainder of the
-#     string following the `"|"` is invoked as a process with appropriate
-#     input/output channels connected to it.
-#
-# *   A string equal to `"|-"` will create another Ruby instance as a
-#     subprocess.
-#
-#
-# The IO may be opened with different file modes (read-only, write-only) and
-# encodings for proper conversion.  See IO.new for these options.  See
-# Kernel#open for details of the various command formats described above.
-#
-# IO.popen, the Open3 library, or  Process#spawn may also be used to communicate
-# with subprocesses through an IO.
-#
-# Ruby will convert pathnames between different operating system conventions if
-# possible.  For instance, on a Windows system the filename
-# `"/gumby/ruby/test.rb"` will be opened as `"\gumby\ruby\test.rb"`.  When
-# specifying a Windows-style filename in a Ruby string, remember to escape the
-# backslashes:
-#
-#     "C:\\gumby\\ruby\\test.rb"
-#
-# Our examples here will use the Unix-style forward slashes; File::ALT_SEPARATOR
-# can be used to get the platform-specific separator character.
+# Class File is the only class in the Ruby core that is a subclass of IO. Some
+# classes in the Ruby standard library are also subclasses of IO; these include
+# TCPSocket and UDPSocket.
 #
 # The global constant ARGF (also accessible as `$<`) provides an IO-like stream
-# which allows access to all files mentioned on the command line (or STDIN if no
-# files are mentioned). ARGF#path and its alias ARGF#filename are provided to
-# access the name of the file currently being read.
-#
-# ## io/console
-#
-# The io/console extension provides methods for interacting with the console.
-# The console can be accessed from IO.console or the standard input/output/error
-# IO objects.
-#
-# Requiring io/console adds the following methods:
-#
-# *   IO::console
-# *   IO#raw
-# *   IO#raw!
-# *   IO#cooked
-# *   IO#cooked!
-# *   IO#getch
-# *   IO#echo=
-# *   IO#echo?
-# *   IO#noecho
-# *   IO#winsize
-# *   IO#winsize=
-# *   IO#iflush
-# *   IO#ioflush
-# *   IO#oflush
-#
-#
-# Example:
-#
-#     require 'io/console'
-#     rows, columns = $stdout.winsize
-#     puts "Your screen is #{columns} wide and #{rows} tall"
-#
-# ## Example Files
-#
-# Many examples here use these filenames and their corresponding files:
-#
-# *   `t.txt`: A text-only file that is assumed to exist via:
-#
-#         text = <<~EOT
-#           This is line one.
-#           This is the second line.
-#           This is the third line.
-#         EOT
-#         File.write('t.txt', text)
-#
-# *   `t.dat`: A data file that is assumed to exist via:
-#
-#         data = "\u9990\u9991\u9992\u9993\u9994"
-#         f = File.open('t.dat', 'wb:UTF-16')
-#         f.write(data)
-#         f.close
+# that allows access to all file paths found in ARGV (or found in STDIN if ARGV
+# is empty). ARGF is not itself a subclass of IO.
 #
-# *   `t.rus`: A Russian-language text file that is assumed to exist via:
+# Class StringIO provides an IO-like stream that handles a String. StringIO is
+# not itself a subclass of IO.
 #
-#         File.write('t.rus', "\u{442 435 441 442}")
+# Important objects based on IO include:
 #
-# *   `t.tmp`: A file that is assumed *not* to exist.
+# *   $stdin.
+# *   $stdout.
+# *   $stderr.
+# *   Instances of class File.
 #
 #
-# ## Modes
+# An instance of IO may be created using:
 #
-# A number of IO method calls must or may specify a *mode* for the stream; the
-# mode determines how stream is to be accessible, including:
+# *   IO.new: returns a new IO object for the given integer file descriptor.
+# *   IO.open: passes a new IO object to the given block.
+# *   IO.popen: returns a new IO object that is connected to the $stdin and
+#     $stdout of a newly-launched subprocess.
+# *   Kernel#open: Returns a new IO object connected to a given source: stream,
+#     file, or subprocess.
 #
-# *   Whether the stream is to be read-only, write-only, or read-write.
-# *   Whether the stream is positioned at its beginning or its end.
-# *   Whether the stream treats data as text-only or binary.
-# *   The external and internal encodings.
 #
+# Like a File stream, an IO stream has:
 #
-# ### Mode Specified as an Integer
+# *   A read/write mode, which may be read-only, write-only, or read/write; see
+#     [Read/Write Mode](rdoc-ref:File@Read-2FWrite+Mode).
+# *   A data mode, which may be text-only or binary; see [Data
+#     Mode](rdoc-ref:File@Data+Mode).
+# *   Internal and external encodings; see [Encodings](rdoc-ref:File@Encodings).
 #
-# When `mode` is an integer it must be one or more (combined by bitwise OR (`|`)
-# of the modes defined in File::Constants:
 #
-# *   `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.
-# *   `File::CREAT`: Create file if it does not exist.
-# *   `File::EXCL`: Raise an exception if `File::CREAT` is given and the file
-#     exists.
+# And like other IO streams, it has:
 #
+# *   A position, which determines where in the stream the next read or write is
+#     to occur; see [Position](rdoc-ref:IO@Position).
+# *   A line number, which is a special, line-oriented, "position" (different
+#     from the position mentioned above); see [Line
+#     Number](rdoc-ref:IO@Line+Number).
 #
-# Examples:
 #
-#     File.new('t.txt', File::RDONLY)
-#     File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
+# ## Extension `io/console`
 #
-# Note: Method IO#set_encoding does not allow the mode to be specified as an
-# integer.
+# Extension `io/console` provides numerous methods for interacting with the
+# console; requiring it adds numerous methods to class IO.
 #
-# ### Mode Specified As a String
-#
-# When `mode` is a string it must begin with one of the following:
-#
-# *   `'r'`: Read-only stream, positioned at the beginning; the stream cannot be
-#     changed to writable.
-# *   `'w'`: Write-only stream, positioned at the beginning; the stream cannot
-#     be changed to readable.
-# *   `'a'`: Write-only stream, positioned at the end; every write appends to
-#     the end; the stream cannot be changed to readable.
-# *   `'r+'`: Read-write stream, positioned at the beginning.
-# *   `'w+'`: Read-write stream, positioned at the end.
-# *   `'a+'`: Read-write stream, positioned at the end.
-#
-#
-# For a writable file stream (that is, any except read-only), the file is
-# truncated to zero if it exists, and is created if it does not exist.
-#
-# Examples:
-#
-#     File.open('t.txt', 'r')
-#     File.open('t.tmp', 'w')
-#
-# Either of the following may be suffixed to any of the above:
-#
-# *   `'t'`: Text data; sets the default external encoding to `Encoding::UTF_8`;
-#     on Windows, enables conversion between EOL and CRLF.
-# *   `'b'`: Binary data; sets the default external encoding to
-#     `Encoding::ASCII_8BIT`; on Windows, suppresses conversion between EOL and
-#     CRLF.
-#
-#
-# If neither is given, the stream defaults to text data.
-#
-# Examples:
-#
-#     File.open('t.txt', 'rt')
-#     File.open('t.dat', 'rb')
-#
-# The following may be suffixed to any writable mode above:
-#
-# *   `'x'`: Creates the file if it does not exist; raises an exception if the
-#     file exists.
-#
-#
-# Example:
-#
-#     File.open('t.tmp', 'wx')
-#
-# Finally, the mode string may specify encodings -- either external encoding
-# only or both external and internal encodings -- by appending one or both
-# encoding names, separated by colons:
+# ## Example Files
 #
-#     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>
+# Many examples here use these variables:
 #
-# The numerous encoding names are available in array Encoding.name_list:
+#     # English text with newlines.
+#     text = <<~EOT
+#       First line
+#       Second line
 #
-#     Encoding.name_list.size    # => 175
-#     Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]
+#       Fourth line
+#       Fifth line
+#     EOT
 #
-# ## Encodings
+#     # Russian text.
+#     russian = "\u{442 435 441 442}" # => "тест"
 #
-# 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.
+#     # Binary data.
+#     data = "\u9990\u9991\u9992\u9993\u9994"
 #
-# 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 Encoding.
+#     # Text file.
+#     File.write('t.txt', text)
 #
-# 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.
+#     # File with Russian text.
+#     File.write('t.rus', russian)
 #
-# Note that the BOM-style encoding option is case insensitive, so 'bom|utf-8' is
-# also valid.)
+#     # File with binary data.
+#     f = File.new('t.dat', 'wb:UTF-16')
+#     f.write(data)
+#     f.close
 #
 # ## Open Options
 #
-# A number of IO methods accept an optional parameter `opts`, which determines
-# how a new stream is to be opened:
+# A number of IO methods accept optional keyword arguments that determine how a
+# new stream is to be opened:
 #
 # *   `:mode`: Stream mode.
 # *   `:flags`: Integer file open flags; If `mode` is also given, the two are
@@ -241,430 +105,520 @@
 #     otherwise.
 # *   `:autoclose`: If a truthy value, specifies that the `fd` will close when
 #     the stream closes; otherwise it remains open.
+# *   `:path:` If a string value is provided, it is used in #inspect and is
+#     available as #path method.
 #
 #
 # Also available are the options offered in String#encode, which may control
 # conversion between external internal encoding.
 #
-# ## Getline Options
+# ## Basic IO
 #
-# A number of IO methods accept optional keyword arguments that determine how a
-# stream is to be treated:
+# You can perform basic stream IO with these methods, which typically operate on
+# multi-byte strings:
 #
-# *   `:chomp`: If `true`, line separators are omitted; default is  `false`.
+# *   IO#read: Reads and returns some or all of the remaining bytes from the
+#     stream.
+# *   IO#write: Writes zero or more strings to the stream; each given object
+#     that is not already a string is converted via `to_s`.
 #
 #
-# ## Position
+# ### Position
 #
-# An IO stream has a *position*, which is the non-negative integer offset (in
-# bytes) in the stream where the next read or write will occur.
+# An IO stream has a nonnegative integer *position*, which is the byte offset at
+# which the next read or write is to occur. A new stream has position zero (and
+# line number zero); method `rewind` resets the position (and line number) to
+# zero.
 #
-# Note that a text stream may have multi-byte characters, so a text stream whose
-# position is `n` (*bytes*) may not have `n` *characters* preceding the current
-# position -- there may be fewer.
+# The relevant methods:
 #
-# A new stream is initially positioned:
+# *   IO#tell (aliased as `#pos`): Returns the current position (in bytes) in
+#     the stream.
+# *   IO#pos=: Sets the position of the stream to a given integer `new_position`
+#     (in bytes).
+# *   IO#seek: Sets the position of the stream to a given integer `offset` (in
+#     bytes), relative to a given position `whence` (indicating the beginning,
+#     end, or current position).
+# *   IO#rewind: Positions the stream at the beginning (also resetting the line
+#     number).
 #
-# *   At the beginning (position `0`) if its mode is `'r'`, `'w'`, or `'r+'`.
-# *   At the end (position `self.size`) if its mode is `'a'`, `'w+'`, or `'a+'`.
 #
+# ### Open and Closed Streams
 #
-# Methods to query the position:
+# A new IO stream may be open for reading, open for writing, or both.
 #
-# *   IO#tell and its alias IO#pos return the position for an open stream.
-# *   IO#eof? and its alias IO#eof return whether the position is at the end of
-#     a readable stream.
+# A stream is automatically closed when claimed by the garbage collector.
 #
+# Attempted reading or writing on a closed stream raises an exception.
 #
-# Reading from a stream usually changes its position:
+# The relevant methods:
 #
-#     f = File.open('t.txt')
-#     f.tell     # => 0
-#     f.readline # => "This is line one.\n"
-#     f.tell     # => 19
-#     f.readline # => "This is the second line.\n"
-#     f.tell     # => 45
-#     f.eof?     # => false
-#     f.readline # => "Here's the third line.\n"
-#     f.eof?     # => true
+# *   IO#close: Closes the stream for both reading and writing.
+# *   IO#close_read: Closes the stream for reading.
+# *   IO#close_write: Closes the stream for writing.
+# *   IO#closed?: Returns whether the stream is closed.
 #
-# Writing to a stream usually changes its position:
 #
-#     f = File.open('t.tmp', 'w')
-#     f.tell         # => 0
-#     f.write('foo') # => 3
-#     f.tell         # => 3
-#     f.write('bar') # => 3
-#     f.tell         # => 6
+# ### End-of-Stream
 #
-# Iterating over a stream usually changes its position:
+# You can query whether a stream is positioned at its end:
 #
-#     f = File.open('t.txt')
-#     f.each do |line|
-#       p "position=#{f.pos} eof?=#{f.eof?} line=#{line}"
-#     end
+# *   IO#eof? (also aliased as `#eof`): Returns whether the stream is at
+#     end-of-stream.
 #
-# Output:
 #
-#     "position=19 eof?=false line=This is line one.\n"
-#     "position=45 eof?=false line=This is the second line.\n"
-#     "position=70 eof?=true line=This is the third line.\n"
+# You can reposition to end-of-stream by using method IO#seek:
 #
-# The position may also be changed by certain other methods:
+#     f = File.new('t.txt')
+#     f.eof? # => false
+#     f.seek(0, :END)
+#     f.eof? # => true
+#     f.close
 #
-# *   IO#pos= and IO#seek change the position to a specified offset.
-# *   IO#rewind changes the position to the beginning.
+# Or by reading all stream content (which is slower than using IO#seek):
 #
+#     f.rewind
+#     f.eof? # => false
+#     f.read # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+#     f.eof? # => true
 #
-# ## Line Number
+# ## Line IO
 #
-# A readable IO stream has a *line* *number*, which is the non-negative integer
-# line number in the stream where the next read will occur.
+# You can read an IO stream line-by-line using these methods:
 #
-# A new stream is initially has line number `0`.
+# *   IO#each_line: Reads each remaining line, passing it to the given block.
+# *   IO#gets: Returns the next line.
+# *   IO#readline: Like #gets, but raises an exception at end-of-stream.
+# *   IO#readlines: Returns all remaining lines in an array.
 #
-# Method IO#lineno returns the line number.
 #
-# Reading lines from a stream usually changes its line number:
+# Each of these reader methods accepts:
 #
-#     f = File.open('t.txt', 'r')
-#     f.lineno   # => 0
-#     f.readline # => "This is line one.\n"
-#     f.lineno   # => 1
-#     f.readline # => "This is the second line.\n"
-#     f.lineno   # => 2
-#     f.readline # => "Here's the third line.\n"
-#     f.lineno   # => 3
-#     f.eof?     # => true
+# *   An optional line separator, `sep`; see [Line
+#     Separator](rdoc-ref:IO@Line+Separator).
+# *   An optional line-size limit, `limit`; see [Line
+#     Limit](rdoc-ref:IO@Line+Limit).
 #
-# Iterating over lines in a stream usually changes its line number:
 #
-#     f = File.open('t.txt')
-#     f.each_line do |line|
-#       p "position=#{f.pos} eof?=#{f.eof?} line=#{line}"
-#     end
+# For each of these reader methods, reading may begin mid-line, depending on the
+# stream's position; see [Position](rdoc-ref:IO@Position):
 #
-# Output:
+#     f = File.new('t.txt')
+#     f.pos = 27
+#     f.each_line {|line| p line }
+#     f.close
 #
-#     "position=19 eof?=false line=This is line one.\n"
-#     "position=45 eof?=false line=This is the second line.\n"
-#     "position=70 eof?=true line=This is the third line.\n"
-#
-# ## What's Here
+# Output:
 #
-# First, what's elsewhere. Class IO:
+#     "rth line\n"
+#     "Fifth line\n"
 #
-# *   Inherits from [class
-#     Object](Object.html#class-Object-label-What-27s+Here).
-# *   Includes [module
-#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
-#     provides dozens of additional methods.
+# You can write to an IO stream line-by-line using this method:
 #
+# *   IO#puts: Writes objects to the stream.
 #
-# Here, class IO provides methods that are useful for:
 #
-# *   [Creating](#class-IO-label-Creating)
-# *   [Reading](#class-IO-label-Reading)
-# *   [Writing](#class-IO-label-Writing)
-# *   [Positioning](#class-IO-label-Positioning)
-# *   [Iterating](#class-IO-label-Iterating)
-# *   [Settings](#class-IO-label-Settings)
-# *   [Querying](#class-IO-label-Querying)
-# *   [Buffering](#class-IO-label-Buffering)
-# *   [Low-Level Access](#class-IO-label-Low-Level+Access)
-# *   [Other](#class-IO-label-Other)
+# ### Line Separator
 #
+# Each of these methods uses a *line separator*, which is the string that
+# delimits lines:
 #
-# ### Creating
+# *   IO.foreach.
+# *   IO.readlines.
+# *   IO#each_line.
+# *   IO#gets.
+# *   IO#readline.
+# *   IO#readlines.
 #
-#     ::new (aliased as ::for_fd)
-# :       Creates and returns a new IO object for the given integer file
-#         descriptor.
 #
-#     ::open
-# :       Creates a new IO object.
+# The default line separator is the given by the global variable `$/`, whose
+# value is by default `"\n"`. The line to be read next is all data from the
+# current position to the next line separator:
 #
-#     ::pipe
-# :       Creates a connected pair of reader and writer IO objects.
+#     f = File.new('t.txt')
+#     f.gets # => "First line\n"
+#     f.gets # => "Second line\n"
+#     f.gets # => "\n"
+#     f.gets # => "Fourth line\n"
+#     f.gets # => "Fifth line\n"
+#     f.close
 #
-#     ::popen
-# :       Creates an IO object to interact with a subprocess.
+# You can specify a different line separator:
 #
-#     ::select
-# :       Selects which given IO instances are ready for reading,
+#     f = File.new('t.txt')
+#     f.gets('l')   # => "First l"
+#     f.gets('li')  # => "ine\nSecond li"
+#     f.gets('lin') # => "ne\n\nFourth lin"
+#     f.gets        # => "e\n"
+#     f.close
 #
-#     writing, or have pending exceptions.
+# There are two special line separators:
 #
+# *   `nil`: The entire stream is read into a single string:
 #
-# ### Reading
+#         f = File.new('t.txt')
+#         f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+#         f.close
 #
-#     ::binread
-# :       Returns a binary string with all or a subset of bytes from the given
-#         file.
+# *   `''` (the empty string): The next "paragraph" is read (paragraphs being
+#     separated by two consecutive line separators):
 #
-#     ::read
-# :       Returns a string with all or a subset of bytes from the given file.
+#         f = File.new('t.txt')
+#         f.gets('') # => "First line\nSecond line\n\n"
+#         f.gets('') # => "Fourth line\nFifth line\n"
+#         f.close
 #
-#     ::readlines
-# :       Returns an array of strings, which are the lines from the given file.
 #
-#     #getbyte
-# :       Returns the next 8-bit byte read from `self` as an integer.
+# ### Line Limit
 #
-#     #getc
-# :       Returns the next character read from `self` as a string.
+# Each of these methods uses a *line limit*, which specifies that the number of
+# bytes returned may not be (much) longer than the given `limit`;
 #
-#     #gets
-# :       Returns the line read from `self`.
+# *   IO.foreach.
+# *   IO.readlines.
+# *   IO#each_line.
+# *   IO#gets.
+# *   IO#readline.
+# *   IO#readlines.
 #
-#     #pread
-# :       Returns all or the next *n* bytes read from `self`, not updating the
-#         receiver's offset.
 #
-#     #read
-# :       Returns all remaining or the next *n* bytes read from `self` for a
-#         given *n*.
+# A multi-byte character will not be split, and so a line may be slightly longer
+# than the given limit.
 #
-#     #read_nonblock
-# :       the next *n* bytes read from `self` for a given *n*, in non-block
-#         mode.
+# If `limit` is not given, the line is determined only by `sep`.
 #
-#     #readbyte
-# :       Returns the next byte read from `self`; same as #getbyte, but raises
-#         an exception on end-of-file.
+#     # Text with 1-byte characters.
+#     File.open('t.txt') {|f| f.gets(1) }  # => "F"
+#     File.open('t.txt') {|f| f.gets(2) }  # => "Fi"
+#     File.open('t.txt') {|f| f.gets(3) }  # => "Fir"
+#     File.open('t.txt') {|f| f.gets(4) }  # => "Firs"
+#     # No more than one line.
+#     File.open('t.txt') {|f| f.gets(10) } # => "First line"
+#     File.open('t.txt') {|f| f.gets(11) } # => "First line\n"
+#     File.open('t.txt') {|f| f.gets(12) } # => "First line\n"
 #
-#     #readchar
-# :       Returns the next character read from `self`; same as #getc, but raises
-#         an exception on end-of-file.
+#     # Text with 2-byte characters, which will not be split.
+#     File.open('t.rus') {|f| f.gets(1).size } # => 1
+#     File.open('t.rus') {|f| f.gets(2).size } # => 1
+#     File.open('t.rus') {|f| f.gets(3).size } # => 2
+#     File.open('t.rus') {|f| f.gets(4).size } # => 2
 #
-#     #readline
-# :       Returns the next line read from `self`; same as #getline, but raises
-#         an exception of end-of-file.
+# ### Line Separator and Line Limit
 #
-#     #readlines
-# :       Returns an array of all lines read read from `self`.
+# With arguments `sep` and `limit` given, combines the two behaviors:
 #
-#     #readpartial
-# :       Returns up to the given number of bytes from `self`.
+# *   Returns the next line as determined by line separator `sep`.
+# *   But returns no more bytes than are allowed by the limit.
 #
 #
+# Example:
 #
-# ### Writing
+#     File.open('t.txt') {|f| f.gets('li', 20) } # => "First li"
+#     File.open('t.txt') {|f| f.gets('li', 2) }  # => "Fi"
 #
-#     ::binwrite
-# :       Writes the given string to the file at the given filepath, in binary
-#         mode.
+# ### Line Number
 #
-#     ::write
-# :       Writes the given string to `self`.
+# A readable IO stream has a non-negative integer *line number*.
 #
-#     [:<<](#method-i-3C-3C)
-# :       Appends the given string to `self`.
+# The relevant methods:
 #
-#     #print
-# :       Prints last read line or given objects to `self`.
+# *   IO#lineno: Returns the line number.
+# *   IO#lineno=: Resets and returns the line number.
 #
-#     #printf
-# :       Writes to `self` based on the given format string and objects.
 #
-#     #putc
-# :       Writes a character to `self`.
+# Unless modified by a call to method IO#lineno=, the line number is the number
+# of lines read by certain line-oriented methods, according to the given line
+# separator `sep`:
 #
-#     #puts
-# :       Writes lines to `self`, making sure line ends with a newline.
+# *   IO.foreach: Increments the line number on each call to the block.
+# *   IO#each_line: Increments the line number on each call to the block.
+# *   IO#gets: Increments the line number.
+# *   IO#readline: Increments the line number.
+# *   IO#readlines: Increments the line number for each line read.
 #
-#     #pwrite
-# :       Writes the given string at the given offset, not updating the
-#         receiver's offset.
 #
-#     #write
-# :       Writes one or more given strings to `self`.
+# A new stream is initially has line number zero (and position zero); method
+# `rewind` resets the line number (and position) to zero:
 #
-#     #write_nonblock
-# :       Writes one or more given strings to `self` in non-blocking mode.
+#     f = File.new('t.txt')
+#     f.lineno # => 0
+#     f.gets   # => "First line\n"
+#     f.lineno # => 1
+#     f.rewind
+#     f.lineno # => 0
+#     f.close
 #
+# Reading lines from a stream usually changes its line number:
 #
+#     f = File.new('t.txt', 'r')
+#     f.lineno   # => 0
+#     f.readline # => "This is line one.\n"
+#     f.lineno   # => 1
+#     f.readline # => "This is the second line.\n"
+#     f.lineno   # => 2
+#     f.readline # => "Here's the third line.\n"
+#     f.lineno   # => 3
+#     f.eof?     # => true
+#     f.close
 #
-# ### Positioning
+# Iterating over lines in a stream usually changes its line number:
 #
-#     #lineno
-# :       Returns the current line number in `self`.
+#     File.open('t.txt') do |f|
+#       f.each_line do |line|
+#         p "position=#{f.pos} eof?=#{f.eof?} lineno=#{f.lineno}"
+#       end
+#     end
 #
-#     #lineno=
-# :       Sets the line number is `self`.
+# Output:
 #
-#     #pos (aliased as #tell)
-# :       Returns the current byte offset in `self`.
+#     "position=11 eof?=false lineno=1"
+#     "position=23 eof?=false lineno=2"
+#     "position=24 eof?=false lineno=3"
+#     "position=36 eof?=false lineno=4"
+#     "position=47 eof?=true lineno=5"
 #
-#     #pos=
-# :       Sets the byte offset in `self`.
+# Unlike the stream's [position](rdoc-ref:IO@Position), the line number does not
+# affect where the next read or write will occur:
 #
-#     #reopen
-# :       Reassociates `self` with a new or existing IO stream.
+#     f = File.new('t.txt')
+#     f.lineno = 1000
+#     f.lineno # => 1000
+#     f.gets   # => "First line\n"
+#     f.lineno # => 1001
+#     f.close
 #
-#     #rewind
-# :       Positions `self` to the beginning of input.
+# Associated with the line number is the global variable `$.`:
 #
-#     #seek
-# :       Sets the offset for `self` relative to given position.
+# *   When a stream is opened, `$.` is not set; its value is left over from
+#     previous activity in the process:
 #
+#         $. = 41
+#         f = File.new('t.txt')
+#         $. = 41
+#         # => 41
+#         f.close
 #
+# *   When a stream is read, `#.` is set to the line number for that stream:
+#
+#         f0 = File.new('t.txt')
+#         f1 = File.new('t.dat')
+#         f0.readlines # => ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
+#         $.           # => 5
+#         f1.readlines # => ["\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"]
+#         $.           # => 1
+#         f0.close
+#         f1.close
+#
+# *   Methods IO#rewind and IO#seek do not affect `$.`:
+#
+#         f = File.new('t.txt')
+#         f.readlines # => ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
+#         $.          # => 5
+#         f.rewind
+#         f.seek(0, :SET)
+#         $.          # => 5
+#         f.close
 #
-# ### Iterating
 #
-#     ::foreach
-# :       Yields each line of given file to the block.
+# ## Character IO
 #
-#     #each (aliased as #each_line)
-# :       Calls the given block with each successive line in `self`.
+# You can process an IO stream character-by-character using these methods:
 #
-#     #each_byte
-# :       Calls the given block with each successive byte in `self` as an
-#         integer.
+# *   IO#getc: Reads and returns the next character from the stream.
+# *   IO#readchar: Like #getc, but raises an exception at end-of-stream.
+# *   IO#ungetc: Pushes back ("unshifts") a character or integer onto the
+#     stream.
+# *   IO#putc: Writes a character to the stream.
+# *   IO#each_char: Reads each remaining character in the stream, passing the
+#     character to the given block.
 #
-#     #each_char
-# :       Calls the given block with each successive character in `self` as a
-#         string.
+# ## Byte IO
 #
-#     #each_codepoint
-# :       Calls the given block with each successive codepoint in `self` as an
-#         integer.
+# You can process an IO stream byte-by-byte using these methods:
 #
+# *   IO#getbyte: Returns the next 8-bit byte as an integer in range 0..255.
+# *   IO#readbyte: Like #getbyte, but raises an exception if at end-of-stream.
+# *   IO#ungetbyte: Pushes back ("unshifts") a byte back onto the stream.
+# *   IO#each_byte: Reads each remaining byte in the stream, passing the byte to
+#     the given block.
 #
 #
-# ### Settings
+# ## Codepoint IO
 #
-#     #autoclose=
-# :       Sets whether `self` auto-closes.
+# You can process an IO stream codepoint-by-codepoint:
 #
-#     #binmode
-# :       Sets `self` to binary mode.
+# *   IO#each_codepoint: Reads each remaining codepoint, passing it to the given
+#     block.
 #
-#     #close
-# :       Closes `self`.
 #
-#     #close_on_exec=
-# :       Sets the close-on-exec flag.
+# ## What's Here
 #
-#     #close_read
-# :       Closes `self` for reading.
+# First, what's elsewhere. Class IO:
 #
-#     #close_write
-# :       Closes `self` for writing.
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
+#     provides dozens of additional methods.
 #
-#     #set_encoding
-# :       Sets the encoding for `self`.
 #
-#     #set_encoding_by_bom
-# :       Sets the encoding for `self`, based on its Unicode byte-order-mark.
+# Here, class IO provides methods that are useful for:
 #
-#     #sync=
-# :       Sets the sync-mode to the given value.
+# *   [Creating](rdoc-ref:IO@Creating)
+# *   [Reading](rdoc-ref:IO@Reading)
+# *   [Writing](rdoc-ref:IO@Writing)
+# *   [Positioning](rdoc-ref:IO@Positioning)
+# *   [Iterating](rdoc-ref:IO@Iterating)
+# *   [Settings](rdoc-ref:IO@Settings)
+# *   [Querying](rdoc-ref:IO@Querying)
+# *   [Buffering](rdoc-ref:IO@Buffering)
+# *   [Low-Level Access](rdoc-ref:IO@Low-Level+Access)
+# *   [Other](rdoc-ref:IO@Other)
 #
 #
+# ### Creating
 #
-# ### Querying
+# *   ::new (aliased as ::for_fd): Creates and returns a new IO object for the
+#     given integer file descriptor.
+# *   ::open: Creates a new IO object.
+# *   ::pipe: Creates a connected pair of reader and writer IO objects.
+# *   ::popen: Creates an IO object to interact with a subprocess.
+# *   ::select: Selects which given IO instances are ready for reading, writing,
+#     or have pending exceptions.
 #
-#     #autoclose?
-# :       Returns whether `self` auto-closes.
 #
-#     #binmode?
-# :       Returns whether `self` is in binary mode.
+# ### Reading
 #
-#     #close_on_exec?
-# :       Returns the close-on-exec flag for `self`.
+# *   ::binread: Returns a binary string with all or a subset of bytes from the
+#     given file.
+# *   ::read: Returns a string with all or a subset of bytes from the given
+#     file.
+# *   ::readlines: Returns an array of strings, which are the lines from the
+#     given file.
+# *   #getbyte: Returns the next 8-bit byte read from `self` as an integer.
+# *   #getc: Returns the next character read from `self` as a string.
+# *   #gets: Returns the line read from `self`.
+# *   #pread: Returns all or the next *n* bytes read from `self`, not updating
+#     the receiver's offset.
+# *   #read: Returns all remaining or the next *n* bytes read from `self` for a
+#     given *n*.
+# *   #read_nonblock: the next *n* bytes read from `self` for a given *n*, in
+#     non-block mode.
+# *   #readbyte: Returns the next byte read from `self`; same as #getbyte, but
+#     raises an exception on end-of-stream.
+# *   #readchar: Returns the next character read from `self`; same as #getc, but
+#     raises an exception on end-of-stream.
+# *   #readline: Returns the next line read from `self`; same as #getline, but
+#     raises an exception of end-of-stream.
+# *   #readlines: Returns an array of all lines read read from `self`.
+# *   #readpartial: Returns up to the given number of bytes from `self`.
 #
-#     #closed?
-# :       Returns whether `self` is closed.
 #
-#     #eof? (aliased as #eof)
-# :       Returns whether `self` is at end-of-file.
+# ### Writing
 #
-#     #external_encoding
-# :       Returns the external encoding object for `self`.
+# *   ::binwrite: Writes the given string to the file at the given filepath, in
+#     binary mode.
+# *   ::write: Writes the given string to `self`.
+# *   #<<: Appends the given string to `self`.
+# *   #print: Prints last read line or given objects to `self`.
+# *   #printf: Writes to `self` based on the given format string and objects.
+# *   #putc: Writes a character to `self`.
+# *   #puts: Writes lines to `self`, making sure line ends with a newline.
+# *   #pwrite: Writes the given string at the given offset, not updating the
+#     receiver's offset.
+# *   #write: Writes one or more given strings to `self`.
+# *   #write_nonblock: Writes one or more given strings to `self` in
+#     non-blocking mode.
 #
-#     #fileno (aliased as #to_i)
-# :       Returns the integer file descriptor for `self`
 #
-#     #internal_encoding
-# :       Returns the internal encoding object for `self`.
+# ### Positioning
 #
-#     #pid
-# :       Returns the process ID of a child process associated with `self`, if
-#         `self` was created by ::popen.
+# *   #lineno: Returns the current line number in `self`.
+# *   #lineno=: Sets the line number is `self`.
+# *   #pos (aliased as #tell): Returns the current byte offset in `self`.
+# *   #pos=: Sets the byte offset in `self`.
+# *   #reopen: Reassociates `self` with a new or existing IO stream.
+# *   #rewind: Positions `self` to the beginning of input.
+# *   #seek: Sets the offset for `self` relative to given position.
 #
-#     #stat
-# :       Returns the File::Stat object containing status information for
-#         `self`.
 #
-#     #sync
-# :       Returns whether `self` is in sync-mode.
+# ### Iterating
 #
-#     #tty (aliased as #isatty)
-# :       Returns whether `self` is a terminal.
+# *   ::foreach: Yields each line of given file to the block.
+# *   #each (aliased as #each_line): Calls the given block with each successive
+#     line in `self`.
+# *   #each_byte: Calls the given block with each successive byte in `self` as
+#     an integer.
+# *   #each_char: Calls the given block with each successive character in `self`
+#     as a string.
+# *   #each_codepoint: Calls the given block with each successive codepoint in
+#     `self` as an integer.
 #
 #
+# ### Settings
 #
-# ### Buffering
+# *   #autoclose=: Sets whether `self` auto-closes.
+# *   #binmode: Sets `self` to binary mode.
+# *   #close: Closes `self`.
+# *   #close_on_exec=: Sets the close-on-exec flag.
+# *   #close_read: Closes `self` for reading.
+# *   #close_write: Closes `self` for writing.
+# *   #set_encoding: Sets the encoding for `self`.
+# *   #set_encoding_by_bom: Sets the encoding for `self`, based on its Unicode
+#     byte-order-mark.
+# *   #sync=: Sets the sync-mode to the given value.
 #
-#     #fdatasync
-# :       Immediately writes all buffered data in `self` to disk.
 #
-#     #flush
-# :       Flushes any buffered data within `self` to the underlying operating
-#         system.
+# ### Querying
 #
-#     #fsync
-# :       Immediately writes all buffered data and attributes in `self` to disk.
+# *   #autoclose?: Returns whether `self` auto-closes.
+# *   #binmode?: Returns whether `self` is in binary mode.
+# *   #close_on_exec?: Returns the close-on-exec flag for `self`.
+# *   #closed?: Returns whether `self` is closed.
+# *   #eof? (aliased as #eof): Returns whether `self` is at end-of-stream.
+# *   #external_encoding: Returns the external encoding object for `self`.
+# *   #fileno (aliased as #to_i): Returns the integer file descriptor for `self`
+# *   #internal_encoding: Returns the internal encoding object for `self`.
+# *   #pid: Returns the process ID of a child process associated with `self`, if
+#     `self` was created by ::popen.
+# *   #stat: Returns the File::Stat object containing status information for
+#     `self`.
+# *   #sync: Returns whether `self` is in sync-mode.
+# *   #tty? (aliased as #isatty): Returns whether `self` is a terminal.
 #
-#     #ungetbyte
-# :       Prepends buffer for `self` with given integer byte or string.
 #
-#     #ungetc
-# :       Prepends buffer for `self` with given string.
+# ### Buffering
 #
+# *   #fdatasync: Immediately writes all buffered data in `self` to disk.
+# *   #flush: Flushes any buffered data within `self` to the underlying
+#     operating system.
+# *   #fsync: Immediately writes all buffered data and attributes in `self` to
+#     disk.
+# *   #ungetbyte: Prepends buffer for `self` with given integer byte or string.
+# *   #ungetc: Prepends buffer for `self` with given string.
 #
 #
 # ### Low-Level Access
 #
-#     ::sysopen
-# :       Opens the file given by its path, returning the integer file
-#         descriptor.
-#
-#     #advise
-# :       Announces the intention to access data from `self` in a specific way.
-#
-#     #fcntl
-# :       Passes a low-level command to the file specified by the given file
-#         descriptor.
-#
-#     #ioctl
-# :       Passes a low-level command to the device specified by the given file
-#         descriptor.
-#
-#     #sysread
-# :       Returns up to the next *n* bytes read from self using a low-level
-#         read.
-#
-#     #sysseek
-# :       Sets the offset for `self`.
-#
-#     #syswrite
-# :       Writes the given string to `self` using a low-level write.
-#
+# *   ::sysopen: Opens the file given by its path, returning the integer file
+#     descriptor.
+# *   #advise: Announces the intention to access data from `self` in a specific
+#     way.
+# *   #fcntl: Passes a low-level command to the file specified by the given file
+#     descriptor.
+# *   #ioctl: Passes a low-level command to the device specified by the given
+#     file descriptor.
+# *   #sysread: Returns up to the next *n* bytes read from self using a
+#     low-level read.
+# *   #sysseek: Sets the offset for `self`.
+# *   #syswrite: Writes the given string to `self` using a low-level write.
 #
 #
 # ### Other
 #
-#     ::copy_stream
-# :       Copies data from a source to a destination, each of which is a
-#         filepath or an IO-like object.
-#
-#     ::try_convert
-# :       Returns a new IO object resulting from converting the given object.
-#
-#     #inspect
-# :       Returns the string representation of `self`.
+# *   ::copy_stream: Copies data from a source to a destination, each of which
+#     is a filepath or an IO-like object.
+# *   ::try_convert: Returns a new IO object resulting from converting the given
+#     object.
+# *   #inspect: Returns the string representation of `self`.
 #
 %a{annotate:rdoc:source:from=io.c}
 class IO < Object
@@ -677,8 +631,8 @@ class IO < Object
   #   - self << object -> self
   # -->
   # Writes the given `object` to `self`, which must be opened for writing (see
-  # [Modes](#class-IO-label-Modes)); returns `self`; if `object` is not a string,
-  # it is converted via method `to_s`:
+  # [Access Modes](rdoc-ref:File@Access+Modes)); returns `self`; if `object` is
+  # not a string, it is converted via method `to_s`:
   #
   #     $stdout << 'Hello' << ', ' << 'World!' << "\n"
   #     $stdout << 'foo' << :bar << 2 << "\n"
@@ -692,56 +646,35 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.advise(advice, offset=0, len=0) -> nil
+  #   - advise(advice, offset = 0, len = 0) -> nil
   # -->
-  # Announce an intention to access data from the current file in a specific
-  # pattern. On platforms that do not support the *posix_fadvise(2)* system call,
-  # this method is a no-op.
+  # Invokes Posix system call
+  # [posix_fadvise(2)](https://linux.die.net/man/2/posix_fadvise), which announces
+  # an intention to access data from the current file in a particular manner.
   #
-  # *advice* is one of the following symbols:
+  # The arguments and results are platform-dependent.
   #
-  # :normal
-  # :   No advice to give; the default assumption for an open file.
-  # :sequential
-  # :   The data will be accessed sequentially with lower offsets read before
-  #     higher ones.
-  # :random
-  # :   The data will be accessed in random order.
-  # :willneed
-  # :   The data will be accessed in the near future.
-  # :dontneed
-  # :   The data will not be accessed in the near future.
-  # :noreuse
-  # :   The data will only be accessed once.
+  # The relevant data is specified by:
   #
+  # *   `offset`: The offset of the first byte of data.
+  # *   `len`: The number of bytes to be accessed; if `len` is zero, or is larger
+  #     than the number of bytes remaining, all remaining bytes will be accessed.
   #
-  # The semantics of a piece of advice are platform-dependent. See *man 2
-  # posix_fadvise* for details.
   #
-  # "data" means the region of the current file that begins at *offset* and
-  # extends for *len* bytes. If *len* is 0, the region ends at the last byte of
-  # the file. By default, both *offset* and *len* are 0, meaning that the advice
-  # applies to the entire file.
+  # Argument `advice` is one of the following symbols:
   #
-  # If an error occurs, one of the following exceptions will be raised:
+  # *   `:normal`: The application has no advice to give about its access pattern
+  #     for the specified data. If no advice is given for an open file, this is
+  #     the default assumption.
+  # *   `:sequential`: The application expects to access the specified data
+  #     sequentially (with lower offsets read before higher ones).
+  # *   `:random`: The specified data will be accessed in random order.
+  # *   `:noreuse`: The specified data will be accessed only once.
+  # *   `:willneed`: The specified data will be accessed in the near future.
+  # *   `:dontneed`: The specified data will not be accessed in the near future.
   #
-  # IOError
-  # :   The IO stream is closed.
-  # Errno::EBADF
-  # :   The file descriptor of the current file is invalid.
-  # Errno::EINVAL
-  # :   An invalid value for *advice* was given.
-  # Errno::ESPIPE
-  # :   The file descriptor of the current file refers to a FIFO or pipe. (Linux
-  #     raises Errno::EINVAL in this case).
-  # TypeError
-  # :   Either *advice* was not a Symbol, or one of the other arguments was not an
-  #     Integer.
-  # RangeError
-  # :   One of the arguments given was too big/small.
   #
-  # This list is not exhaustive; other Errno
-  # :   exceptions are also possible.
+  # Not implemented on all platforms.
   #
   def advise: (:normal | :sequential | :random | :willneed | :dontneed | :noreuse advise, ?Integer offset, ?Integer len) -> nil
 
@@ -774,43 +707,60 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.binmode    -> ios
+  #   - binmode -> self
   # -->
-  # Puts *ios* into binary mode. Once a stream is in binary mode, it cannot be
-  # reset to nonbinary mode.
+  # Sets the stream's data mode as binary (see [Data
+  # Mode](rdoc-ref:File@Data+Mode)).
   #
-  # *   newline conversion disabled
-  # *   encoding conversion disabled
-  # *   content is treated as ASCII-8BIT
+  # A stream's data mode may not be changed from binary to text.
   #
   def binmode: () -> self
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.binmode?    -> true or false
+  #   - binmode? -> true or false
   # -->
-  # Returns `true` if *ios* is binmode.
+  # Returns `true` if the stream is on binary mode, `false` otherwise. See [Data
+  # Mode](rdoc-ref:File@Data+Mode).
   #
   def binmode?: () -> bool
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.close   -> nil
+  #   - close -> nil
   # -->
-  # Closes *ios* and flushes any pending writes to the operating system. The
-  # stream is unavailable for any further data operations; an IOError is raised if
-  # such an attempt is made. I/O streams are automatically closed when they are
-  # claimed by the garbage collector.
+  # Closes the stream for both reading and writing if open for either or both;
+  # returns `nil`. See [Open and Closed
+  # Streams](rdoc-ref:IO@Open+and+Closed+Streams).
+  #
+  # If the stream is open for writing, flushes any buffered writes to the
+  # operating system before closing.
   #
-  # If *ios* is opened by IO.popen, #close sets `$?`.
+  # If the stream was opened by IO.popen, sets global variable `$?` (child exit
+  # status).
   #
-  # Calling this method on closed IO object is just ignored since Ruby 2.3.
+  # Example:
+  #
+  #     IO.popen('ruby', 'r+') do |pipe|
+  #       puts pipe.closed?
+  #       pipe.close
+  #       puts $?
+  #       puts pipe.closed?
+  #     end
+  #
+  # Output:
+  #
+  #     false
+  #     pid 13760 exit 0
+  #     true
+  #
+  # Related: IO#close_read, IO#close_write, IO#closed?.
   #
   def close: () -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.close_on_exec = bool    -> true or false
+  #   - self.close_on_exec = bool -> true or false
   # -->
   # Sets a close-on-exec flag.
   #
@@ -829,157 +779,272 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.close_on_exec?   -> true or false
+  #   - close_on_exec? -> true or false
   # -->
-  # Returns `true` if *ios* will be closed on exec.
+  # Returns `true` if the stream will be closed on exec, `false` otherwise:
   #
-  #     f = open("/dev/null")
-  #     f.close_on_exec?                 #=> false
-  #     f.close_on_exec = true
-  #     f.close_on_exec?                 #=> true
+  #     f = File.open('t.txt')
+  #     f.close_on_exec? # => true
   #     f.close_on_exec = false
-  #     f.close_on_exec?                 #=> false
+  #     f.close_on_exec? # => false
+  #     f.close
   #
   def close_on_exec?: () -> bool
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.close_read    -> nil
+  #   - close_read -> nil
   # -->
-  # Closes the read end of a duplex I/O stream (i.e., one that contains both a
-  # read and a write stream, such as a pipe). Will raise an IOError if the stream
-  # is not duplexed.
+  # Closes the stream for reading if open for reading; returns `nil`. See [Open
+  # and Closed Streams](rdoc-ref:IO@Open+and+Closed+Streams).
   #
-  #     f = IO.popen("/bin/sh","r+")
-  #     f.close_read
-  #     f.readlines
+  # If the stream was opened by IO.popen and is also closed for writing, sets
+  # global variable `$?` (child exit status).
   #
-  # *produces:*
+  # Example:
   #
-  #     prog.rb:3:in `readlines': not opened for reading (IOError)
-  #      from prog.rb:3
+  #     IO.popen('ruby', 'r+') do |pipe|
+  #       puts pipe.closed?
+  #       pipe.close_write
+  #       puts pipe.closed?
+  #       pipe.close_read
+  #       puts $?
+  #       puts pipe.closed?
+  #     end
   #
-  # Calling this method on closed IO object is just ignored since Ruby 2.3.
+  # Output:
+  #
+  #     false
+  #     false
+  #     pid 14748 exit 0
+  #     true
+  #
+  # Related: IO#close, IO#close_write, IO#closed?.
   #
   def close_read: () -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.close_write   -> nil
+  #   - close_write -> nil
   # -->
-  # Closes the write end of a duplex I/O stream (i.e., one that contains both a
-  # read and a write stream, such as a pipe). Will raise an IOError if the stream
-  # is not duplexed.
+  # Closes the stream for writing if open for writing; returns `nil`. See [Open
+  # and Closed Streams](rdoc-ref:IO@Open+and+Closed+Streams).
   #
-  #     f = IO.popen("/bin/sh","r+")
-  #     f.close_write
-  #     f.print "nowhere"
+  # Flushes any buffered writes to the operating system before closing.
   #
-  # *produces:*
+  # If the stream was opened by IO.popen and is also closed for reading, sets
+  # global variable `$?` (child exit status).
   #
-  #     prog.rb:3:in `write': not opened for writing (IOError)
-  #      from prog.rb:3:in `print'
-  #      from prog.rb:3
+  #     IO.popen('ruby', 'r+') do |pipe|
+  #       puts pipe.closed?
+  #       pipe.close_read
+  #       puts pipe.closed?
+  #       pipe.close_write
+  #       puts $?
+  #       puts pipe.closed?
+  #     end
   #
-  # Calling this method on closed IO object is just ignored since Ruby 2.3.
+  # Output:
+  #
+  #     false
+  #     false
+  #     pid 15044 exit 0
+  #     true
+  #
+  # Related: IO#close, IO#close_read, IO#closed?.
   #
   def close_write: () -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.closed?    -> true or false
+  #   - closed? -> true or false
   # -->
-  # Returns `true` if *ios* is completely closed (for duplex streams, both reader
-  # and writer), `false` otherwise.
+  # Returns `true` if the stream is closed for both reading and writing, `false`
+  # otherwise. See [Open and Closed Streams](rdoc-ref:IO@Open+and+Closed+Streams).
   #
-  #     f = File.new("testfile")
-  #     f.close         #=> nil
-  #     f.closed?       #=> true
-  #     f = IO.popen("/bin/sh","r+")
-  #     f.close_write   #=> nil
-  #     f.closed?       #=> false
-  #     f.close_read    #=> nil
-  #     f.closed?       #=> true
+  #     IO.popen('ruby', 'r+') do |pipe|
+  #       puts pipe.closed?
+  #       pipe.close_read
+  #       puts pipe.closed?
+  #       pipe.close_write
+  #       puts pipe.closed?
+  #     end
+  #
+  # Output:
+  #
+  #     false
+  #     false
+  #     true
+  #
+  # Related: IO#close_read, IO#close_write, IO#close.
   #
   def closed?: () -> bool
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.each(sep=$/ [, getline_args])          {|line| block } -> ios
-  #   - ios.each(limit [, getline_args])           {|line| block } -> ios
-  #   - ios.each(sep, limit [, getline_args])      {|line| block } -> ios
-  #   - ios.each(...)                             -> an_enumerator
-  #   - ios.each_line(sep=$/ [, getline_args])     {|line| block } -> ios
-  #   - ios.each_line(limit [, getline_args])      {|line| block } -> ios
-  #   - ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios
-  #   - ios.each_line(...)                        -> an_enumerator
+  #   - each_line(sep = $/, chomp: false) {|line| ... }   -> self
+  #   - each_line(limit, chomp: false) {|line| ... }      -> self
+  #   - each_line(sep, limit, chomp: false) {|line| ... } -> self
+  #   - each_line                                   -> enumerator
   # -->
-  # Executes the block for every line in *ios*, where lines are separated by
-  # *sep*. *ios* must be opened for reading or an IOError will be raised.
+  # Calls the block with each remaining line read from the stream; returns `self`.
+  # Does nothing if already at end-of-stream; See [Line IO](rdoc-ref:IO@Line+IO).
   #
-  # If no block is given, an enumerator is returned instead.
+  # With no arguments given, reads lines as determined by line separator `$/`:
   #
-  #     f = File.new("testfile")
-  #     f.each {|line| puts "#{f.lineno}: #{line}" }
+  #     f = File.new('t.txt')
+  #     f.each_line {|line| p line }
+  #     f.each_line {|line| fail 'Cannot happen' }
+  #     f.close
   #
-  # *produces:*
+  # Output:
+  #
+  #     "First line\n"
+  #     "Second line\n"
+  #     "\n"
+  #     "Fourth line\n"
+  #     "Fifth line\n"
+  #
+  # With only string argument `sep` given, reads lines as determined by line
+  # separator `sep`; see [Line Separator](rdoc-ref:IO@Line+Separator):
   #
-  #     1: This is line one
-  #     2: This is line two
-  #     3: This is line three
-  #     4: And so on...
+  #     f = File.new('t.txt')
+  #     f.each_line('li') {|line| p line }
+  #     f.close
+  #
+  # Output:
+  #
+  #     "First li"
+  #     "ne\nSecond li"
+  #     "ne\n\nFourth li"
+  #     "ne\nFifth li"
+  #     "ne\n"
+  #
+  # The two special values for `sep` are honored:
+  #
+  #     f = File.new('t.txt')
+  #     # Get all into one string.
+  #     f.each_line(nil) {|line| p line }
+  #     f.close
+  #
+  # Output:
   #
-  # See IO.readlines for details about getline_args.
+  #     "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #
+  #     f.rewind
+  #     # Get paragraphs (up to two line separators).
+  #     f.each_line('') {|line| p line }
+  #
+  # Output:
+  #
+  #     "First line\nSecond line\n\n"
+  #     "Fourth line\nFifth line\n"
+  #
+  # With only integer argument `limit` given, limits the number of bytes in each
+  # line; see [Line Limit](rdoc-ref:IO@Line+Limit):
+  #
+  #     f = File.new('t.txt')
+  #     f.each_line(8) {|line| p line }
+  #     f.close
+  #
+  # Output:
+  #
+  #     "First li"
+  #     "ne\n"
+  #     "Second l"
+  #     "ine\n"
+  #     "\n"
+  #     "Fourth l"
+  #     "ine\n"
+  #     "Fifth li"
+  #     "ne\n"
+  #
+  # With arguments `sep` and `limit` given, combines the two behaviors:
+  #
+  # *   Calls with the next line as determined by line separator `sep`.
+  # *   But returns no more bytes than are allowed by the limit.
+  #
+  #
+  # Optional keyword argument `chomp` specifies whether line separators are to be
+  # omitted:
+  #
+  #     f = File.new('t.txt')
+  #     f.each_line(chomp: true) {|line| p line }
+  #     f.close
+  #
+  # Output:
+  #
+  #     "First line"
+  #     "Second line"
+  #     ""
+  #     "Fourth line"
+  #     "Fifth line"
+  #
+  # Returns an Enumerator if no block is given.
+  #
+  # IO#each is an alias for IO#each_line.
   #
   def each: (?String sep, ?Integer limit) { (String arg0) -> untyped } -> self
           | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.each_byte {|byte| block }  -> ios
-  #   - ios.each_byte                  -> an_enumerator
+  #   - each_byte {|byte| ... } -> self
+  #   - each_byte               -> enumerator
   # -->
-  # Calls the given block once for each byte (0..255) in *ios*, passing the byte
-  # as an argument. The stream must be opened for reading or an IOError will be
-  # raised.
+  # Calls the given block with each byte (0..255) in the stream; returns `self`.
+  # See [Byte IO](rdoc-ref:IO@Byte+IO).
   #
-  # If no block is given, an enumerator is returned instead.
+  #     f = File.new('t.rus')
+  #     a = []
+  #     f.each_byte {|b| a << b }
+  #     a # => [209, 130, 208, 181, 209, 129, 209, 130]
+  #     f.close
   #
-  #     f = File.new("testfile")
-  #     checksum = 0
-  #     f.each_byte {|x| checksum ^= x }   #=> #<File:testfile>
-  #     checksum                           #=> 12
+  # Returns an Enumerator if no block is given.
+  #
+  # Related: IO#each_char, IO#each_codepoint.
   #
   def each_byte: () { (Integer arg0) -> untyped } -> self
                | () -> ::Enumerator[Integer, self]
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.each_char {|c| block }  -> ios
-  #   - ios.each_char               -> an_enumerator
+  #   - each_char {|c| ... } -> self
+  #   - each_char            -> enumerator
   # -->
-  # Calls the given block once for each character in *ios*, passing the character
-  # as an argument. The stream must be opened for reading or an IOError will be
-  # raised.
+  # Calls the given block with each character in the stream; returns `self`. See
+  # [Character IO](rdoc-ref:IO@Character+IO).
   #
-  # If no block is given, an enumerator is returned instead.
+  #     f = File.new('t.rus')
+  #     a = []
+  #     f.each_char {|c| a << c.ord }
+  #     a # => [1090, 1077, 1089, 1090]
+  #     f.close
   #
-  #     f = File.new("testfile")
-  #     f.each_char {|c| print c, ' ' }   #=> #<File:testfile>
+  # Returns an Enumerator if no block is given.
+  #
+  # Related: IO#each_byte, IO#each_codepoint.
   #
   def each_char: () { (String arg0) -> untyped } -> self
                | () -> ::Enumerator[String, self]
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.each_codepoint {|c| block }  -> ios
-  #   - ios.each_codepoint               -> an_enumerator
+  #   - each_codepoint {|c| ... } -> self
+  #   - each_codepoint            -> enumerator
   # -->
-  # Passes the Integer ordinal of each character in *ios*, passing the codepoint
-  # as an argument. The stream must be opened for reading or an IOError will be
-  # raised.
+  # Calls the given block with each codepoint in the stream; returns `self`:
+  #
+  #     f = File.new('t.rus')
+  #     a = []
+  #     f.each_codepoint {|c| a << c }
+  #     a # => [1090, 1077, 1089, 1090]
+  #     f.close
   #
-  # If no block is given, an enumerator is returned instead.
+  # Returns an Enumerator if no block is given.
+  #
+  # Related: IO#each_byte, IO#each_char.
   #
   def each_codepoint: () { (Integer arg0) -> untyped } -> self
                     | () -> ::Enumerator[Integer, self]
@@ -989,15 +1054,16 @@ class IO < Object
   #   - eof -> true or false
   # -->
   # Returns `true` if the stream is positioned at its end, `false` otherwise; see
-  # [Position](#class-IO-label-Position):
+  # [Position](rdoc-ref:IO@Position):
   #
   #     f = File.open('t.txt')
   #     f.eof           # => false
   #     f.seek(0, :END) # => 0
   #     f.eof           # => true
+  #     f.close
   #
   # Raises an exception unless the stream is opened for reading; see
-  # [Mode](#class-IO-label-Mode).
+  # [Mode](rdoc-ref:File@Access+Modes).
   #
   # If `self` is a stream such as pipe or socket, this method blocks until the
   # other end sends some data or closes it:
@@ -1017,20 +1083,23 @@ class IO < Object
   # not behave as you intend with IO#eof?, unless you call IO#rewind first (which
   # is not available for some streams).
   #
-  # I#eof? is an alias for IO#eof.
+  # IO#eof? is an alias for IO#eof.
   #
   def eof: () -> bool
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.fcntl(integer_cmd, arg)    -> integer
+  #   - fcntl(integer_cmd, argument) -> integer
   # -->
-  # Provides a mechanism for issuing low-level commands to control or query
-  # file-oriented I/O streams. Arguments and results are platform dependent. If
-  # *arg* is a number, its value is passed directly. If it is a string, it is
-  # interpreted as a binary sequence of bytes (Array#pack might be a useful way to
-  # build this string). On Unix platforms, see `fcntl(2)` for details.  Not
-  # implemented on all platforms.
+  # Invokes Posix system call [fcntl(2)](https://linux.die.net/man/2/fcntl), which
+  # provides a mechanism for issuing low-level commands to control or query a
+  # file-oriented I/O stream. Arguments and results are platform dependent.
+  #
+  # If +argument is a number, its value is passed directly; if it is a string, it
+  # is interpreted as a binary sequence of bytes. (Array#pack might be a useful
+  # way to build this string.)
+  #
+  # Not implemented on all platforms.
   #
   def fcntl: (Integer integer_cmd, String | Integer arg) -> Integer
 
@@ -1054,6 +1123,7 @@ class IO < Object
   #     $stdout.fileno            # => 1
   #     $stderr.fileno            # => 2
   #     File.open('t.txt').fileno # => 10
+  #     f.close
   #
   # IO#to_i is an alias for IO#fileno.
   #
@@ -1093,256 +1163,153 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.getbyte   -> integer or nil
+  #   - getbyte -> integer or nil
   # -->
-  # Gets the next 8-bit byte (0..255) from *ios*. Returns `nil` if called at end
-  # of file.
+  # Reads and returns the next byte (in range 0..255) from the stream; returns
+  # `nil` if already at end-of-stream. See [Byte IO](rdoc-ref:IO@Byte+IO).
   #
-  #     f = File.new("testfile")
-  #     f.getbyte   #=> 84
-  #     f.getbyte   #=> 104
+  #     f = File.open('t.txt')
+  #     f.getbyte # => 70
+  #     f.close
+  #     f = File.open('t.rus')
+  #     f.getbyte # => 209
+  #     f.close
+  #
+  # Related: IO#readbyte (may raise EOFError).
   #
   def getbyte: () -> Integer?
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.getc   -> string or nil
+  #   - getc -> character or nil
   # -->
-  # Reads a one-character string from *ios*. Returns `nil` if called at end of
-  # file.
+  # Reads and returns the next 1-character string from the stream; returns `nil`
+  # if already at end-of-stream. See [Character IO](rdoc-ref:IO@Character+IO).
   #
-  #     f = File.new("testfile")
-  #     f.getc   #=> "h"
-  #     f.getc   #=> "e"
+  #     f = File.open('t.txt')
+  #     f.getc     # => "F"
+  #     f.close
+  #     f = File.open('t.rus')
+  #     f.getc.ord # => 1090
+  #     f.close
+  #
+  # Related:  IO#readchar (may raise EOFError).
   #
   def getc: () -> String?
 
   # <!--
   #   rdoc-file=io.c
-  #   - gets(sep = $/, **getline_opts)   -> string or nil
-  #   - gets(limit, **getline_opts)      -> string or nil
-  #   - gets(sep, limit, **getline_opts) -> string or nil
+  #   - gets(sep = $/, chomp: false)   -> string or nil
+  #   - gets(limit, chomp: false)      -> string or nil
+  #   - gets(sep, limit, chomp: false) -> string or nil
   # -->
-  # Reads and returns data from the stream; assigns the return value to `$_`.
+  # Reads and returns a line from the stream; assigns the return value to `$_`.
+  # See [Line IO](rdoc-ref:IO@Line+IO).
   #
   # With no arguments given, returns the next line as determined by line separator
   # `$/`, or `nil` if none:
   #
   #     f = File.open('t.txt')
-  #     f.gets # => "This is line one.\n"
-  #     $_     # => "This is line one.\n"
-  #     f.gets # => "This is the second line.\n"
-  #     f.gets # => "This is the third line.\n"
+  #     f.gets # => "First line\n"
+  #     $_     # => "First line\n"
+  #     f.gets # => "\n"
+  #     f.gets # => "Fourth line\n"
+  #     f.gets # => "Fifth line\n"
   #     f.gets # => nil
+  #     f.close
   #
-  # With string argument `sep` given, but not argument `limit`, returns the next
-  # line as determined by line separator `sep`, or `nil` if none:
-  #
-  #     f = File.open('t.txt')
-  #     f.gets(' is') # => "This is"
-  #     f.gets(' is') # => " line one.\nThis is"
-  #     f.gets(' is') # => " the second line.\nThis is"
-  #     f.gets(' is') # => " the third line.\n"
-  #     f.gets(' is') # => nil
+  # With only string argument `sep` given, returns the next line as determined by
+  # line separator `sep`, or `nil` if none; see [Line
+  # Separator](rdoc-ref:IO@Line+Separator):
   #
-  # Note two special values for `sep`:
+  #     f = File.new('t.txt')
+  #     f.gets('l')   # => "First l"
+  #     f.gets('li')  # => "ine\nSecond li"
+  #     f.gets('lin') # => "ne\n\nFourth lin"
+  #     f.gets        # => "e\n"
+  #     f.close
   #
-  # *   `nil`: The entire stream is read and returned.
-  # *   `''` (empty string): The next "paragraph" is read and returned, the
-  #     paragraph separator being two successive line separators.
+  # The two special values for `sep` are honored:
   #
+  #     f = File.new('t.txt')
+  #     # Get all.
+  #     f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #     f.rewind
+  #     # Get paragraph (up to two line separators).
+  #     f.gets('')  # => "First line\nSecond line\n\n"
+  #     f.close
   #
-  # With integer argument `limit` given, returns up to `limit+1` bytes:
+  # With only integer argument `limit` given, limits the number of bytes in the
+  # line; see [Line Limit](rdoc-ref:IO@Line+Limit):
   #
-  #     # Text with 1-byte characters.
-  #     File.open('t.txt') {|f| f.gets(1) } # => "T"
-  #     File.open('t.txt') {|f| f.gets(2) } # => "Th"
-  #     File.open('t.txt') {|f| f.gets(3) } # => "Thi"
-  #     File.open('t.txt') {|f| f.gets(4) } # => "This"
   #     # No more than one line.
-  #     File.open('t.txt') {|f| f.gets(17) } # => "This is line one."
-  #     File.open('t.txt') {|f| f.gets(18) } # => "This is line one.\n"
-  #     File.open('t.txt') {|f| f.gets(19) } # => "This is line one.\n"
-  #
-  #     # Text with 2-byte characters, which will not be split.
-  #     File.open('t.rus') {|f| f.gets(1).size } # => 1
-  #     File.open('t.rus') {|f| f.gets(2).size } # => 1
-  #     File.open('t.rus') {|f| f.gets(3).size } # => 2
-  #     File.open('t.rus') {|f| f.gets(4).size } # => 2
+  #     File.open('t.txt') {|f| f.gets(10) } # => "First line"
+  #     File.open('t.txt') {|f| f.gets(11) } # => "First line\n"
+  #     File.open('t.txt') {|f| f.gets(12) } # => "First line\n"
   #
-  # With arguments `sep` and `limit`, combines the two behaviors above:
+  # With arguments `sep` and `limit` given, combines the two behaviors:
   #
   # *   Returns the next line as determined by line separator `sep`, or `nil` if
   #     none.
-  # *   But returns no more than `limit+1` bytes.
+  # *   But returns no more bytes than are allowed by the limit.
   #
   #
-  # For all forms above, trailing optional keyword arguments may be given; see
-  # [Getline Options](#class-IO-label-Getline+Options):
+  # Optional keyword argument `chomp` specifies whether line separators are to be
+  # omitted:
   #
   #     f = File.open('t.txt')
   #     # Chomp the lines.
-  #     f.gets(chomp: true) # => "This is line one."
-  #     f.gets(chomp: true) # => "This is the second line."
-  #     f.gets(chomp: true) # => "This is the third line."
+  #     f.gets(chomp: true) # => "First line"
+  #     f.gets(chomp: true) # => "Second line"
+  #     f.gets(chomp: true) # => ""
+  #     f.gets(chomp: true) # => "Fourth line"
+  #     f.gets(chomp: true) # => "Fifth line"
   #     f.gets(chomp: true) # => nil
+  #     f.close
   #
   def gets: (?String sep, ?Integer limit) -> String?
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.new(fd [, mode] [, opt])   -> io
+  #   - IO.new(fd, mode = 'r', **opts) -> io
   # -->
-  # Returns a new IO object (a stream) for the given integer file descriptor `fd`
-  # and `mode` string.  `opt` may be used to specify parts of `mode` in a more
-  # readable fashion.  See also IO.sysopen and IO.for_fd.
-  #
-  # IO.new is called by various File and IO opening methods such as IO::open,
-  # Kernel#open, and File::open.
-  #
-  # ### Open Mode
-  #
-  # When `mode` is an integer it must be combination of the modes defined in
-  # File::Constants (`File::RDONLY`, `File::WRONLY|File::CREAT`). See the open(2)
-  # man page for more information.
-  #
-  # When `mode` is a string it must be in one of the following forms:
-  #
-  #     fmode
-  #     fmode ":" ext_enc
-  #     fmode ":" ext_enc ":" int_enc
-  #     fmode ":" "BOM|UTF-*"
-  #
-  # `fmode` is an IO open mode string, `ext_enc` is the external encoding for the
-  # IO and `int_enc` is the internal encoding.
-  #
-  # #### IO Open Mode
-  #
-  # Ruby allows the following open modes:
-  #
-  #     "r"  Read-only, starts at beginning of file  (default mode).
-  #
-  #     "r+" Read-write, starts at beginning of file.
-  #
-  #     "w"  Write-only, truncates existing file
-  #          to zero length or creates a new file for writing.
-  #
-  #     "w+" Read-write, truncates existing file to zero length
-  #          or creates a new file for reading and writing.
-  #
-  #     "a"  Write-only, each write call appends data at end of file.
-  #          Creates a new file for writing if file does not exist.
-  #
-  #     "a+" Read-write, each write call appends data at end of file.
-  #          Creates a new file for reading and writing if file does
-  #          not exist.
-  #
-  # The following modes must be used separately, and along with one or more of the
-  # modes seen above.
-  #
-  #     "b"  Binary file mode
-  #          Suppresses EOL <-> CRLF conversion on Windows. And
-  #          sets external encoding to ASCII-8BIT unless explicitly
-  #          specified.
-  #
-  #     "t"  Text file mode
+  # Creates and returns a new IO object (file stream) from a file descriptor.
   #
-  # The exclusive access mode ("x") can be used together with "w" to ensure the
-  # file is created. Errno::EEXIST is raised when it already exists. It may not be
-  # supported with all kinds of streams (e.g. pipes).
+  # IO.new may be useful for interaction with low-level libraries. For
+  # higher-level interactions, it may be simpler to create the file stream using
+  # File.open.
   #
-  # When the open mode of original IO is read only, the mode cannot be changed to
-  # be writable.  Similarly, the open mode cannot be changed from write only to
-  # readable.
+  # Argument `fd` must be a valid file descriptor (integer):
   #
-  # When such a change is attempted the error is raised in different locations
-  # according to the platform.
+  #     path = 't.tmp'
+  #     fd = IO.sysopen(path) # => 3
+  #     IO.new(fd)            # => #<IO:fd 3>
   #
-  # ### IO Encoding
+  # The new IO object does not inherit encoding (because the integer file
+  # descriptor does not have an encoding):
   #
-  # When `ext_enc` is specified, strings read will be tagged by the encoding when
-  # reading, and strings output will be converted to the specified encoding when
-  # writing.
+  #     fd = IO.sysopen('t.rus', 'rb')
+  #     io = IO.new(fd)
+  #     io.external_encoding # => #<Encoding:UTF-8> # Not ASCII-8BIT.
   #
-  # When `ext_enc` and `int_enc` are specified read strings will be converted from
-  # `ext_enc` to `int_enc` upon input, and written strings will be converted from
-  # `int_enc` to `ext_enc` upon output.  See Encoding for further details of
-  # transcoding on input and output.
+  # Optional argument `mode` (defaults to 'r') must specify a valid mode; see
+  # [Access Modes](rdoc-ref:File@Access+Modes):
   #
-  # If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, 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.  When present, the BOM is
-  # stripped and the external encoding from the BOM is used.  When the BOM is
-  # missing the given Unicode encoding is used as `ext_enc`.  (The BOM-set
-  # encoding option is case insensitive, so "bom|utf-8" is also valid.)
+  #     IO.new(fd, 'w')         # => #<IO:fd 3>
+  #     IO.new(fd, File::WRONLY) # => #<IO:fd 3>
   #
-  # ### Options
+  # Optional keyword arguments `opts` specify:
   #
-  # `opt` can be used instead of `mode` for improved readability.  The following
-  # keys are supported:
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  # :mode
-  # :   Same as `mode` parameter
   #
-  # :flags
-  # :   Specifies file open flags as integer. If `mode` parameter is given, this
-  #     parameter will be bitwise-ORed.
-  #
-  # :external_encoding
-  # :   External encoding for the IO.
-  #
-  # :internal_encoding
-  # :   Internal encoding for the IO.  "-" is a synonym for the default internal
-  #     encoding.
-  #
-  #     If the value is `nil` no conversion occurs.
-  #
-  # :encoding
-  # :   Specifies external and internal encodings as "extern:intern".
-  #
-  # :textmode
-  # :   If the value is truth value, same as "t" in argument `mode`.
-  #
-  # :binmode
-  # :   If the value is truth value, same as "b" in argument `mode`.
-  #
-  # :autoclose
-  # :   If the value is `false`, the `fd` will be kept open after this IO instance
-  #     gets finalized.
-  #
-  #
-  # Also, `opt` can have same keys in String#encode for controlling conversion
-  # between the external encoding and the internal encoding.
-  #
-  # ### Example 1
-  #
-  #     fd = IO.sysopen("/dev/tty", "w")
-  #     a = IO.new(fd,"w")
-  #     $stderr.puts "Hello"
-  #     a.puts "World"
-  #
-  # Produces:
-  #
-  #     Hello
-  #     World
-  #
-  # ### Example 2
-  #
-  #     require 'fcntl'
-  #
-  #     fd = STDERR.fcntl(Fcntl::F_DUPFD)
-  #     io = IO.new(fd, mode: 'w:UTF-16LE', cr_newline: true)
-  #     io.puts "Hello, World!"
-  #
-  #     fd = STDERR.fcntl(Fcntl::F_DUPFD)
-  #     io = IO.new(fd, mode: 'w', cr_newline: true,
-  #                 external_encoding: Encoding::UTF_16LE)
-  #     io.puts "Hello, World!"
+  # Examples:
   #
-  # Both of above print "Hello, World!" in UTF-16LE to standard error output with
-  # converting EOL generated by #puts to CR.
+  #     IO.new(fd, internal_encoding: nil) # => #<IO:fd 3>
+  #     IO.new(fd, autoclose: true)        # => #<IO:fd 3>
   #
-  def initialize: (Integer fd, ?Integer mode, ?Integer opt) -> void
+  def initialize: (int fd, ?string | int mode, ?path: string?, **untyped opts) -> void
 
   # <!--
   #   rdoc-file=io.c
@@ -1352,84 +1319,86 @@ class IO < Object
   #
   #     f = File.open('t.txt')
   #     f.inspect # => "#<File:t.txt>"
+  #     f.close
   #
   def inspect: () -> String
 
   # <!--
   #   rdoc-file=io.c
-  #   - io.internal_encoding   -> encoding
+  #   - internal_encoding -> encoding or nil
   # -->
-  # Returns the Encoding of the internal string if conversion is specified.
-  # Otherwise returns `nil`.
+  # Returns the Encoding object that represents the encoding of the internal
+  # string, if conversion is specified, or `nil` otherwise.
+  #
+  # See [Encodings](rdoc-ref:File@Encodings).
   #
   def internal_encoding: () -> Encoding
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.ioctl(integer_cmd, arg)    -> integer
+  #   - ioctl(integer_cmd, argument) -> integer
   # -->
-  # Provides a mechanism for issuing low-level commands to control or query I/O
-  # devices. Arguments and results are platform dependent. If *arg* is a number,
-  # its value is passed directly. If it is a string, it is interpreted as a binary
-  # sequence of bytes. On Unix platforms, see `ioctl(2)` for details. Not
-  # implemented on all platforms.
+  # Invokes Posix system call [ioctl(2)](https://linux.die.net/man/2/ioctl), which
+  # issues a low-level command to an I/O device.
+  #
+  # Issues a low-level command to an I/O device. The arguments and returned value
+  # are platform-dependent. The effect of the call is platform-dependent.
+  #
+  # If argument `argument` is an integer, it is passed directly; if it is a
+  # string, it is interpreted as a binary sequence of bytes.
+  #
+  # Not implemented on all platforms.
   #
   def ioctl: (Integer integer_cmd, String | Integer arg) -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.isatty   -> true or false
-  #   - ios.tty?     -> true or false
+  #   - isatty -> true or false
   # -->
-  # Returns `true` if *ios* is associated with a terminal device (tty), `false`
-  # otherwise.
+  # Returns `true` if the stream is associated with a terminal device (tty),
+  # `false` otherwise:
+  #
+  #     f = File.new('t.txt').isatty    #=> false
+  #     f.close
+  #     f = File.new('/dev/tty').isatty #=> true
+  #     f.close
   #
-  #     File.new("testfile").isatty   #=> false
-  #     File.new("/dev/tty").isatty   #=> true
+  # IO#tty? is an alias for IO#isatty.
   #
   def isatty: () -> bool
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.lineno    -> integer
+  #   - lineno -> integer
   # -->
-  # Returns the current line number in *ios*.  The stream must be opened for
-  # reading. #lineno counts the number of times #gets is called rather than the
-  # number of newlines encountered.  The two values will differ if #gets is called
-  # with a separator other than newline.
-  #
-  # Methods that use `$/` like #each, #lines and #readline will also increment
-  # #lineno.
-  #
-  # See also the `$.` variable.
-  #
-  #     f = File.new("testfile")
-  #     f.lineno   #=> 0
-  #     f.gets     #=> "This is line one\n"
-  #     f.lineno   #=> 1
-  #     f.gets     #=> "This is line two\n"
-  #     f.lineno   #=> 2
+  # Returns the current line number for the stream; see [Line
+  # Number](rdoc-ref:IO@Line+Number).
   #
   def lineno: () -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.lineno = integer    -> integer
+  #   - lineno = integer -> integer
   # -->
-  # Manually sets the current line number to the given value. `$.` is updated only
-  # on the next read.
-  #
-  #     f = File.new("testfile")
-  #     f.gets                     #=> "This is line one\n"
-  #     $.                         #=> 1
-  #     f.lineno = 1000
-  #     f.lineno                   #=> 1000
-  #     $.                         #=> 1         # lineno of last read
-  #     f.gets                     #=> "This is line two\n"
-  #     $.                         #=> 1001      # lineno of last read
+  # Sets and returns the line number for the stream; see [Line
+  # Number](rdoc-ref:IO@Line+Number).
   #
   def lineno=: (Integer arg0) -> Integer
 
+  # <!--
+  #   rdoc-file=io.c
+  #   - path -> string or nil
+  # -->
+  # Returns the path associated with the IO, or `nil` if there is no path
+  # associated with the IO. It is not guaranteed that the path exists on the
+  # filesystem.
+  #
+  #     $stdin.path # => "<STDIN>"
+  #
+  #     File.open("testfile") {|f| f.path} # => "testfile"
+  #
+  def path: () -> String?
+
   # <!--
   #   rdoc-file=io.c
   #   - pid -> integer or nil
@@ -1454,12 +1423,13 @@ class IO < Object
 
   # <!-- rdoc-file=io.c -->
   # Returns the current position (in bytes) in `self` (see
-  # [Position](#class-IO-label-Position)):
+  # [Position](rdoc-ref:IO@Position)):
   #
-  #     f = File.new('t.txt')
-  #     f.tell     # => 0
-  #     f.readline # => "This is line one.\n"
-  #     f.tell     # => 19
+  #     f = File.open('t.txt')
+  #     f.tell # => 0
+  #     f.gets # => "First line\n"
+  #     f.tell # => 12
+  #     f.close
   #
   # Related: IO#pos=, IO#seek.
   #
@@ -1472,12 +1442,13 @@ class IO < Object
   #   - pos = new_position -> new_position
   # -->
   # Seeks to the given `new_position` (in bytes); see
-  # [Position](#class-IO-label-Position):
+  # [Position](rdoc-ref:IO@Position):
   #
   #     f = File.open('t.txt')
   #     f.tell     # => 0
   #     f.pos = 20 # => 20
   #     f.tell     # => 20
+  #     f.close
   #
   # Related: IO#seek, IO#tell.
   #
@@ -1485,48 +1456,86 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.print               -> nil
-  #   - ios.print(obj, ...)     -> nil
+  #   - print(*objects) -> nil
   # -->
-  # Writes the given object(s) to *ios*. Returns `nil`.
+  # Writes the given objects to the stream; returns `nil`. Appends the output
+  # record separator `$OUTPUT_RECORD_SEPARATOR` (`$\`), if it is not `nil`. See
+  # [Line IO](rdoc-ref:IO@Line+IO).
   #
-  # The stream must be opened for writing. Each given object that isn't a string
-  # will be converted by calling its `to_s` method. When called without arguments,
-  # prints the contents of `$_`.
+  # With argument `objects` given, for each object:
   #
-  # If the output field separator (`$,`) is not `nil`, it is inserted between
-  # objects. If the output record separator (`$\`) is not `nil`, it is appended to
-  # the output.
+  # *   Converts via its method `to_s` if not a string.
+  # *   Writes to the stream.
+  # *   If not the last object, writes the output field separator
+  #     `$OUTPUT_FIELD_SEPARATOR` (`$,`) if it is not `nil`.
   #
-  #     $stdout.print("This is ", 100, " percent.\n")
   #
-  # *produces:*
+  # With default separators:
   #
-  #     This is 100 percent.
+  #     f = File.open('t.tmp', 'w+')
+  #     objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero']
+  #     p $OUTPUT_RECORD_SEPARATOR
+  #     p $OUTPUT_FIELD_SEPARATOR
+  #     f.print(*objects)
+  #     f.rewind
+  #     p f.read
+  #     f.close
+  #
+  # Output:
+  #
+  #     nil
+  #     nil
+  #     "00.00/10+0izerozero"
+  #
+  # With specified separators:
+  #
+  #     $\ = "\n"
+  #     $, = ','
+  #     f.rewind
+  #     f.print(*objects)
+  #     f.rewind
+  #     p f.read
+  #
+  # Output:
+  #
+  #     "0,0.0,0/1,0+0i,zero,zero\n"
+  #
+  # With no argument given, writes the content of `$_` (which is usually the most
+  # recent user input):
+  #
+  #     f = File.open('t.tmp', 'w+')
+  #     gets # Sets $_ to the most recent user input.
+  #     f.print
+  #     f.close
   #
   def print: (*untyped arg0) -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.printf(format_string [, obj, ...])   -> nil
+  #   - printf(format_string, *objects) -> nil
   # -->
-  # Formats and writes to *ios*, converting parameters under control of the format
-  # string. See Kernel#sprintf for details.
+  # Formats and writes `objects` to the stream.
+  #
+  # For details on `format_string`, see [Format
+  # Specifications](rdoc-ref:format_specifications.rdoc).
   #
   def printf: (String format_string, *untyped arg0) -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.putc(obj)    -> obj
+  #   - putc(object) -> object
   # -->
-  # If *obj* is Numeric, write the character whose code is the least-significant
-  # byte of *obj*.  If *obj* is String, write the first character of *obj* to
-  # *ios*.  Otherwise, raise TypeError.
+  # Writes a character to the stream. See [Character
+  # IO](rdoc-ref:IO@Character+IO).
+  #
+  # If `object` is numeric, converts to integer if necessary, then writes the
+  # character whose code is the least significant byte; if `object` is a string,
+  # writes the first character:
   #
   #     $stdout.putc "A"
   #     $stdout.putc 65
   #
-  # *produces:*
+  # Output:
   #
   #     AA
   #
@@ -1534,40 +1543,60 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.puts(obj, ...)    -> nil
+  #   - puts(*objects) -> nil
   # -->
-  # Writes the given object(s) to *ios*. Writes a newline after any that do not
-  # already end with a newline sequence. Returns `nil`.
+  # Writes the given `objects` to the stream, which must be open for writing;
+  # returns `nil`.\ Writes a newline after each that does not already end with a
+  # newline sequence. If called without arguments, writes a newline. See [Line
+  # IO](rdoc-ref:IO@Line+IO).
   #
-  # The stream must be opened for writing. If called with an array argument,
-  # writes each element on a new line. Each given object that isn't a string or
-  # array will be converted by calling its `to_s` method. If called without
-  # arguments, outputs a single newline.
+  # Note that each added newline is the character `"\n"<//tt>, not the output
+  # record separator (<tt>$\`).
   #
-  #     $stdout.puts("this", "is", ["a", "test"])
+  # Treatment for each object:
   #
-  # *produces:*
+  # *   String: writes the string.
+  # *   Neither string nor array: writes `object.to_s`.
+  # *   Array: writes each element of the array; arrays may be nested.
+  #
+  #
+  # To keep these examples brief, we define this helper method:
+  #
+  #     def show(*objects)
+  #       # Puts objects to file.
+  #       f = File.new('t.tmp', 'w+')
+  #       f.puts(objects)
+  #       # Return file content.
+  #       f.rewind
+  #       p f.read
+  #       f.close
+  #     end
   #
-  #     this
-  #     is
-  #     a
-  #     test
+  #     # Strings without newlines.
+  #     show('foo', 'bar', 'baz')     # => "foo\nbar\nbaz\n"
+  #     # Strings, some with newlines.
+  #     show("foo\n", 'bar', "baz\n") # => "foo\nbar\nbaz\n"
   #
-  # Note that `puts` always uses newlines and is not affected by the output record
-  # separator (`$\`).
+  #     # Neither strings nor arrays:
+  #     show(0, 0.0, Rational(0, 1), Complex(9, 0), :zero)
+  #     # => "0\n0.0\n0/1\n9+0i\nzero\n"
+  #
+  #     # Array of strings.
+  #     show(['foo', "bar\n", 'baz']) # => "foo\nbar\nbaz\n"
+  #     # Nested arrays.
+  #     show([[[0, 1], 2, 3], 4, 5])  # => "0\n1\n2\n3\n4\n5\n"
   #
   def puts: (*untyped arg0) -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - read(maxlen = nil)             -> string or nil
-  #   - read(maxlen = nil, out_string) -> out_string or nil
+  #   - read(maxlen = nil, out_string = nil) -> new_string, out_string, or nil
   # -->
-  # Reads bytes from the stream (in binary mode):
+  # Reads bytes from the stream; the stream must be opened for reading (see
+  # [Access Modes](rdoc-ref:File@Access+Modes)):
   #
-  # *   If `maxlen` is `nil`, reads all bytes.
-  # *   Otherwise reads `maxlen` bytes, if available.
-  # *   Otherwise reads all bytes.
+  # *   If `maxlen` is `nil`, reads all bytes using the stream's data mode.
+  # *   Otherwise reads up to `maxlen` bytes in binary mode.
   #
   #
   # Returns a string (either a new string or the given `out_string`) containing
@@ -1589,11 +1618,12 @@ class IO < Object
   #
   #     f = File.new('t.txt')
   #     f.read
-  #     # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
+  #     # => "First line\nSecond line\n\nFourth line\nFifth line\n"
   #     f.rewind
-  #     f.read(40)      # => "This is line one.\r\nThis is the second li"
-  #     f.read(40)      # => "ne.\r\nThis is the third line.\r\n"
-  #     f.read(40)      # => nil
+  #     f.read(30) # => "First line\r\nSecond line\r\n\r\nFou"
+  #     f.read(30) # => "rth line\r\nFifth line\r\n"
+  #     f.read(30) # => nil
+  #     f.close
   #
   # If `maxlen` is zero, returns an empty string.
   #
@@ -1604,18 +1634,19 @@ class IO < Object
   #
   #     f = File.new('t.txt')
   #     s = 'foo'      # => "foo"
-  #     f.read(nil, s) # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
-  #     s              # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
+  #     f.read(nil, s) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #     s              # => "First line\nSecond line\n\nFourth line\nFifth line\n"
   #     f.rewind
   #     s = 'bar'
-  #     f.read(40, s)  # => "This is line one.\r\nThis is the second li"
-  #     s              # => "This is line one.\r\nThis is the second li"
+  #     f.read(30, s)  # => "First line\r\nSecond line\r\n\r\nFou"
+  #     s              # => "First line\r\nSecond line\r\n\r\nFou"
   #     s = 'baz'
-  #     f.read(40, s)  # => "ne.\r\nThis is the third line.\r\n"
-  #     s              # => "ne.\r\nThis is the third line.\r\n"
+  #     f.read(30, s)  # => "rth line\r\nFifth line\r\n"
+  #     s              # => "rth line\r\nFifth line\r\n"
   #     s = 'bat'
-  #     f.read(40, s)  # => nil
+  #     f.read(30, s)  # => nil
   #     s              # => ""
+  #     f.close
   #
   # Note that this method behaves like the fread() function in C. This means it
   # retries to invoke read(2) system calls to read data with the specified maxlen
@@ -1627,6 +1658,8 @@ class IO < Object
   # If you need the behavior like a single read(2) system call, consider
   # #readpartial, #read_nonblock, and #sysread.
   #
+  # Related: IO#write.
+  #
   def read: (?int? length, ?string outbuf) -> String?
 
   # <!--
@@ -1687,54 +1720,113 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.readbyte   -> integer
+  #   - readbyte -> integer
   # -->
-  # Reads a byte as with IO#getbyte, but raises an EOFError on end of file.
+  # Reads and returns the next byte (in range 0..255) from the stream; raises
+  # EOFError if already at end-of-stream. See [Byte IO](rdoc-ref:IO@Byte+IO).
+  #
+  #     f = File.open('t.txt')
+  #     f.readbyte # => 70
+  #     f.close
+  #     f = File.open('t.rus')
+  #     f.readbyte # => 209
+  #     f.close
+  #
+  # Related: IO#getbyte (will not raise EOFError).
   #
   def readbyte: () -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.readchar   -> string
+  #   - readchar -> string
   # -->
-  # Reads a one-character string from *ios*. Raises an EOFError on end of file.
+  # Reads and returns the next 1-character string from the stream; raises EOFError
+  # if already at end-of-stream. See [Character IO](rdoc-ref:IO@Character+IO).
   #
-  #     f = File.new("testfile")
-  #     f.readchar   #=> "h"
-  #     f.readchar   #=> "e"
+  #     f = File.open('t.txt')
+  #     f.readchar     # => "F"
+  #     f.close
+  #     f = File.open('t.rus')
+  #     f.readchar.ord # => 1090
+  #     f.close
+  #
+  # Related:  IO#getc (will not raise EOFError).
   #
   def readchar: () -> String
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.readline(sep=$/ [, getline_args])     -> string
-  #   - ios.readline(limit [, getline_args])      -> string
-  #   - ios.readline(sep, limit [, getline_args]) -> string
+  #   - readline(sep = $/, chomp: false)   -> string
+  #   - readline(limit, chomp: false)      -> string
+  #   - readline(sep, limit, chomp: false) -> string
+  # -->
+  # Reads a line as with IO#gets, but raises EOFError if already at end-of-stream.
+  #
+  # Optional keyword argument `chomp` specifies whether line separators are to be
+  # omitted.
+  #
+  def readline: (?String sep, ?Integer limit) -> String
+
+  # <!--
+  #   rdoc-file=io.c
+  #   - readlines(sep = $/, chomp: false)   -> array
+  #   - readlines(limit, chomp: false)       -> array
+  #   - readlines(sep, limit, chomp: false) -> array
   # -->
-  # Reads a line as with IO#gets, but raises an EOFError on end of file.
+  # Reads and returns all remaining line from the stream; does not modify `$_`.
+  # See [Line IO](rdoc-ref:IO@Line+IO).
+  #
+  # With no arguments given, returns lines as determined by line separator `$/`,
+  # or `nil` if none:
+  #
+  #     f = File.new('t.txt')
+  #     f.readlines
+  #     # => ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
+  #     f.readlines # => []
+  #     f.close
+  #
+  # With only string argument `sep` given, returns lines as determined by line
+  # separator `sep`, or `nil` if none; see [Line
+  # Separator](rdoc-ref:IO@Line+Separator):
+  #
+  #     f = File.new('t.txt')
+  #     f.readlines('li')
+  #     # => ["First li", "ne\nSecond li", "ne\n\nFourth li", "ne\nFifth li", "ne\n"]
+  #     f.close
+  #
+  # The two special values for `sep` are honored:
+  #
+  #     f = File.new('t.txt')
+  #     # Get all into one string.
+  #     f.readlines(nil)
+  #     # => ["First line\nSecond line\n\nFourth line\nFifth line\n"]
+  #     # Get paragraphs (up to two line separators).
+  #     f.rewind
+  #     f.readlines('')
+  #     # => ["First line\nSecond line\n\n", "Fourth line\nFifth line\n"]
+  #     f.close
+  #
+  # With only integer argument `limit` given, limits the number of bytes in each
+  # line; see [Line Limit](rdoc-ref:IO@Line+Limit):
   #
-  def readline: (?String sep, ?Integer limit) -> String
-
-  # <!--
-  #   rdoc-file=io.c
-  #   - ios.readlines(sep=$/ [, getline_args])     -> array
-  #   - ios.readlines(limit [, getline_args])      -> array
-  #   - ios.readlines(sep, limit [, getline_args]) -> array
-  # -->
-  # Reads all of the lines in *ios*, and returns them in an array. Lines are
-  # separated by the optional *sep*. If *sep* is `nil`, the rest of the stream is
-  # returned as a single record. If the first argument is an integer, or an
-  # optional second argument is given, the returning string would not be longer
-  # than the given value in bytes. The stream must be opened for reading or an
-  # IOError will be raised.
+  #     f = File.new('t.txt')
+  #     f.readlines(8)
+  #     # => ["First li", "ne\n", "Second l", "ine\n", "\n", "Fourth l", "ine\n", "Fifth li", "ne\n"]
+  #     f.close
   #
-  #     f = File.new("testfile")
-  #     f.readlines[0]   #=> "This is line one\n"
+  # With arguments `sep` and `limit` given, combines the two behaviors:
   #
-  #     f = File.new("testfile", chomp: true)
-  #     f.readlines[0]   #=> "This is line one"
+  # *   Returns lines as determined by line separator `sep`.
+  # *   But returns no more bytes in a line than are allowed by the limit.
   #
-  # See IO.readlines for details about getline_args.
+  #
+  # Optional keyword argument `chomp` specifies whether line separators are to be
+  # omitted:
+  #
+  #     f = File.new('t.txt')
+  #     f.readlines(chomp: true)
+  #     # => ["First line", "Second line", "", "Fourth line", "Fifth line"]
+  #     f.close
   #
   def readlines: (?String sep, ?Integer limit) -> ::Array[String]
 
@@ -1758,20 +1850,21 @@ class IO < Object
   # string:
   #
   #     f = File.new('t.txt')
-  #     f.readpartial(30) # => "This is line one.\nThis is the"
-  #     f.readpartial(30) # => " second line.\nThis is the thi"
-  #     f.readpartial(30) # => "rd line.\n"
-  #     f.eof             # => true
-  #     f.readpartial(30) # Raises EOFError.
+  #     f.readpartial(20) # => "First line\nSecond l"
+  #     f.readpartial(20) # => "ine\n\nFourth line\n"
+  #     f.readpartial(20) # => "Fifth line\n"
+  #     f.readpartial(20) # Raises EOFError.
+  #     f.close
   #
   # With both argument `maxlen` and string argument `out_string` given, returns
   # modified `out_string`:
   #
   #     f = File.new('t.txt')
   #     s = 'foo'
-  #     f.readpartial(30, s) # => "This is line one.\nThis is the"
+  #     f.readpartial(20, s) # => "First line\nSecond l"
   #     s = 'bar'
   #     f.readpartial(0, s)  # => ""
+  #     f.close
   #
   # This method is useful for a stream such as a pipe, a socket, or a tty. It
   # blocks only when no data is immediately available. This means that it blocks
@@ -1835,18 +1928,34 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.reopen(other_IO)             -> ios
-  #   - ios.reopen(path, mode [, opt])   -> ios
+  #   - reopen(other_io)                 -> self
+  #   - reopen(path, mode = 'r', **opts) -> self
   # -->
-  # Reassociates *ios* with the I/O stream given in *other_IO* or to a new stream
-  # opened on *path*. This may dynamically change the actual class of this stream.
-  # The `mode` and `opt` parameters accept the same values as IO.open.
+  # Reassociates the stream with another stream, which may be of a different
+  # class. This method may be used to redirect an existing stream to a new
+  # destination.
+  #
+  # With argument `other_io` given, reassociates with that stream:
+  #
+  #     # Redirect $stdin from a file.
+  #     f = File.open('t.txt')
+  #     $stdin.reopen(f)
+  #     f.close
+  #
+  #     # Redirect $stdout to a file.
+  #     f = File.open('t.tmp', 'w')
+  #     $stdout.reopen(f)
+  #     f.close
+  #
+  # With argument `path` given, reassociates with a new stream to that file path:
+  #
+  #     $stdin.reopen('t.txt')
+  #     $stdout.reopen('t.tmp', 'w')
+  #
+  # Optional keyword arguments `opts` specify:
   #
-  #     f1 = File.new("testfile")
-  #     f2 = File.new("testfile")
-  #     f2.readlines[0]   #=> "This is line one\n"
-  #     f2.reopen(f1)     #=> #<File:testfile>
-  #     f2.readlines[0]   #=> "This is line one\n"
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
   def reopen: (IO other_IO_or_path) -> IO
             | (String other_IO_or_path, ?String mode_str) -> IO
@@ -1856,18 +1965,19 @@ class IO < Object
   #   - rewind -> 0
   # -->
   # Repositions the stream to its beginning, setting both the position and the
-  # line number to zero; see [Position](#class-IO-label-Position) and [Line
-  # Number](#class-IO-label-Line+Number):
+  # line number to zero; see [Position](rdoc-ref:IO@Position) and [Line
+  # Number](rdoc-ref:IO@Line+Number):
   #
   #     f = File.open('t.txt')
   #     f.tell     # => 0
   #     f.lineno   # => 0
-  #     f.readline # => "This is line one.\n"
-  #     f.tell     # => 19
+  #     f.gets     # => "First line\n"
+  #     f.tell     # => 12
   #     f.lineno   # => 1
   #     f.rewind   # => 0
   #     f.tell     # => 0
   #     f.lineno   # => 0
+  #     f.close
   #
   # Note that this method cannot be used with streams such as pipes, ttys, and
   # sockets.
@@ -1879,7 +1989,7 @@ class IO < Object
   #   - seek(offset, whence = IO::SEEK_SET) -> 0
   # -->
   # Seeks to the position given by integer `offset` (see
-  # [Position](#class-IO-label-Position)) and constant `whence`, which is one of:
+  # [Position](rdoc-ref:IO@Position)) and constant `whence`, which is one of:
   #
   # *   `:CUR` or `IO::SEEK_CUR`: Repositions the stream to its current position
   #     plus the given `offset`:
@@ -1890,6 +2000,7 @@ class IO < Object
   #         f.tell            # => 20
   #         f.seek(-10, :CUR) # => 0
   #         f.tell            # => 10
+  #         f.close
   #
   # *   `:END` or `IO::SEEK_END`: Repositions the stream to its end plus the given
   #     `offset`:
@@ -1897,11 +2008,12 @@ class IO < Object
   #         f = File.open('t.txt')
   #         f.tell            # => 0
   #         f.seek(0, :END)   # => 0  # Repositions to stream end.
-  #         f.tell            # => 70
+  #         f.tell            # => 52
   #         f.seek(-20, :END) # => 0
-  #         f.tell            # => 50
+  #         f.tell            # => 32
   #         f.seek(-40, :END) # => 0
-  #         f.tell            # => 30
+  #         f.tell            # => 12
+  #         f.close
   #
   # *   `:SET` or `IO:SEEK_SET`: Repositions the stream to the given `offset`:
   #
@@ -1911,6 +2023,7 @@ class IO < Object
   #         f.tell           # => 20
   #         f.seek(40, :SET) # => 0
   #         f.tell           # => 40
+  #         f.close
   #
   #
   # Related: IO#pos=, IO#tell.
@@ -1919,39 +2032,49 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - io.set_encoding(ext_enc)                -> io
-  #   - io.set_encoding("ext_enc:int_enc")      -> io
-  #   - io.set_encoding(ext_enc, int_enc)       -> io
-  #   - io.set_encoding("ext_enc:int_enc", opt) -> io
-  #   - io.set_encoding(ext_enc, int_enc, opt)  -> io
+  #   - set_encoding(ext_enc)                   -> self
+  #   - set_encoding(ext_enc, int_enc, **enc_opts)  -> self
+  #   - set_encoding('ext_enc:int_enc', **enc_opts) -> self
   # -->
-  # If single argument is specified, read string from io is tagged with the
-  # encoding specified.  If encoding is a colon separated two encoding names
-  # "A:B", the read string is converted from encoding A (external encoding) to
-  # encoding B (internal encoding), then tagged with B.  If two arguments are
-  # specified, those must be encoding objects or encoding names, and the first one
-  # is the external encoding, and the second one is the internal encoding. If the
-  # external encoding and the internal encoding is specified, optional hash
-  # argument specify the conversion option.
+  # See [Encodings](rdoc-ref:File@Encodings).
+  #
+  # Argument `ext_enc`, if given, must be an Encoding object; it is assigned as
+  # the encoding for the stream.
+  #
+  # Argument `int_enc`, if given, must be an Encoding object; it is assigned as
+  # the encoding for the internal string.
+  #
+  # Argument `'ext_enc:int_enc'`, if given, is a string containing two
+  # colon-separated encoding names; corresponding Encoding objects are assigned as
+  # the external and internal encodings for the stream.
+  #
+  # Optional keyword arguments `enc_opts` specify [Encoding
+  # options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
   def set_encoding: (?String | Encoding ext_or_ext_int_enc) -> self
                   | (?String | Encoding ext_or_ext_int_enc, ?String | Encoding int_enc) -> self
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.set_encoding_by_bom   -> encoding or nil
+  #   - set_encoding_by_bom -> encoding or nil
   # -->
-  # Checks if `ios` starts with a BOM, and then consumes it and sets the external
-  # encoding.  Returns the result encoding if found, or nil.  If `ios` is not
-  # binmode or its encoding has been set already, an exception will be raised.
+  # If the stream begins with a BOM ([byte order
+  # marker](https://en.wikipedia.org/wiki/Byte_order_mark)), consumes the BOM and
+  # sets the external encoding accordingly; returns the result encoding if found,
+  # or `nil` otherwise:
+  #
+  #     File.write('t.tmp', "\u{FEFF}abc")
+  #     io = File.open('t.tmp', 'rb')
+  #     io.set_encoding_by_bom # => #<Encoding:UTF-8>
+  #     io.close
   #
-  #     File.write("bom.txt", "\u{FEFF}abc")
-  #     ios = File.open("bom.txt", "rb")
-  #     ios.set_encoding_by_bom    #=>  #<Encoding:UTF-8>
+  #     File.write('t.tmp', 'abc')
+  #     io = File.open('t.tmp', 'rb')
+  #     io.set_encoding_by_bom # => nil
+  #     io.close
   #
-  #     File.write("nobom.txt", "abc")
-  #     ios = File.open("nobom.txt", "rb")
-  #     ios.set_encoding_by_bom    #=>  nil
+  # Raises an exception if the stream is not binmode or its encoding has already
+  # been set.
   #
   def set_encoding_by_bom: () -> Encoding?
 
@@ -1981,6 +2104,7 @@ class IO < Object
   #     f.sync # => false
   #     f.sync = true
   #     f.sync # => true
+  #     f.close
   #
   def sync: () -> bool
 
@@ -2004,6 +2128,7 @@ class IO < Object
   #     f.sync # => false
   #     f.sync = true
   #     f.sync # => true
+  #     f.close
   #
   # Related: IO#fsync.
   #
@@ -2011,46 +2136,41 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.sysread(maxlen[, outbuf])    -> string
+  #   - sysread(maxlen)             -> string
+  #   - sysread(maxlen, out_string) -> string
   # -->
-  # Reads *maxlen* bytes from *ios* using a low-level read and returns them as a
-  # string.  Do not mix with other methods that read from *ios* or you may get
-  # unpredictable results.
+  # Behaves like IO#readpartial, except that it uses low-level system functions.
   #
-  # If the optional *outbuf* argument is present, it must reference a String,
-  # which will receive the data. The *outbuf* will contain only the received data
-  # after the method call even if it is not empty at the beginning.
-  #
-  # Raises SystemCallError on error and EOFError at end of file.
-  #
-  #     f = File.new("testfile")
-  #     f.sysread(16)   #=> "This is line one"
+  # This method should not be used with other stream-reader methods.
   #
   def sysread: (Integer maxlen, String outbuf) -> String
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.sysseek(offset, whence=IO::SEEK_SET)   -> integer
+  #   - sysseek(offset, whence = IO::SEEK_SET) -> integer
   # -->
-  # Seeks to a given *offset* in the stream according to the value of *whence*
-  # (see IO#seek for values of *whence*). Returns the new offset into the file.
+  # Behaves like IO#seek, except that it:
   #
-  #     f = File.new("testfile")
-  #     f.sysseek(-13, IO::SEEK_END)   #=> 53
-  #     f.sysread(10)                  #=> "And so on."
+  # *   Uses low-level system functions.
+  # *   Returns the new position.
   #
   def sysseek: (Integer amount, ?Integer whence) -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.syswrite(string)   -> integer
+  #   - syswrite(object) -> integer
   # -->
-  # Writes the given string to *ios* using a low-level write. Returns the number
-  # of bytes written. Do not mix with other methods that write to *ios* or you may
-  # get unpredictable results. Raises SystemCallError on error.
+  # Writes the given `object` to self, which must be opened for writing (see
+  # Modes); returns the number bytes written. If `object` is not a string is
+  # converted via method to_s:
+  #
+  #     f = File.new('t.tmp', 'w')
+  #     f.syswrite('foo') # => 3
+  #     f.syswrite(30)    # => 2
+  #     f.syswrite(:foo)  # => 3
+  #     f.close
   #
-  #     f = File.new("out", "w")
-  #     f.syswrite("ABCDEF")   #=> 6
+  # This methods should not be used with other stream-writer methods.
   #
   def syswrite: (_ToS arg0) -> Integer
 
@@ -2059,12 +2179,13 @@ class IO < Object
   #   - tell -> integer
   # -->
   # Returns the current position (in bytes) in `self` (see
-  # [Position](#class-IO-label-Position)):
+  # [Position](rdoc-ref:IO@Position)):
   #
-  #     f = File.new('t.txt')
-  #     f.tell     # => 0
-  #     f.readline # => "This is line one.\n"
-  #     f.tell     # => 19
+  #     f = File.open('t.txt')
+  #     f.tell # => 0
+  #     f.gets # => "First line\n"
+  #     f.tell # => 12
+  #     f.close
   #
   # Related: IO#pos=, IO#seek.
   #
@@ -2072,6 +2193,34 @@ class IO < Object
   #
   def tell: () -> Integer
 
+  # <!--
+  #   rdoc-file=io.c
+  #   - timeout -> duration or nil
+  # -->
+  # Get the internal timeout duration or nil if it was not set.
+  #
+  def timeout: () -> Numeric?
+
+  # <!--
+  #   rdoc-file=io.c
+  #   - timeout = duration -> duration
+  #   - timeout = nil -> nil
+  # -->
+  # Set the internal timeout to the specified duration or nil. The timeout applies
+  # to all blocking operations where possible.
+  #
+  # This affects the following methods (but is not limited to): #gets, #puts,
+  # #read, #write, #wait_readable and #wait_writable. This also affects blocking
+  # socket operations like Socket#accept and Socket#connect.
+  #
+  # Some operations like File#open and IO#close are not affected by the timeout. A
+  # timeout during a write operation may leave the IO in an inconsistent state,
+  # e.g. data was partially written. Generally speaking, a timeout is a last ditch
+  # effort to prevent an application from hanging on slow I/O operations, such as
+  # those that occur during a slowloris attack.
+  #
+  def timeout=: (Numeric?) -> void
+
   # <!--
   #   rdoc-file=io.c
   #   - to_io -> self
@@ -2081,78 +2230,98 @@ class IO < Object
   def to_io: () -> self
 
   # <!-- rdoc-file=io.c -->
-  # Returns `true` if *ios* is associated with a terminal device (tty), `false`
-  # otherwise.
+  # Returns `true` if the stream is associated with a terminal device (tty),
+  # `false` otherwise:
+  #
+  #     f = File.new('t.txt').isatty    #=> false
+  #     f.close
+  #     f = File.new('/dev/tty').isatty #=> true
+  #     f.close
   #
-  #     File.new("testfile").isatty   #=> false
-  #     File.new("/dev/tty").isatty   #=> true
+  # IO#tty? is an alias for IO#isatty.
   #
   def tty?: () -> bool
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.ungetbyte(string)   -> nil
-  #   - ios.ungetbyte(integer)  -> nil
+  #   - ungetbyte(integer) -> nil
+  #   - ungetbyte(string)  -> nil
   # -->
-  # Pushes back bytes (passed as a parameter) onto *ios*, such that a subsequent
-  # buffered read will return it. It is only guaranteed to support a single byte,
-  # and only if ungetbyte or ungetc has not already been called on *ios* since the
-  # previous read of at least a single byte from *ios*. However, it can support
-  # additional bytes if there is space in the internal buffer to allow for it.
+  # Pushes back ("unshifts") the given data onto the stream's buffer, placing the
+  # data so that it is next to be read; returns `nil`. See [Byte
+  # IO](rdoc-ref:IO@Byte+IO).
   #
-  #     f = File.new("testfile")   #=> #<File:testfile>
-  #     b = f.getbyte              #=> 0x38
-  #     f.ungetbyte(b)             #=> nil
-  #     f.getbyte                  #=> 0x38
+  # Note that:
   #
-  # If given an integer, only uses the lower 8 bits of the integer as the byte to
-  # push.
+  # *   Calling the method has no effect with unbuffered reads (such as
+  #     IO#sysread).
+  # *   Calling #rewind on the stream discards the pushed-back data.
   #
-  #     f = File.new("testfile")   #=> #<File:testfile>
-  #     f.ungetbyte(0x102)         #=> nil
-  #     f.getbyte                  #=> 0x2
   #
-  # Calling this method prepends to the existing buffer, even if the method has
-  # already been called previously:
+  # When argument `integer` is given, uses only its low-order byte:
   #
-  #     f = File.new("testfile")   #=> #<File:testfile>
-  #     f.ungetbyte("ab")          #=> nil
-  #     f.ungetbyte("cd")          #=> nil
-  #     f.read(5)                  #=> "cdab8"
+  #     File.write('t.tmp', '012')
+  #     f = File.open('t.tmp')
+  #     f.ungetbyte(0x41)   # => nil
+  #     f.read              # => "A012"
+  #     f.rewind
+  #     f.ungetbyte(0x4243) # => nil
+  #     f.read              # => "C012"
+  #     f.close
   #
-  # Has no effect with unbuffered reads (such as IO#sysread).
+  # When argument `string` is given, uses all bytes:
+  #
+  #     File.write('t.tmp', '012')
+  #     f = File.open('t.tmp')
+  #     f.ungetbyte('A')    # => nil
+  #     f.read              # => "A012"
+  #     f.rewind
+  #     f.ungetbyte('BCDE') # => nil
+  #     f.read              # => "BCDE012"
+  #     f.close
   #
   def ungetbyte: (String | Integer arg0) -> NilClass
 
   # <!--
   #   rdoc-file=io.c
-  #   - ios.ungetc(integer)  -> nil
-  #   - ios.ungetc(string)   -> nil
+  #   - ungetc(integer) -> nil
+  #   - ungetc(string)  -> nil
   # -->
-  # Pushes back characters (passed as a parameter) onto *ios*, such that a
-  # subsequent buffered read will return it. It is only guaranteed to support a
-  # single byte, and only if ungetbyte or ungetc has not already been called on
-  # *ios* since the previous read of at least a single byte from *ios*. However,
-  # it can support additional bytes if there is space in the internal buffer to
-  # allow for it.
+  # Pushes back ("unshifts") the given data onto the stream's buffer, placing the
+  # data so that it is next to be read; returns `nil`. See [Character
+  # IO](rdoc-ref:IO@Character+IO).
+  #
+  # Note that:
   #
-  #     f = File.new("testfile")   #=> #<File:testfile>
-  #     c = f.getc                 #=> "8"
-  #     f.ungetc(c)                #=> nil
-  #     f.getc                     #=> "8"
+  # *   Calling the method has no effect with unbuffered reads (such as
+  #     IO#sysread).
+  # *   Calling #rewind on the stream discards the pushed-back data.
   #
-  # If given an integer, the integer must represent a valid codepoint in the
-  # external encoding of *ios*.
   #
-  # Calling this method prepends to the existing buffer, even if the method has
-  # already been called previously:
+  # When argument `integer` is given, interprets the integer as a character:
+  #
+  #     File.write('t.tmp', '012')
+  #     f = File.open('t.tmp')
+  #     f.ungetc(0x41)     # => nil
+  #     f.read             # => "A012"
+  #     f.rewind
+  #     f.ungetc(0x0442)   # => nil
+  #     f.getc.ord         # => 1090
+  #     f.close
   #
-  #     f = File.new("testfile")   #=> #<File:testfile>
-  #     f.ungetc("ab")             #=> nil
-  #     f.ungetc("cd")             #=> nil
-  #     f.read(5)                  #=> "cdab8"
+  # When argument `string` is given, uses all characters:
   #
-  # Has no effect with unbuffered reads (such as IO#sysread).
+  #     File.write('t.tmp', '012')
+  #     f = File.open('t.tmp')
+  #     f.ungetc('A')      # => nil
+  #     f.read      # => "A012"
+  #     f.rewind
+  #     f.ungetc("\u0442\u0435\u0441\u0442") # => nil
+  #     f.getc.ord      # => 1090
+  #     f.getc.ord      # => 1077
+  #     f.getc.ord      # => 1089
+  #     f.getc.ord      # => 1090
+  #     f.close
   #
   def ungetc: (String arg0) -> NilClass
 
@@ -2161,8 +2330,9 @@ class IO < Object
   #   - write(*objects) -> integer
   # -->
   # Writes each of the given `objects` to `self`, which must be opened for writing
-  # (see [Modes](#class-IO-label-Modes)); returns the total number bytes written;
-  # each of `objects` that is not a string is converted via method `to_s`:
+  # (see [Access Modes](rdoc-ref:File@Access+Modes)); returns the total number
+  # bytes written; each of `objects` that is not a string is converted via method
+  # `to_s`:
   #
   #     $stdout.write('Hello', ', ', 'World!', "\n") # => 14
   #     $stdout.write('foo', :bar, 2, "\n")          # => 8
@@ -2172,6 +2342,8 @@ class IO < Object
   #     Hello, World!
   #     foobar2
   #
+  # Related: IO#read.
+  #
   def write: (*_ToS string) -> Integer
 
   # <!--
@@ -2233,145 +2405,237 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.binread(name, [length [, offset]])   -> string
-  #   - File.binread(name, [length [, offset]]) -> string
+  #   - IO.binread(command, length = nil, offset = 0) -> string or nil
+  #   - IO.binread(path, length = nil, offset = 0)    -> string or nil
   # -->
-  # Opens the file, optionally seeks to the given *offset*, then returns *length*
-  # bytes (defaulting to the rest of the file). #binread ensures the file is
-  # closed before returning.  The open mode would be `"rb:ASCII-8BIT"`.
+  # Behaves like IO.read, except that the stream is opened in binary mode with
+  # ASCII-8BIT encoding.
   #
-  # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
-  # class, a subprocess is created in the same way as Kernel#open, and its output
-  # is returned. Consider to use File.binread to disable the behavior of
-  # subprocess invocation.
-  #
-  #     File.binread("testfile")           #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
-  #     File.binread("testfile", 20)       #=> "This is line one\nThi"
-  #     File.binread("testfile", 20, 10)   #=> "ne one\nThis is line "
-  #     IO.binread("| cat testfile")       #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
-  #
-  # See also IO.read for details about `name` and open_args.
+  # When called from class IO (but not subclasses of IO), this method has
+  # potential security vulnerabilities if called with untrusted input; see
+  # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   def self.binread: (String name, ?Integer length, ?Integer offset) -> String
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.binwrite(name, string, [offset])               -> integer
-  #   - IO.binwrite(name, string, [offset], open_args)    -> integer
-  #   - File.binwrite(name, string, [offset])             -> integer
-  #   - File.binwrite(name, string, [offset], open_args)  -> integer
+  #   - IO.binwrite(command, string, offset = 0) -> integer
+  #   - IO.binwrite(path, string, offset = 0)    -> integer
   # -->
-  # Same as IO.write except opening the file in binary mode and ASCII-8BIT
-  # encoding (`"wb:ASCII-8BIT"`).
+  # Behaves like IO.write, except that the stream is opened in binary mode with
+  # ASCII-8BIT encoding.
   #
-  # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
-  # class, a subprocess is created in the same way as Kernel#open, and its output
-  # is returned. Consider to use File.binwrite to disable the behavior of
-  # subprocess invocation.
-  #
-  # See also IO.read for details about `name` and open_args.
+  # When called from class IO (but not subclasses of IO), this method has
+  # potential security vulnerabilities if called with untrusted input; see
+  # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   def self.binwrite: (String name, _ToS string, ?Integer offset, ?mode: String mode) -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.copy_stream(src, dst)
-  #   - IO.copy_stream(src, dst, copy_length)
-  #   - IO.copy_stream(src, dst, copy_length, src_offset)
+  #   - IO.copy_stream(src, dst, src_length = nil, src_offset = 0) -> integer
   # -->
-  # IO.copy_stream copies *src* to *dst*. *src* and *dst* is either a filename or
-  # an IO-like object. IO-like object for *src* should have #readpartial or #read
-  # method.  IO-like object for *dst* should have #write method. (Specialized
-  # mechanisms, such as sendfile system call, may be used on appropriate
-  # situation.)
+  # Copies from the given `src` to the given `dst`, returning the number of bytes
+  # copied.
+  #
+  # *   The given `src` must be one of the following:
+  #
+  #     *   The path to a readable file, from which source data is to be read.
+  #     *   An IO-like object, opened for reading and capable of responding to
+  #         method `:readpartial` or method `:read`.
+  #
+  #
+  # *   The given `dst` must be one of the following:
+  #
+  #     *   The path to a writable file, to which data is to be written.
+  #     *   An IO-like object, opened for writing and capable of responding to
+  #         method `:write`.
   #
-  # This method returns the number of bytes copied.
   #
-  # If optional arguments are not given, the start position of the copy is the
-  # beginning of the filename or the current file offset of the IO. The end
-  # position of the copy is the end of file.
   #
-  # If *copy_length* is given, No more than *copy_length* bytes are copied.
+  # The examples here use file `t.txt` as source:
   #
-  # If *src_offset* is given, it specifies the start position of the copy.
+  #     File.read('t.txt')
+  #     # => "First line\nSecond line\n\nThird line\nFourth line\n"
+  #     File.read('t.txt').size # => 47
   #
-  # When *src_offset* is specified and *src* is an IO, IO.copy_stream doesn't move
-  # the current file offset.
+  # If only arguments `src` and `dst` are given, the entire source stream is
+  # copied:
+  #
+  #     # Paths.
+  #     IO.copy_stream('t.txt', 't.tmp')  # => 47
+  #
+  #     # IOs (recall that a File is also an IO).
+  #     src_io = File.open('t.txt', 'r') # => #<File:t.txt>
+  #     dst_io = File.open('t.tmp', 'w') # => #<File:t.tmp>
+  #     IO.copy_stream(src_io, dst_io)   # => 47
+  #     src_io.close
+  #     dst_io.close
+  #
+  # With argument `src_length` a non-negative integer, no more than that many
+  # bytes are copied:
+  #
+  #     IO.copy_stream('t.txt', 't.tmp', 10) # => 10
+  #     File.read('t.tmp')                   # => "First line"
+  #
+  # With argument `src_offset` also given, the source stream is read beginning at
+  # that offset:
+  #
+  #     IO.copy_stream('t.txt', 't.tmp', 11, 11) # => 11
+  #     IO.read('t.tmp')                         # => "Second line"
   #
   def self.copy_stream: (String | _Reader | _ReaderPartial src, String | _Writer dst, ?Integer copy_length, ?Integer src_offset) -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.popen([env,] cmd, mode="r" [, opt])               -> io
-  #   - IO.popen([env,] cmd, mode="r" [, opt]) {|io| block } -> obj
+  #   - IO.popen(env = {}, cmd, mode = 'r', **opts) -> io
+  #   - IO.popen(env = {}, cmd, mode = 'r', **opts) {|io| ... } -> object
   # -->
-  # Runs the specified command as a subprocess; the subprocess's standard input
-  # and output will be connected to the returned IO object.
+  # Executes the given command `cmd` as a subprocess whose $stdin and $stdout are
+  # connected to a new stream `io`.
   #
-  # The PID of the started process can be obtained by IO#pid method.
+  # This method has potential security vulnerabilities if called with untrusted
+  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # *cmd* is a string or an array as follows.
+  # If no block is given, returns the new stream, which depending on given `mode`
+  # may be open for reading, writing, or both. The stream should be explicitly
+  # closed (eventually) to avoid resource leaks.
   #
-  #     cmd:
-  #       "-"                                      : fork
-  #       commandline                              : command line string which is passed to a shell
-  #       [env, cmdname, arg1, ..., opts]          : command name and zero or more arguments (no shell)
-  #       [env, [cmdname, argv0], arg1, ..., opts] : command name, argv[0] and zero or more arguments (no shell)
-  #     (env and opts are optional.)
+  # If a block is given, the stream is passed to the block (again, open for
+  # reading, writing, or both); when the block exits, the stream is closed, and
+  # the block's value is assigned to global variable `$?` and returned.
   #
-  # If *cmd* is a `String` ```-`'', then a new instance of Ruby is started as the
-  # subprocess.
+  # Optional argument `mode` may be any valid IO mode. See [Access
+  # Modes](rdoc-ref:File@Access+Modes).
   #
-  # If *cmd* is an `Array` of `String`, then it will be used as the subprocess's
-  # `argv` bypassing a shell. The array can contain a hash at first for
-  # environments and a hash at last for options similar to #spawn.
+  # Required argument `cmd` determines which of the following occurs:
   #
-  # The default mode for the new file object is ``r'', but *mode* may be set to
-  # any of the modes listed in the description for class IO. The last argument
-  # *opt* qualifies *mode*.
+  # *   The process forks.
+  # *   A specified program runs in a shell.
+  # *   A specified program runs with specified arguments.
+  # *   A specified program runs with specified arguments and a specified `argv0`.
   #
-  #     # set IO encoding
-  #     IO.popen("nkf -e filename", :external_encoding=>"EUC-JP") {|nkf_io|
-  #       euc_jp_string = nkf_io.read
-  #     }
   #
-  #     # merge standard output and standard error using
-  #     # spawn option.  See the document of Kernel.spawn.
-  #     IO.popen(["ls", "/", :err=>[:child, :out]]) {|ls_io|
-  #       ls_result_with_error = ls_io.read
-  #     }
+  # Each of these is detailed below.
   #
-  #     # spawn options can be mixed with IO options
-  #     IO.popen(["ls", "/"], :err=>[:child, :out]) {|ls_io|
-  #       ls_result_with_error = ls_io.read
-  #     }
+  # The optional hash argument `env` specifies name/value pairs that are to be
+  # added to the environment variables for the subprocess:
   #
-  # Raises exceptions which IO.pipe and Kernel.spawn raise.
+  #     IO.popen({'FOO' => 'bar'}, 'ruby', 'r+') do |pipe|
+  #       pipe.puts 'puts ENV["FOO"]'
+  #       pipe.close_write
+  #       pipe.gets
+  #     end => "bar\n"
   #
-  # If a block is given, Ruby will run the command as a child connected to Ruby
-  # with a pipe. Ruby's end of the pipe will be passed as a parameter to the
-  # block. At the end of block, Ruby closes the pipe and sets `$?`. In this case
-  # IO.popen returns the value of the block.
+  # Optional keyword arguments `opts` specify:
   #
-  # If a block is given with a *cmd* of ```-`'', the block will be run in two
-  # separate processes: once in the parent, and once in a child. The parent
-  # process will be passed the pipe object as a parameter to the block, the child
-  # version of the block will be passed `nil`, and the child's standard in and
-  # standard out will be connected to the parent through the pipe. Not available
-  # on all platforms.
+  # *   [Open options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
+  # *   Options for Kernel#spawn.
   #
-  #     f = IO.popen("uname")
-  #     p f.readlines
-  #     f.close
-  #     puts "Parent is #{Process.pid}"
-  #     IO.popen("date") {|f| puts f.gets }
-  #     IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
-  #     p $?
-  #     IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
-  #       f.puts "bar"; f.close_write; puts f.gets
+  #
+  # **Forked \Process**
+  #
+  # When argument `cmd` is the 1-character string `'-'`, causes the process to
+  # fork:
+  #     IO.popen('-') do |pipe|
+  #       if pipe
+  #         $stderr.puts "In parent, child pid is #{pipe.pid}\n"
+  #       else
+  #         $stderr.puts "In child, pid is #{$$}\n"
+  #       end
+  #     end
+  #
+  # Output:
+  #
+  #     In parent, child pid is 26253
+  #     In child, pid is 26253
+  #
+  # Note that this is not supported on all platforms.
+  #
+  # **Shell Subprocess**
+  #
+  # When argument `cmd` is a single string (but not `'-'`), the program named
+  # `cmd` is run as a shell command:
+  #
+  #     IO.popen('uname') do |pipe|
+  #       pipe.readlines
+  #     end
+  #
+  # Output:
+  #
+  #     ["Linux\n"]
+  #
+  # Another example:
+  #
+  #     IO.popen('/bin/sh', 'r+') do |pipe|
+  #       pipe.puts('ls')
+  #       pipe.close_write
+  #       $stderr.puts pipe.readlines.size
+  #     end
+  #
+  # Output:
+  #
+  #     213
+  #
+  # **Program Subprocess**
+  #
+  # When argument `cmd` is an array of strings, the program named `cmd[0]` is run
+  # with all elements of `cmd` as its arguments:
+  #
+  #     IO.popen(['du', '..', '.']) do |pipe|
+  #       $stderr.puts pipe.readlines.size
+  #     end
+  #
+  # Output:
+  #
+  #     1111
+  #
+  # **Program Subprocess with `argv0`**
+  #
+  # When argument `cmd` is an array whose first element is a 2-element string
+  # array and whose remaining elements (if any) are strings:
+  #
+  # *   `cmd[0][0]` (the first string in the nested array) is the name of a
+  #     program that is run.
+  # *   `cmd[0][1]` (the second string in the nested array) is set as the
+  #     program's `argv[0]`.
+  # *   `cmd[1..-1]` (the strings in the outer array) are the program's arguments.
+  #
+  #
+  # Example (sets `$0` to 'foo'):
+  #
+  #     IO.popen([['/bin/sh', 'foo'], '-c', 'echo $0']).read # => "foo\n"
+  #
+  # **Some Special Examples**
+  #
+  #     # Set IO encoding.
+  #     IO.popen("nkf -e filename", :external_encoding=>"EUC-JP") {|nkf_io|
+  #       euc_jp_string = nkf_io.read
   #     }
   #
-  # *produces:*
+  #     # Merge standard output and standard error using Kernel#spawn option. See Kernel#spawn.
+  #     IO.popen(["ls", "/", :err=>[:child, :out]]) do |io|
+  #       ls_result_with_error = io.read
+  #     end
+  #
+  #     # Use mixture of spawn options and IO options.
+  #     IO.popen(["ls", "/"], :err=>[:child, :out]) do |io|
+  #       ls_result_with_error = io.read
+  #     end
+  #
+  #      f = IO.popen("uname")
+  #      p f.readlines
+  #      f.close
+  #      puts "Parent is #{Process.pid}"
+  #      IO.popen("date") {|f| puts f.gets }
+  #      IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
+  #      p $?
+  #      IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
+  #        f.puts "bar"; f.close_write; puts f.gets
+  #      }
+  #
+  # Output (from last section):
   #
   #     ["Linux\n"]
   #     Parent is 21346
@@ -2381,79 +2645,162 @@ class IO < Object
   #     #<Process::Status: pid 21352 exit 0>
   #     <foo>bar;zot;
   #
+  # Raises exceptions that IO.pipe and Kernel.spawn raise.
+  #
   def self.popen: (*untyped args) -> untyped
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block }     -> nil
-  #   - IO.foreach(name, limit [, getline_args, open_args]) {|line| block }      -> nil
-  #   - IO.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil
-  #   - IO.foreach(...)                                            -> an_enumerator
-  #   - File.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block }     -> nil
-  #   - File.foreach(name, limit [, getline_args, open_args]) {|line| block }      -> nil
-  #   - File.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil
-  #   - File.foreach(...)                                            -> an_enumerator
+  #   - IO.foreach(path, sep = $/, **opts) {|line| block }       -> nil
+  #   - IO.foreach(path, limit, **opts) {|line| block }          -> nil
+  #   - IO.foreach(path, sep, limit, **opts) {|line| block }     -> nil
+  #   - IO.foreach(command, sep = $/, **opts) {|line| block }    -> nil
+  #   - IO.foreach(command, limit, **opts) {|line| block }       -> nil
+  #   - IO.foreach(command, sep, limit, **opts) {|line| block }  -> nil
+  #   - IO.foreach(...)                                          -> an_enumerator
   # -->
-  # Executes the block for every line in the named I/O port, where lines are
-  # separated by *sep*.
+  # Calls the block with each successive line read from the stream.
   #
-  # If no block is given, an enumerator is returned instead.
+  # When called from class IO (but not subclasses of IO), this method has
+  # potential security vulnerabilities if called with untrusted input; see
+  # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
-  # class, a subprocess is created in the same way as Kernel#open, and its output
-  # is returned. Consider to use File.foreach to disable the behavior of
-  # subprocess invocation.
+  # The first argument must be a string that is one of the following:
   #
-  #     File.foreach("testfile") {|x| print "GOT ", x }
-  #     IO.foreach("| cat testfile") {|x| print "GOT ", x }
+  # *   Path: if `self` is a subclass of IO (File, for example), or if the string
+  #     *does* *not* start with the pipe character (`'|'`), the string is the path
+  #     to a file.
+  # *   Command: if `self` is the class IO, and if the string starts with the pipe
+  #     character, the rest of the string is a command to be executed as a
+  #     subprocess. This usage has potential security vulnerabilities if called
+  #     with untrusted input; see [Command
+  #     Injection](rdoc-ref:command_injection.rdoc).
   #
-  # *produces:*
   #
-  #     GOT This is line one
-  #     GOT This is line two
-  #     GOT This is line three
-  #     GOT And so on...
+  # With only argument `path` given, parses lines from the file at the given
+  # `path`, as determined by the default line separator, and calls the block with
+  # each successive line:
+  #
+  #     File.foreach('t.txt') {|line| p line }
+  #
+  # Output: the same as above.
+  #
+  # For both forms, command and path, the remaining arguments are the same.
+  #
+  # With argument `sep` given, parses lines as determined by that line separator
+  # (see [Line Separator](rdoc-ref:IO@Line+Separator)):
+  #
+  #     File.foreach('t.txt', 'li') {|line| p line }
+  #
+  # Output:
+  #
+  #     "First li"
+  #     "ne\nSecond li"
+  #     "ne\n\nThird li"
+  #     "ne\nFourth li"
+  #     "ne\n"
+  #
+  # Each paragraph:
+  #
+  #     File.foreach('t.txt', '') {|paragraph| p paragraph }
+  #
+  # Output:
+  #
+  #     "First line\nSecond line\n\n"
+  #     "Third line\nFourth line\n"
+  #
+  # With argument `limit` given, parses lines as determined by the default line
+  # separator and the given line-length limit (see [Line
+  # Limit](rdoc-ref:IO@Line+Limit)):
+  #
+  #     File.foreach('t.txt', 7) {|line| p line }
+  #
+  # Output:
+  #
+  #     "First l"
+  #     "ine\n"
+  #     "Second "
+  #     "line\n"
+  #     "\n"
+  #     "Third l"
+  #     "ine\n"
+  #     "Fourth l"
+  #     "line\n"
+  #
+  # With arguments `sep` and  `limit` given, parses lines as determined by the
+  # given line separator and the given line-length limit (see [Line Separator and
+  # Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)):
+  #
+  # Optional keyword arguments `opts` specify:
+  #
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
+  # *   [Line Options](rdoc-ref:IO@Line+Options).
   #
-  # If the last argument is a hash, it's the keyword argument to open. See
-  # IO.readlines for details about getline_args. And see also IO.read for details
-  # about open_args.
+  #
+  # Returns an Enumerator if no block is given.
   #
   def self.foreach: (string | _ToPath path, ?String sep, ?Integer limit, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode, ?chomp: boolish) { (String line) -> void } -> nil
                   | (string | _ToPath path, ?String sep, ?Integer limit, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode, ?chomp: boolish) -> ::Enumerator[String, nil]
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.pipe                             ->  [read_io, write_io]
-  #   - IO.pipe(ext_enc)                    ->  [read_io, write_io]
-  #   - IO.pipe("ext_enc:int_enc" [, opt])  ->  [read_io, write_io]
-  #   - IO.pipe(ext_enc, int_enc [, opt])   ->  [read_io, write_io]
-  #   - IO.pipe(...) {|read_io, write_io| ... }
+  #   - IO.pipe(**opts) -> [read_io, write_io]
+  #   - IO.pipe(enc, **opts) -> [read_io, write_io]
+  #   - IO.pipe(ext_enc, int_enc, **opts) -> [read_io, write_io]
+  #   - IO.pipe(**opts) {|read_io, write_io] ...} -> object
+  #   - IO.pipe(enc, **opts) {|read_io, write_io] ...} -> object
+  #   - IO.pipe(ext_enc, int_enc, **opts) {|read_io, write_io] ...} -> object
   # -->
-  # Creates a pair of pipe endpoints (connected to each other) and returns them as
-  # a two-element array of IO objects: `[` *read_io*, *write_io* `]`.
+  # Creates a pair of pipe endpoints, `read_io` and `write_io`, connected to each
+  # other.
   #
-  # If a block is given, the block is called and returns the value of the block.
-  # *read_io* and *write_io* are sent to the block as arguments. If read_io and
-  # write_io are not closed when the block exits, they are closed. i.e. closing
-  # read_io and/or write_io doesn't cause an error.
+  # If argument `enc_string` is given, it must be a string containing one of:
   #
-  # Not available on all platforms.
+  # *   The name of the encoding to be used as the external encoding.
+  # *   The colon-separated names of two encodings to be used as the external and
+  #     internal encodings.
+  #
+  #
+  # If argument `int_enc` is given, it must be an Encoding object or encoding name
+  # string that specifies the internal encoding to be used; if argument `ext_enc`
+  # is also given, it must be an Encoding object or encoding name string that
+  # specifies the external encoding to be used.
+  #
+  # The string read from `read_io` is tagged with the external encoding; if an
+  # internal encoding is also specified, the string is converted to, and tagged
+  # with, that encoding.
+  #
+  # If any encoding is specified, optional hash arguments specify the conversion
+  # option.
+  #
+  # Optional keyword arguments `opts` specify:
+  #
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding Options](rdoc-ref:encodings.rdoc@Encoding+Options).
+  #
+  #
+  # With no block given, returns the two endpoints in an array:
+  #
+  #     IO.pipe # => [#<IO:fd 4>, #<IO:fd 5>]
+  #
+  # With a block given, calls the block with the two endpoints; closes both
+  # endpoints and returns the value of the block:
+  #
+  #     IO.pipe {|read_io, write_io| p read_io; p write_io }
+  #
+  # Output:
+  #
+  #     #<IO:fd 6>
+  #     #<IO:fd 7>
   #
-  # If an encoding (encoding name or encoding object) is specified as an optional
-  # argument, read string from pipe is tagged with the encoding specified. If the
-  # argument is a colon separated two encoding names "A:B", the read string is
-  # converted from encoding A (external encoding) to encoding B (internal
-  # encoding), then tagged with B. If two optional arguments are specified, those
-  # must be encoding objects or encoding names, and the first one is the external
-  # encoding, and the second one is the internal encoding. If the external
-  # encoding and the internal encoding is specified, optional hash argument
-  # specify the conversion option.
+  # Not available on all platforms.
   #
   # In the example below, the two processes close the ends of the pipe that they
   # are not using. This is not just a cosmetic nicety. The read end of a pipe will
   # not generate an end of file condition if there are any writers with the pipe
   # still open. In the case of the parent process, the `rd.read` will never return
-  # if it does not first issue a `wr.close`.
+  # if it does not first issue a `wr.close`:
   #
   #     rd, wr = IO.pipe
   #
@@ -2464,7 +2811,7 @@ class IO < Object
   #       Process.wait
   #     else
   #       rd.close
-  #       puts "Sending message to parent"
+  #       puts 'Sending message to parent'
   #       wr.write "Hi Dad"
   #       wr.close
   #     end
@@ -2479,113 +2826,168 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.read(name, [length [, offset]] [, opt])   -> string
-  #   - File.read(name, [length [, offset]] [, opt]) -> string
+  #   - IO.read(command, length = nil, offset = 0, **opts) -> string or nil
+  #   - IO.read(path, length = nil, offset = 0, **opts)    -> string or nil
   # -->
-  # Opens the file, optionally seeks to the given `offset`, then returns `length`
-  # bytes (defaulting to the rest of the file).  #read ensures the file is closed
-  # before returning.
+  # Opens the stream, reads and returns some or all of its content, and closes the
+  # stream; returns `nil` if no bytes were read.
   #
-  # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
-  # class, a subprocess is created in the same way as Kernel#open, and its output
-  # is returned. Consider to use File.read to disable the behavior of subprocess
-  # invocation.
+  # When called from class IO (but not subclasses of IO), this method has
+  # potential security vulnerabilities if called with untrusted input; see
+  # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # ### Options
+  # The first argument must be a string; its meaning depends on whether it starts
+  # with the pipe character (`'|'`):
   #
-  # The options hash accepts the following keys:
+  # *   If so (and if `self` is IO), the rest of the string is a command to be
+  #     executed as a subprocess.
+  # *   Otherwise, the string is the path to a file.
   #
-  # :encoding
-  # :   string or encoding
   #
-  #     Specifies the encoding of the read string.  `:encoding` will be ignored if
-  #     `length` is specified.  See Encoding.aliases for possible encodings.
+  # With only argument `command` given, executes the command in a shell, returns
+  # its entire $stdout:
   #
-  # :mode
-  # :   string or integer
+  #     IO.read('| cat t.txt')
+  #     # => "First line\nSecond line\n\nThird line\nFourth line\n"
   #
-  #     Specifies the *mode* argument for open().  It must start with an "r",
-  #     otherwise it will cause an error. See IO.new for the list of possible
-  #     modes.
+  # With only argument `path` given, reads in text mode and returns the entire
+  # content of the file at the given path:
   #
-  # :open_args
-  # :   array
+  #     IO.read('t.txt')
+  #     # => "First line\nSecond line\n\nThird line\nFourth line\n"
   #
-  #     Specifies arguments for open() as an array.  This key can not be used in
-  #     combination with either `:encoding` or `:mode`.
+  # On Windows, text mode can terminate reading and leave bytes in the file unread
+  # when encountering certain special bytes. Consider using IO.binread if all
+  # bytes in the file should be read.
   #
+  # For both forms, command and path, the remaining arguments are the same.
   #
-  # Examples:
+  # With argument `length`, returns `length` bytes if available:
+  #
+  #     IO.read('t.txt', 7) # => "First l"
+  #     IO.read('t.txt', 700)
+  #     # => "First line\r\nSecond line\r\n\r\nFourth line\r\nFifth line\r\n"
+  #
+  # With arguments `length` and `offset`, returns `length` bytes if available,
+  # beginning at the given `offset`:
   #
-  #     File.read("testfile")            #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
-  #     File.read("testfile", 20)        #=> "This is line one\nThi"
-  #     File.read("testfile", 20, 10)    #=> "ne one\nThis is line "
-  #     File.read("binfile", mode: "rb") #=> "\xF7\x00\x00\x0E\x12"
-  #     IO.read("|ls -a")                #=> ".\n..\n"...
+  #     IO.read('t.txt', 10, 2)   # => "rst line\nS"
+  #     IO.read('t.txt', 10, 200) # => nil
+  #
+  # Optional keyword arguments `opts` specify:
+  #
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
   def self.read: (String name, ?Integer length, ?Integer offset, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode) -> String
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.readlines(name, sep=$/ [, getline_args, open_args])     -> array
-  #   - IO.readlines(name, limit [, getline_args, open_args])      -> array
-  #   - IO.readlines(name, sep, limit [, getline_args, open_args]) -> array
-  #   - File.readlines(name, sep=$/ [, getline_args, open_args])     -> array
-  #   - File.readlines(name, limit [, getline_args, open_args])      -> array
-  #   - File.readlines(name, sep, limit [, getline_args, open_args]) -> array
+  #   - IO.readlines(command, sep = $/, **opts)     -> array
+  #   - IO.readlines(command, limit, **opts)      -> array
+  #   - IO.readlines(command, sep, limit, **opts) -> array
+  #   - IO.readlines(path, sep = $/, **opts)     -> array
+  #   - IO.readlines(path, limit, **opts)      -> array
+  #   - IO.readlines(path, sep, limit, **opts) -> array
   # -->
-  # Reads the entire file specified by *name* as individual lines, and returns
-  # those lines in an array. Lines are separated by *sep*.
+  # Returns an array of all lines read from the stream.
+  #
+  # When called from class IO (but not subclasses of IO), this method has
+  # potential security vulnerabilities if called with untrusted input; see
+  # [Command Injection](rdoc-ref:command_injection.rdoc).
+  #
+  # The first argument must be a string; its meaning depends on whether it starts
+  # with the pipe character (`'|'`):
   #
-  # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
-  # class, a subprocess is created in the same way as Kernel#open, and its output
-  # is returned. Consider to use File.readlines to disable the behavior of
-  # subprocess invocation.
+  # *   If so (and if `self` is IO), the rest of the string is a command to be
+  #     executed as a subprocess.
+  # *   Otherwise, the string is the path to a file.
   #
-  #     a = File.readlines("testfile")
-  #     a[0]   #=> "This is line one\n"
   #
-  #     b = File.readlines("testfile", chomp: true)
-  #     b[0]   #=> "This is line one"
+  # With only argument `command` given, executes the command in a shell, parses
+  # its $stdout into lines, as determined by the default line separator, and
+  # returns those lines in an array:
   #
-  #     IO.readlines("|ls -a")     #=> [".\n", "..\n", ...]
+  #     IO.readlines('| cat t.txt')
+  #     # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
   #
-  # If the last argument is a hash, it's the keyword argument to open.
+  # With only argument `path` given, parses lines from the file at the given
+  # `path`, as determined by the default line separator, and returns those lines
+  # in an array:
   #
-  # ### Options for getline
+  #     IO.readlines('t.txt')
+  #     # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
   #
-  # The options hash accepts the following keys:
+  # For both forms, command and path, the remaining arguments are the same.
   #
-  # :chomp
-  # :   When the optional `chomp` keyword argument has a true value, `\n`, `\r`,
-  #     and `\r\n` will be removed from the end of each line.
+  # With argument `sep` given, parses lines as determined by that line separator
+  # (see [Line Separator](rdoc-ref:IO@Line+Separator)):
   #
+  #     # Ordinary separator.
+  #     IO.readlines('t.txt', 'li')
+  #     # =>["First li", "ne\nSecond li", "ne\n\nThird li", "ne\nFourth li", "ne\n"]
+  #     # Get-paragraphs separator.
+  #     IO.readlines('t.txt', '')
+  #     # => ["First line\nSecond line\n\n", "Third line\nFourth line\n"]
+  #     # Get-all separator.
+  #     IO.readlines('t.txt', nil)
+  #     # => ["First line\nSecond line\n\nThird line\nFourth line\n"]
   #
-  # See also IO.read for details about `name` and open_args.
+  # With argument `limit` given, parses lines as determined by the default line
+  # separator and the given line-length limit (see [Line
+  # Limit](rdoc-ref:IO@Line+Limit)):
+  #
+  #     IO.readlines('t.txt', 7)
+  #     # => ["First l", "ine\n", "Second ", "line\n", "\n", "Third l", "ine\n", "Fourth ", "line\n"]
+  #
+  # With arguments `sep` and  `limit` given, parses lines as determined by the
+  # given line separator and the given line-length limit (see [Line Separator and
+  # Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)):
+  #
+  # Optional keyword arguments `opts` specify:
+  #
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
+  # *   [Line Options](rdoc-ref:IO@Line+Options).
   #
   def self.readlines: (String | _ToPath name, ?String sep, ?Integer limit, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode, ?chomp: boolish) -> ::Array[String]
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil
+  #   - IO.select(read_ios, write_ios = [], error_ios = [], timeout = nil) -> array or nil
   # -->
-  # Calls select(2) system call. It monitors given arrays of IO objects, waits
-  # until one or more of IO objects are ready for reading, are ready for writing,
-  # and have pending exceptions respectively, and returns an array that contains
-  # arrays of those IO objects.  It will return `nil` if optional *timeout* value
-  # is given and no IO object is ready in *timeout* seconds.
+  # Invokes system call [select(2)](https://linux.die.net/man/2/select), which
+  # monitors multiple file descriptors, waiting until one or more of the file
+  # descriptors becomes ready for some class of I/O operation.
+  #
+  # Not implemented on all platforms.
+  #
+  # Each of the arguments `read_ios`, `write_ios`, and `error_ios` is an array of
+  # IO objects.
+  #
+  # Argument `timeout` is an integer timeout interval in seconds.
+  #
+  # The method monitors the IO objects given in all three arrays, waiting for some
+  # to be ready; returns a 3-element array whose elements are:
+  #
+  # *   An array of the objects in `read_ios` that are ready for reading.
+  # *   An array of the objects in `write_ios` that are ready for writing.
+  # *   An array of the objects in `error_ios` have pending exceptions.
+  #
+  #
+  # If no object becomes ready within the given `timeout`, `nil` is returned.
   #
   # IO.select peeks the buffer of IO objects for testing readability. If the IO
   # buffer is not empty, IO.select immediately notifies readability.  This "peek"
   # only happens for IO objects.  It does not happen for IO-like objects such as
   # OpenSSL::SSL::SSLSocket.
   #
-  # The best way to use IO.select is invoking it after nonblocking methods such as
-  # #read_nonblock, #write_nonblock, etc.  The methods raise an exception which is
-  # extended by IO::WaitReadable or IO::WaitWritable.  The modules notify how the
-  # caller should wait with IO.select.  If IO::WaitReadable is raised, the caller
-  # should wait for reading.  If IO::WaitWritable is raised, the caller should
-  # wait for writing.
+  # The best way to use IO.select is invoking it after non-blocking methods such
+  # as #read_nonblock, #write_nonblock, etc.  The methods raise an exception which
+  # is extended by IO::WaitReadable or IO::WaitWritable.  The modules notify how
+  # the caller should wait with IO.select.  If IO::WaitReadable is raised, the
+  # caller should wait for reading.  If IO::WaitWritable is raised, the caller
+  # should wait for writing.
   #
   # So, blocking read (#readpartial) can be emulated using #read_nonblock and
   # IO.select as follows:
@@ -2600,7 +3002,7 @@ class IO < Object
   #       retry
   #     end
   #
-  # Especially, the combination of nonblocking methods and IO.select is preferred
+  # Especially, the combination of non-blocking methods and IO.select is preferred
   # for IO like objects such as OpenSSL::SSL::SSLSocket.  It has #to_io method to
   # return underlying IO object.  IO.select calls #to_io to obtain the file
   # descriptor to wait.
@@ -2626,13 +3028,13 @@ class IO < Object
   # blocking. So, the caller should wait for ready for writability as above
   # example.
   #
-  # The combination of nonblocking methods and IO.select is also useful for
+  # The combination of non-blocking methods and IO.select is also useful for
   # streams such as tty, pipe socket socket when multiple processes read from a
   # stream.
   #
   # Finally, Linux kernel developers don't guarantee that readability of select(2)
-  # means readability of following read(2) even for a single process. See
-  # select(2) manual on GNU/Linux system.
+  # means readability of following read(2) even for a single process; see
+  # [select(2)](https://linux.die.net/man/2/select)
   #
   # Invoking IO.select before IO#readpartial works well as usual. However it is
   # not the best way to use IO.select.
@@ -2659,18 +3061,7 @@ class IO < Object
   #       string = string.byteslice(written..-1)
   #     end
   #
-  # ### Parameters
-  # read_array
-  # :   an array of IO objects that wait until ready for read
-  # write_array
-  # :   an array of IO objects that wait until ready for write
-  # error_array
-  # :   an array of IO objects that wait for exceptions
-  # timeout
-  # :   a numeric value in second
-  #
-  #
-  # ### Example
+  # Example:
   #
   #     rp, wp = IO.pipe
   #     mesg = "ping "
@@ -2692,7 +3083,7 @@ class IO < Object
   #       end
   #     }
   #
-  # *produces:*
+  # Output:
   #
   #     ping pong
   #     ping pong
@@ -2705,11 +3096,17 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.sysopen(path, [mode, [perm]])  -> integer
+  #   - IO.sysopen(path, mode = 'r', perm = 0666) -> integer
   # -->
-  # Opens the given path, returning the underlying file descriptor as a Integer.
+  # Opens the file at the given path with the given mode and permissions; returns
+  # the integer file descriptor.
+  #
+  # If the file is to be readable, it must exist; if the file is to be writable
+  # and does not exist, it is created with the given permissions:
   #
-  #     IO.sysopen("testfile")   #=> 3
+  #     File.write('t.tmp', '')  # => 0
+  #     IO.sysopen('t.tmp')      # => 8
+  #     IO.sysopen('t.tmp', 'w') # => 9
   #
   def self.sysopen: (String path, ?String mode, ?String perm) -> Integer
 
@@ -2728,96 +3125,87 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.write(name, string [, offset])           -> integer
-  #   - IO.write(name, string [, offset] [, opt])   -> integer
-  #   - File.write(name, string [, offset])         -> integer
-  #   - File.write(name, string [, offset] [, opt]) -> integer
+  #   - IO.write(command, data, **opts)             -> integer
+  #   - IO.write(path, data, offset = 0, **opts)    -> integer
   # -->
-  # Opens the file, optionally seeks to the given *offset*, writes *string*, then
-  # returns the length written.  #write ensures the file is closed before
-  # returning.  If *offset* is not given in write mode, the file is truncated.
-  # Otherwise, it is not truncated.
+  # Opens the stream, writes the given `data` to it, and closes the stream;
+  # returns the number of bytes written.
   #
-  # If `name` starts with a pipe character (`"|"`) and the receiver is the IO
-  # class, a subprocess is created in the same way as Kernel#open, and its output
-  # is returned. Consider to use File.write to disable the behavior of subprocess
-  # invocation.
+  # When called from class IO (but not subclasses of IO), this method has
+  # potential security vulnerabilities if called with untrusted input; see
+  # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  #     File.write("testfile", "0123456789", 20)  #=> 10
-  #     # File could contain:  "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"
-  #     File.write("testfile", "0123456789")      #=> 10
-  #     # File would now read: "0123456789"
-  #     IO.write("|tr a-z A-Z", "abc")            #=> 3
-  #     # Prints "ABC" to the standard output
+  # The first argument must be a string; its meaning depends on whether it starts
+  # with the pipe character (`'|'`):
   #
-  # If the last argument is a hash, it specifies options for the internal open().
-  # It accepts the following keys:
+  # *   If so (and if `self` is IO), the rest of the string is a command to be
+  #     executed as a subprocess.
+  # *   Otherwise, the string is the path to a file.
   #
-  # :encoding
-  # :   string or encoding
   #
-  #     Specifies the encoding of the read string. See Encoding.aliases for
-  #     possible encodings.
+  # With argument `command` given, executes the command in a shell, passes `data`
+  # through standard input, writes its output to $stdout, and returns the length
+  # of the given `data`:
   #
-  # :mode
-  # :   string or integer
+  #     IO.write('| cat', 'Hello World!') # => 12
   #
-  #     Specifies the *mode* argument for open().  It must start with "w", "a", or
-  #     "r+", otherwise it will cause an error. See IO.new for the list of
-  #     possible modes.
+  # Output:
+  #
+  #     Hello World!
+  #
+  # With argument `path` given, writes the given `data` to the file at that path:
+  #
+  #     IO.write('t.tmp', 'abc')    # => 3
+  #     File.read('t.tmp')          # => "abc"
   #
-  # :perm
-  # :   integer
+  # If `offset` is zero (the default), the file is overwritten:
   #
-  #     Specifies the *perm* argument for open().
+  #     IO.write('t.tmp', 'A')      # => 1
+  #     File.read('t.tmp')          # => "A"
   #
-  # :open_args
-  # :   array
+  # If `offset` in within the file content, the file is partly overwritten:
   #
-  #     Specifies arguments for open() as an array. This key can not be used in
-  #     combination with other keys.
+  #     IO.write('t.tmp', 'abcdef') # => 3
+  #     File.read('t.tmp')          # => "abcdef"
+  #     # Offset within content.
+  #     IO.write('t.tmp', '012', 2) # => 3
+  #     File.read('t.tmp')          # => "ab012f"
   #
+  # If `offset` is outside the file content, the file is padded with null
+  # characters `"\u0000"`:
   #
-  # See also IO.read for details about `name` and open_args.
+  #     IO.write('t.tmp', 'xyz', 10) # => 3
+  #     File.read('t.tmp')           # => "ab012f\u0000\u0000\u0000\u0000xyz"
+  #
+  # Optional keyword arguments `opts` specify:
+  #
+  # *   [Open Options](rdoc-ref:IO@Open+Options).
+  # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
   def self.write: (String name, _ToS arg0, ?Integer offset, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode) -> Integer
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.for_fd(fd, mode [, opt])    -> io
+  #   - IO.for_fd(fd, mode = 'r', **opts) -> io
   # -->
   # Synonym for IO.new.
   #
-  def self.for_fd: (int fd, ?string | int mode, **untyped opt) -> instance
+  alias self.for_fd self.new
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.open(fd, mode="r" [, opt])                -> io
-  #   - IO.open(fd, mode="r" [, opt]) {|io| block }  -> obj
+  #   - IO.open(fd, mode = 'r', **opts)             -> io
+  #   - IO.open(fd, mode = 'r', **opts) {|io| ... } -> object
   # -->
-  # With no associated block, IO.open is a synonym for IO.new.  If the optional
-  # code block is given, it will be passed `io` as an argument, and the IO object
-  # will automatically be closed when the block terminates. In this instance,
-  # IO.open returns the value of the block.
+  # Creates a new IO object, via IO.new with the given arguments.
   #
-  # See IO.new for a description of the `fd`, `mode` and `opt` parameters.
-  #
-  alias self.open self.for_fd
-
-  # <!--
-  #   rdoc-file=io.c
-  #   - IO.open(fd, mode="r" [, opt])                -> io
-  #   - IO.open(fd, mode="r" [, opt]) {|io| block }  -> obj
-  # -->
-  # With no associated block, IO.open is a synonym for IO.new.  If the optional
-  # code block is given, it will be passed `io` as an argument, and the IO object
-  # will automatically be closed when the block terminates. In this instance,
-  # IO.open returns the value of the block.
+  # With no block given, returns the IO object.
   #
-  # See IO.new for a description of the `fd`, `mode` and `opt` parameters.
+  # With a block given, calls the block with the IO object and returns the block's
+  # value.
   #
-  def self.open: [A] (int fd, ?string | int mode, **untyped opt) { (instance) -> A } -> A
-               | ...
+  def self.open: (int fd, ?string | int mode, ?path: string?, **untyped opts) -> instance
+               | [A] (int fd, ?string | int mode, ?path: string?, **untyped opts) { (instance) -> A } -> A
 
   def bytes: () { (Integer arg0) -> untyped } -> self
            | () -> ::Enumerator[Integer, self]
@@ -2829,37 +3217,118 @@ class IO < Object
                 | () -> ::Enumerator[Integer, self]
 
   # <!-- rdoc-file=io.c -->
-  # Executes the block for every line in *ios*, where lines are separated by
-  # *sep*. *ios* must be opened for reading or an IOError will be raised.
+  # Calls the block with each remaining line read from the stream; returns `self`.
+  # Does nothing if already at end-of-stream; See [Line IO](rdoc-ref:IO@Line+IO).
   #
-  # If no block is given, an enumerator is returned instead.
+  # With no arguments given, reads lines as determined by line separator `$/`:
   #
-  #     f = File.new("testfile")
-  #     f.each {|line| puts "#{f.lineno}: #{line}" }
+  #     f = File.new('t.txt')
+  #     f.each_line {|line| p line }
+  #     f.each_line {|line| fail 'Cannot happen' }
+  #     f.close
   #
-  # *produces:*
+  # Output:
+  #
+  #     "First line\n"
+  #     "Second line\n"
+  #     "\n"
+  #     "Fourth line\n"
+  #     "Fifth line\n"
+  #
+  # With only string argument `sep` given, reads lines as determined by line
+  # separator `sep`; see [Line Separator](rdoc-ref:IO@Line+Separator):
+  #
+  #     f = File.new('t.txt')
+  #     f.each_line('li') {|line| p line }
+  #     f.close
+  #
+  # Output:
   #
-  #     1: This is line one
-  #     2: This is line two
-  #     3: This is line three
-  #     4: And so on...
+  #     "First li"
+  #     "ne\nSecond li"
+  #     "ne\n\nFourth li"
+  #     "ne\nFifth li"
+  #     "ne\n"
   #
-  # See IO.readlines for details about getline_args.
+  # The two special values for `sep` are honored:
+  #
+  #     f = File.new('t.txt')
+  #     # Get all into one string.
+  #     f.each_line(nil) {|line| p line }
+  #     f.close
+  #
+  # Output:
+  #
+  #     "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #
+  #     f.rewind
+  #     # Get paragraphs (up to two line separators).
+  #     f.each_line('') {|line| p line }
+  #
+  # Output:
+  #
+  #     "First line\nSecond line\n\n"
+  #     "Fourth line\nFifth line\n"
+  #
+  # With only integer argument `limit` given, limits the number of bytes in each
+  # line; see [Line Limit](rdoc-ref:IO@Line+Limit):
+  #
+  #     f = File.new('t.txt')
+  #     f.each_line(8) {|line| p line }
+  #     f.close
+  #
+  # Output:
+  #
+  #     "First li"
+  #     "ne\n"
+  #     "Second l"
+  #     "ine\n"
+  #     "\n"
+  #     "Fourth l"
+  #     "ine\n"
+  #     "Fifth li"
+  #     "ne\n"
+  #
+  # With arguments `sep` and `limit` given, combines the two behaviors:
+  #
+  # *   Calls with the next line as determined by line separator `sep`.
+  # *   But returns no more bytes than are allowed by the limit.
+  #
+  #
+  # Optional keyword argument `chomp` specifies whether line separators are to be
+  # omitted:
+  #
+  #     f = File.new('t.txt')
+  #     f.each_line(chomp: true) {|line| p line }
+  #     f.close
+  #
+  # Output:
+  #
+  #     "First line"
+  #     "Second line"
+  #     ""
+  #     "Fourth line"
+  #     "Fifth line"
+  #
+  # Returns an Enumerator if no block is given.
+  #
+  # IO#each is an alias for IO#each_line.
   #
   def each_line: (?String sep, ?Integer limit) { (String arg0) -> untyped } -> self
                | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
 
   # <!-- rdoc-file=io.c -->
   # Returns `true` if the stream is positioned at its end, `false` otherwise; see
-  # [Position](#class-IO-label-Position):
+  # [Position](rdoc-ref:IO@Position):
   #
   #     f = File.open('t.txt')
   #     f.eof           # => false
   #     f.seek(0, :END) # => 0
   #     f.eof           # => true
+  #     f.close
   #
   # Raises an exception unless the stream is opened for reading; see
-  # [Mode](#class-IO-label-Mode).
+  # [Mode](rdoc-ref:File@Access+Modes).
   #
   # If `self` is a stream such as pipe or socket, this method blocks until the
   # other end sends some data or closes it:
@@ -2879,7 +3348,7 @@ class IO < Object
   # not behave as you intend with IO#eof?, unless you call IO#rewind first (which
   # is not available for some streams).
   #
-  # I#eof? is an alias for IO#eof.
+  # IO#eof? is an alias for IO#eof.
   #
   def eof?: () -> bool
 
@@ -2893,6 +3362,7 @@ class IO < Object
   #     $stdout.fileno            # => 1
   #     $stderr.fileno            # => 2
   #     File.open('t.txt').fileno # => 10
+  #     f.close
   #
   # IO#to_i is an alias for IO#fileno.
   #