More on IO doc (#9842)

1 files changed, 76 insertions, 70 deletions

diff --git a/io.c b/io.c
index eb2698d047..621d5c8457 100644
--- a/io.c
+++ b/io.c
@@ -15094,56 +15094,64 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *
  *  == Line \IO
  *
- *  You can read an \IO stream line-by-line using these methods:
+ *  \Class \IO supports line-oriented
+ *  {input}[rdoc-ref:IO@Line+Input] and {output}[rdoc-ref:IO@Line+Output]
  *
- *  - 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.
+ *  === Line Input
+ *
+ *  \Class \IO supports line-oriented input for
+ *  {files}[rdoc-ref:IO@File+Line+Input] and {IO streams}[rdoc-ref:IO@Stream+Line+Input]
+ *
+ *  ==== \File Line Input
  *
- *  Each of these reader methods accepts:
+ *  You can read lines from a file using these methods:
  *
- *  - An optional line separator, +sep+;
+ *  - IO.foreach: Reads each line and passes it to the given block.
+ *  - IO.readlines: Reads and returns all lines in an array.
+ *
+ *  For each of these methods:
+ *
+ *  - You can specify {open options}[rdoc-ref:IO@Open+Options].
+ *  - Line parsing depends on the effective <i>line separator</i>;
  *    see {Line Separator}[rdoc-ref:IO@Line+Separator].
- *  - An optional line-size limit, +limit+;
+ *  - The length of each returned line depends on the effective <i>line limit</i>;
  *    see {Line Limit}[rdoc-ref:IO@Line+Limit].
  *
- *  For each of these reader methods, reading may begin mid-line,
- *  depending on the stream's position;
- *  see {Position}[rdoc-ref:IO@Position]:
+ *  ==== Stream Line Input
  *
- *    f = File.new('t.txt')
- *    f.pos = 27
- *    f.each_line {|line| p line }
- *    f.close
+ *  You can read lines from an \IO stream using these methods:
  *
- *  Output:
- *
- *    "rth line\n"
- *    "Fifth line\n"
+ *  - 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.
  *
- *  You can write to an \IO stream line-by-line using this method:
+ *  For each of these methods:
  *
- *  - IO#puts: Writes objects to the stream.
+ *  - Reading may begin mid-line,
+ *    depending on the stream's _position_;
+ *    see {Position}[rdoc-ref:IO@Position].
+ *  - Line parsing depends on the effective <i>line separator</i>;
+ *    see {Line Separator}[rdoc-ref:IO@Line+Separator].
+ *  - The length of each returned line depends on the effective <i>line limit</i>;
+ *    see {Line Limit}[rdoc-ref:IO@Line+Limit].
  *
- *  === Line Separator
+ *  ===== Line Separator
  *
- *  Each of these methods uses a <i>line separator</i>,
- *  which is the string that delimits lines:
+ *  Each of the {line input methods}[rdoc-ref:IO@Line+Input] uses a <i>line separator</i>:
+ *  the string that determines what is considered a line;
+ *  it is sometimes called the <i>input record separator</i>.
  *
- *  - IO.foreach.
- *  - IO.readlines.
- *  - IO#each_line.
- *  - IO#gets.
- *  - IO#readline.
- *  - IO#readlines.
+ *  The default line separator is taken from global variable <tt>$/</tt>,
+ *  whose initial value is <tt>"\n"</tt>.
  *
- *  The default line separator is the given by the global variable <tt>$/</tt>,
- *  whose value is by default <tt>"\n"</tt>.
- *  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"
@@ -15151,7 +15159,7 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *    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"
@@ -15160,15 +15168,27 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *    f.gets        # => "e\n"
  *    f.close
  *
- *  There are two special line separators:
+ *  Or by setting global variable <tt>$/</tt>:
+ *
+ *    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
  *
- *  - <tt>''</tt> (the empty string): The next "paragraph" is read
+ *  - <tt>''</tt> (the empty string): The next "paragraph" is to be read
  *    (paragraphs being separated by two consecutive line separators):
  *
  *      f = File.new('t.txt')
@@ -15176,23 +15196,18 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *      f.gets('') # => "Fourth line\nFifth line\n"
  *      f.close
  *
- *  === Line Limit
+ *  ===== Line Limit
  *
- *  Each of these methods uses a <i>line limit</i>,
- *  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 <i>line limit</i>,
+ *  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 <tt>-1</tt>;
+ *  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"
@@ -15210,24 +15225,9 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *    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
- *
- *  With arguments +sep+ and +limit+ given,
- *  combines the two behaviors:
+ *  ===== Line Number
  *
- *  - Returns the next line as determined by line separator +sep+.
- *  - But returns no more bytes than are allowed by the 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
- *
- *  A readable \IO stream has a non-negative integer <i>line number</i>.
- *
- *  The relevant methods:
+ *  A readable \IO stream has a non-negative integer <i>line number</i>:
  *
  *  - IO#lineno: Returns the line number.
  *  - IO#lineno=: Resets and returns the line number.
@@ -15235,7 +15235,7 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *  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+:
+ *  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.
@@ -15325,6 +15325,12 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *      $.          # => 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
  *
  *  You can process an \IO stream character-by-character using these methods: