rbs 3.7.0 → 3.8.0.pre.1

data/core/io.rbs

@@ -21,7 +21,6 @@
 # *   $stderr.
 # *   Instances of class File.
 #
-#
 # An instance of IO may be created using:
 #
 # *   IO.new: returns a new IO object for the given integer file descriptor.
@@ -31,7 +30,6 @@
 # *   Kernel#open: Returns a new IO object connected to a given source: stream,
 #     file, or subprocess.
 #
-#
 # Like a File stream, an IO stream has:
 #
 # *   A read/write mode, which may be read-only, write-only, or read/write; see
@@ -40,7 +38,6 @@
 #     Mode](rdoc-ref:File@Data+Mode).
 # *   Internal and external encodings; see [Encodings](rdoc-ref:File@Encodings).
 #
-#
 # And like other IO streams, it has:
 #
 # *   A position, which determines where in the stream the next read or write is
@@ -49,7 +46,6 @@
 #     from the position mentioned above); see [Line
 #     Number](rdoc-ref:IO@Line+Number).
 #
-#
 # ## Extension `io/console`
 #
 # Extension `io/console` provides numerous methods for interacting with the
@@ -108,7 +104,6 @@
 # *   `: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 and internal encoding.
 #
@@ -122,7 +117,6 @@
 # *   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
 #
 # An IO stream has a nonnegative integer *position*, which is the byte offset at
@@ -130,6 +124,9 @@
 # line number zero); method `rewind` resets the position (and line number) to
 # zero.
 #
+# These methods discard [buffers](rdoc-ref:IO@Buffering) and the
+# Encoding::Converter instances used for that IO.
+#
 # The relevant methods:
 #
 # *   IO#tell (aliased as `#pos`): Returns the current position (in bytes) in
@@ -142,7 +139,6 @@
 # *   IO#rewind: Positions the stream at the beginning (also resetting the line
 #     number).
 #
-#
 # ### Open and Closed Streams
 #
 # A new IO stream may be open for reading, open for writing, or both.
@@ -158,7 +154,6 @@
 # *   IO#close_write: Closes the stream for writing.
 # *   IO#closed?: Returns whether the stream is closed.
 #
-#
 # ### End-of-Stream
 #
 # You can query whether a stream is positioned at its end:
@@ -166,7 +161,6 @@
 # *   IO#eof? (also aliased as `#eof`): Returns whether the stream is at
 #     end-of-stream.
 #
-#
 # You can reposition to end-of-stream by using method IO#seek:
 #
 #     f = File.new('t.txt')
@@ -184,58 +178,62 @@
 #
 # ## Line IO
 #
-# You can read an IO stream line-by-line using these methods:
-#
-# *   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.
+# Class IO supports line-oriented [input](rdoc-ref:IO@Line+Input) and
+# [output](rdoc-ref:IO@Line+Output)
 #
+# ### Line Input
 #
-# Each of these reader methods accepts:
+# Class IO supports line-oriented input for [files](rdoc-ref:IO@File+Line+Input)
+# and [IO streams](rdoc-ref:IO@Stream+Line+Input)
 #
-# *   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).
+# #### File Line Input
 #
+# You can read lines from a file using these methods:
 #
-# For each of these reader methods, reading may begin mid-line, depending on the
-# stream's position; see [Position](rdoc-ref:IO@Position):
+# *   IO.foreach: Reads each line and passes it to the given block.
+# *   IO.readlines: Reads and returns all lines in an array.
 #
-#     f = File.new('t.txt')
-#     f.pos = 27
-#     f.each_line {|line| p line }
-#     f.close
+# For each of these methods:
 #
-# Output:
+# *   You can specify [open options](rdoc-ref:IO@Open+Options).
+# *   Line parsing depends on the effective *line separator*; see [Line
+#     Separator](rdoc-ref:IO@Line+Separator).
+# *   The length of each returned line depends on the effective *line limit*;
+#     see [Line Limit](rdoc-ref:IO@Line+Limit).
 #
-#     "rth line\n"
-#     "Fifth line\n"
+# #### Stream Line Input
 #
-# You can write to an IO stream line-by-line using this method:
+# You can read lines from an IO stream using these methods:
 #
-# *   IO#puts: Writes objects to the stream.
+# *   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.
 #
+# For each of these methods:
 #
-# ### Line Separator
+# *   Reading may begin mid-line, depending on the stream's *position*; see
+#     [Position](rdoc-ref:IO@Position).
+# *   Line parsing depends on the effective *line separator*; see [Line
+#     Separator](rdoc-ref:IO@Line+Separator).
+# *   The length of each returned line depends on the effective *line limit*;
+#     see [Line Limit](rdoc-ref:IO@Line+Limit).
 #
-# Each of these methods uses a *line separator*, which is the string that
-# delimits lines:
+# ##### Line Separator
 #
-# *   IO.foreach.
-# *   IO.readlines.
-# *   IO#each_line.
-# *   IO#gets.
-# *   IO#readline.
-# *   IO#readlines.
+# Each of the [line input methods](rdoc-ref:IO@Line+Input) uses a *line
+# separator*: the string that determines what is considered a line; it is
+# sometimes called the *input record separator*.
 #
+# The default line separator is taken from global variable `$/`, whose initial
+# value is `"\n"`.
 #
-# 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:
+# Generally, the line to be read next is all data from the current
+# [position](rdoc-ref:IO@Position) to the next line separator (but see [Special
+# Line Separator Values](rdoc-ref:IO@Special+Line+Separator+Values)):
 #
 #     f = File.new('t.txt')
+#     # Method gets with no sep argument returns the next line, according to $/.
 #     f.gets # => "First line\n"
 #     f.gets # => "Second line\n"
 #     f.gets # => "\n"
@@ -243,7 +241,7 @@
 #     f.gets # => "Fifth line\n"
 #     f.close
 #
-# You can specify a different line separator:
+# You can use a different line separator by passing argument `sep`:
 #
 #     f = File.new('t.txt')
 #     f.gets('l')   # => "First l"
@@ -252,40 +250,45 @@
 #     f.gets        # => "e\n"
 #     f.close
 #
-# There are two special line separators:
+# Or by setting global variable `$/`:
+#
+#     f = File.new('t.txt')
+#     $/ = 'l'
+#     f.gets # => "First l"
+#     f.gets # => "ine\nSecond l"
+#     f.gets # => "ine\n\nFourth l"
+#     f.close
+#
+# ##### Special Line Separator Values
+#
+# Each of the [line input methods](rdoc-ref:IO@Line+Input) accepts two special
+# values for parameter `sep`:
 #
-# *   `nil`: The entire stream is read into a single string:
+# *   `nil`: The entire stream is to be read ("slurped") into a single string:
 #
 #         f = File.new('t.txt')
 #         f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
 #         f.close
 #
-# *   `''` (the empty string): The next "paragraph" is read (paragraphs being
-#     separated by two consecutive line separators):
+# *   `''` (the empty string): The next "paragraph" is to be read (paragraphs
+#     being separated by two consecutive line separators):
 #
 #         f = File.new('t.txt')
 #         f.gets('') # => "First line\nSecond line\n\n"
 #         f.gets('') # => "Fourth line\nFifth line\n"
 #         f.close
 #
+# ##### Line Limit
 #
-# ### Line Limit
-#
-# 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`;
+# Each of the [line input methods](rdoc-ref:IO@Line+Input) uses an integer *line
+# limit*, which restricts the number of bytes that may be returned. (A
+# multi-byte character will not be split, and so a returned line may be slightly
+# longer than the limit).
 #
-# *   IO.foreach.
-# *   IO.readlines.
-# *   IO#each_line.
-# *   IO#gets.
-# *   IO#readline.
-# *   IO#readlines.
+# The default limit value is `-1`; any negative limit value means that there is
+# no limit.
 #
-#
-# A multi-byte character will not be split, and so a line may be slightly longer
-# than the given limit.
-#
-# If `limit` is not given, the line is determined only by `sep`.
+# If there is no limit, the line is determined only by `sep`.
 #
 #     # Text with 1-byte characters.
 #     File.open('t.txt') {|f| f.gets(1) }  # => "F"
@@ -303,32 +306,28 @@
 #     File.open('t.rus') {|f| f.gets(3).size } # => 2
 #     File.open('t.rus') {|f| f.gets(4).size } # => 2
 #
-# ### Line Separator and Line Limit
+# ##### Line Separator and Line Limit
 #
 # With arguments `sep` and `limit` given, combines the two behaviors:
 #
 # *   Returns the next line as determined by line separator `sep`.
-# *   But returns no more bytes than are allowed by the limit.
-#
+# *   But returns no more bytes than are allowed by the limit `limit`.
 #
 # Example:
 #
 #     File.open('t.txt') {|f| f.gets('li', 20) } # => "First li"
 #     File.open('t.txt') {|f| f.gets('li', 2) }  # => "Fi"
 #
-# ### Line Number
+# ##### Line Number
 #
-# A readable IO stream has a non-negative integer *line number*.
-#
-# The relevant methods:
+# A readable IO stream has a non-negative integer *line number*:
 #
 # *   IO#lineno: Returns the line number.
 # *   IO#lineno=: Resets and returns the line number.
 #
-#
 # 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`:
+# of lines read by certain line-oriented methods, according to the effective
+# [line separator](rdoc-ref:IO@Line+Separator):
 #
 # *   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.
@@ -336,7 +335,6 @@
 # *   IO#readline: Increments the line number.
 # *   IO#readlines: Increments the line number for each line read.
 #
-#
 # A new stream is initially has line number zero (and position zero); method
 # `rewind` resets the line number (and position) to zero:
 #
@@ -419,6 +417,11 @@
 #         $.          # => 5
 #         f.close
 #
+# ### Line Output
+#
+# You can write to an IO stream line-by-line using this method:
+#
+# *   IO#puts: Writes objects to the stream.
 #
 # ## Character IO
 #
@@ -442,7 +445,6 @@
 # *   IO#each_byte: Reads each remaining byte in the stream, passing the byte to
 #     the given block.
 #
-#
 # ## Codepoint IO
 #
 # You can process an IO stream codepoint-by-codepoint:
@@ -450,7 +452,6 @@
 # *   IO#each_codepoint: Reads each remaining codepoint, passing it to the given
 #     block.
 #
-#
 # ## What's Here
 #
 # First, what's elsewhere. Class IO:
@@ -459,7 +460,6 @@
 # *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
 #     provides dozens of additional methods.
 #
-#
 # Here, class IO provides methods that are useful for:
 #
 # *   [Creating](rdoc-ref:IO@Creating)
@@ -473,7 +473,6 @@
 # *   [Low-Level Access](rdoc-ref:IO@Low-Level+Access)
 # *   [Other](rdoc-ref:IO@Other)
 #
-#
 # ### Creating
 #
 # *   ::new (aliased as ::for_fd): Creates and returns a new IO object for the
@@ -484,7 +483,6 @@
 # *   ::select: Selects which given IO instances are ready for reading, writing,
 #     or have pending exceptions.
 #
-#
 # ### Reading
 #
 # *   ::binread: Returns a binary string with all or a subset of bytes from the
@@ -511,7 +509,6 @@
 # *   #readlines: Returns an array of all lines read read from `self`.
 # *   #readpartial: Returns up to the given number of bytes from `self`.
 #
-#
 # ### Writing
 #
 # *   ::binwrite: Writes the given string to the file at the given filepath, in
@@ -528,7 +525,6 @@
 # *   #write_nonblock: Writes one or more given strings to `self` in
 #     non-blocking mode.
 #
-#
 # ### Positioning
 #
 # *   #lineno: Returns the current line number in `self`.
@@ -539,7 +535,6 @@
 # *   #rewind: Positions `self` to the beginning of input.
 # *   #seek: Sets the offset for `self` relative to given position.
 #
-#
 # ### Iterating
 #
 # *   ::foreach: Yields each line of given file to the block.
@@ -552,7 +547,6 @@
 # *   #each_codepoint: Calls the given block with each successive codepoint in
 #     `self` as an integer.
 #
-#
 # ### Settings
 #
 # *   #autoclose=: Sets whether `self` auto-closes.
@@ -566,7 +560,6 @@
 #     byte-order-mark.
 # *   #sync=: Sets the sync-mode to the given value.
 #
-#
 # ### Querying
 #
 # *   #autoclose?: Returns whether `self` auto-closes.
@@ -584,7 +577,6 @@
 # *   #sync: Returns whether `self` is in sync-mode.
 # *   #tty? (aliased as #isatty): Returns whether `self` is a terminal.
 #
-#
 # ### Buffering
 #
 # *   #fdatasync: Immediately writes all buffered data in `self` to disk.
@@ -595,7 +587,6 @@
 # *   #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
@@ -611,7 +602,6 @@
 # *   #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
@@ -660,7 +650,6 @@ class IO < Object
   # *   `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.
   #
-  #
   # Argument `advice` is one of the following symbols:
   #
   # *   `:normal`: The application has no advice to give about its access pattern
@@ -673,7 +662,6 @@ class IO < Object
   # *   `:willneed`: The specified data will be accessed in the near future.
   # *   `:dontneed`: The specified data will not be accessed in the near future.
   #
-  #
   # Not implemented on all platforms.
   #
   def advise: (:normal | :sequential | :random | :willneed | :dontneed | :noreuse advise, ?Integer offset, ?Integer len) -> nil
@@ -739,6 +727,9 @@ class IO < Object
   # If the stream was opened by IO.popen, sets global variable `$?` (child exit
   # status).
   #
+  # It is not an error to close an IO object that has already been closed. It just
+  # returns nil.
+  #
   # Example:
   #
   #     IO.popen('ruby', 'r+') do |pipe|
@@ -1045,7 +1036,6 @@ class IO < Object
   # *   IO#fsync: Ensures both that data is flushed from internal buffers, and
   #     that data is written to disk.
   #
-  #
   # Raises an exception if the operating system does not support `fsync(2)`.
   #
   def fsync: () -> Integer?
@@ -1136,12 +1126,8 @@ class IO < Object
   #     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` given, combines the two behaviors:
-  #
-  # *   Returns the next line as determined by line separator `sep`, or `nil` if
-  #     none.
-  # *   But returns no more bytes than are allowed by the limit.
-  #
+  # With arguments `sep` and `limit` given, combines the two behaviors (see [Line
+  # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)).
   #
   # Optional keyword argument `chomp` specifies whether line separators are to be
   # omitted:
@@ -1193,7 +1179,6 @@ class IO < Object
   # *   [Open Options](rdoc-ref:IO@Open+Options).
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  #
   # Examples:
   #
   #     IO.new(fd, internal_encoding: nil) # => #<IO:fd 3>
@@ -1341,7 +1326,6 @@ class IO < Object
   # *   If not the last object, writes the output field separator
   #     `$OUTPUT_FIELD_SEPARATOR` (`$,`) if it is not `nil`.
   #
-  #
   # With default separators:
   #
   #     f = File.open('t.tmp', 'w+')
@@ -1431,7 +1415,6 @@ class IO < Object
   # *   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)
@@ -1470,7 +1453,6 @@ class IO < Object
   # *   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
   # the bytes read. The encoding of the string depends on both `maxLen` and
   # `out_string`:
@@ -1482,8 +1464,6 @@ class IO < Object
   #     *   `out_string` given: encoding of `out_string` not modified.
   #     *   `out_string` not given: ASCII-8BIT is used.
   #
-  #
-  #
   # **Without Argument `out_string`**
   #
   # When argument `out_string` is omitted, the returned value is a new string:
@@ -1687,11 +1667,8 @@ class IO < Object
   #     # => ["First li", "ne\n", "Second l", "ine\n", "\n", "Fourth l", "ine\n", "Fifth li", "ne\n"]
   #     f.close
   #
-  # With arguments `sep` and `limit` given, combines the two behaviors:
-  #
-  # *   Returns lines as determined by line separator `sep`.
-  # *   But returns no more bytes in a line than are allowed by the limit.
-  #
+  # With arguments `sep` and `limit` given, combines the two behaviors (see [Line
+  # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)).
   #
   # Optional keyword argument `chomp` specifies whether line separators are to be
   # omitted:
@@ -1718,7 +1695,6 @@ class IO < Object
   # *   Otherwise contains all available bytes, if any available.
   # *   Otherwise is an empty string.
   #
-  #
   # With the single non-negative integer argument `maxlen` given, returns a new
   # string:
   #
@@ -1747,20 +1723,17 @@ class IO < Object
   # *   The content of the stream is empty.
   # *   The stream is not at EOF.
   #
-  #
   # When blocked, the method waits for either more data or EOF on the stream:
   #
   # *   If more data is read, the method returns the data.
   # *   If EOF is reached, the method raises EOFError.
   #
-  #
   # When not blocked, the method responds immediately:
   #
   # *   Returns data from the buffer if there is any.
   # *   Otherwise returns data from the stream if there is any.
   # *   Otherwise raises EOFError if the stream has reached EOF.
   #
-  #
   # Note that this method is similar to sysread. The differences are:
   #
   # *   If the byte buffer is not empty, read from the byte buffer instead of
@@ -1769,7 +1742,6 @@ class IO < Object
   #     meets EWOULDBLOCK and EINTR by read system call, readpartial retries the
   #     system call.
   #
-  #
   # The latter means that readpartial is non-blocking-flag insensitive. It blocks
   # on the situation IO#sysread causes Errno::EWOULDBLOCK as if the fd is blocking
   # mode.
@@ -1898,7 +1870,6 @@ class IO < Object
   #         f.tell           # => 40
   #         f.close
   #
-  #
   # Related: IO#pos=, IO#tell.
   #
   def seek: (Integer amount, ?Integer whence) -> Integer
@@ -1997,7 +1968,6 @@ class IO < Object
   #     system and is not buffered internally.
   # *   `false`: Output may be buffered internally.
   #
-  #
   # Example;
   #
   #     f = File.open('t.tmp', 'w')
@@ -2153,7 +2123,6 @@ class IO < Object
   #     IO#sysread).
   # *   Calling #rewind on the stream discards the pushed-back data.
   #
-  #
   # When argument `integer` is given, uses only its low-order byte:
   #
   #     File.write('t.tmp', '012')
@@ -2193,7 +2162,6 @@ class IO < Object
   #     IO#sysread).
   # *   Calling #rewind on the stream discards the pushed-back data.
   #
-  #
   # When argument `integer` is given, interprets the integer as a character:
   #
   #     File.write('t.tmp', '012')
@@ -2338,15 +2306,12 @@ class IO < Object
   #     *   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`.
   #
-  #
-  #
   # The examples here use file `t.txt` as source:
   #
   #     File.read('t.txt')
@@ -2409,7 +2374,6 @@ class IO < Object
   # *   A specified program runs with specified arguments.
   # *   A specified program runs with specified arguments and a specified `argv0`.
   #
-  #
   # Each of these is detailed below.
   #
   # The optional hash argument `env` specifies name/value pairs that are to be
@@ -2427,7 +2391,6 @@ class IO < Object
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   # *   Options for Kernel#spawn.
   #
-  #
   # **Forked \Process**
   #
   # When argument `cmd` is the 1-character string `'-'`, causes the process to
@@ -2496,7 +2459,6 @@ class IO < Object
   #     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"
@@ -2604,6 +2566,7 @@ class IO < Object
   #
   # With argument `limit` given, parses lines as determined by the default line
   # separator and the given line-length limit (see [Line
+  # Separator](rdoc-ref:IO@Line+Separator) and [Line
   # Limit](rdoc-ref:IO@Line+Limit)):
   #
   #     File.foreach('t.txt', 7) {|line| p line }
@@ -2620,9 +2583,8 @@ class IO < Object
   #     "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)):
+  # With arguments `sep` and `limit` given, combines the two behaviors (see [Line
+  # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)).
   #
   # Optional keyword arguments `opts` specify:
   #
@@ -2630,7 +2592,6 @@ class IO < Object
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   # *   [Line Options](rdoc-ref:IO@Line+IO).
   #
-  #
   # Returns an Enumerator if no block is given.
   #
   def self.foreach: (string | _ToPath path, ?String sep, ?Integer limit, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?chomp: boolish) { (String line) -> void } -> nil
@@ -2654,7 +2615,6 @@ class IO < Object
   # *   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
@@ -2672,7 +2632,6 @@ class IO < Object
   # *   [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>]
@@ -2795,14 +2754,14 @@ class IO < Object
   #
   # 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)):
+  # Separator](rdoc-ref:IO@Line+Separator) and [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)):
+  # With arguments `sep` and `limit` given, combines the two behaviors (see [Line
+  # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)).
   #
   # Optional keyword arguments `opts` specify:
   #
@@ -2825,7 +2784,8 @@ class IO < Object
   # 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.
+  # Argument `timeout` is a numeric value (such as integer or float) 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:
@@ -2834,7 +2794,6 @@ class IO < Object
   # *   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
@@ -3125,11 +3084,8 @@ class IO < Object
   #     "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.
-  #
+  # With arguments `sep` and `limit` given, combines the two behaviors (see [Line
+  # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)).
   #
   # Optional keyword argument `chomp` specifies whether line separators are to be
   # omitted:
@@ -3230,11 +3186,8 @@ class IO < Object
   #     "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.
-  #
+  # With arguments `sep` and `limit` given, combines the two behaviors (see [Line
+  # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit)).
   #
   # Optional keyword argument `chomp` specifies whether line separators are to be
   # omitted: