[DOC] More about line number (#6582)

2 files changed, 16 insertions, 7 deletions

diff --git a/doc/io_streams.rdoc b/doc/io_streams.rdoc
index 96285e4f36..3ee8592687 100644
--- a/doc/io_streams.rdoc
+++ b/doc/io_streams.rdoc
@@ -113,8 +113,11 @@ You can perform basic stream \IO with these methods:
 ==== Position
 
 An \IO stream has a nonnegative integer _position_,
-which is the byte offset at which the next read or write is to occur;
-the relevant methods:
+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.
+
+The relevant methods:
 
 - IO#tell (aliased as +#pos+):
   Returns the current position (in bytes) in the stream:
@@ -171,7 +174,7 @@ the relevant methods:
       f.tell           # => 40
       f.close
 
-- IO#rewind: Positions the stream to the beginning:
+- IO#rewind: Positions the stream to the beginning (also resetting the line number):
 
     f = File.new('t.txt')
     f.tell     # => 0
@@ -179,6 +182,7 @@ the relevant methods:
     f.tell     # => 12
     f.rewind   # => 0
     f.tell     # => 0
+    f.lineno   # => 0
     f.close
 
 ==== Open and Closed Streams
@@ -363,7 +367,12 @@ 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.
 
-A new stream is initially has line number +0+.
+The line number is the number of lines read by certain line-oriented methods
+(IO.foreach, IO#each_line, IO#gets, IO#readline, and IO#readlines)
+according to the given (or default) line separator +sep+.
+
+A new stream is initially has line number zero (and position zero);
+method +rewind+ resets the line number (and position) to zero.
 
 \Method IO#lineno returns the line number.
 
diff --git a/file.c b/file.c
index 5e23bc98f3..efd15ea8a1 100644
--- a/file.c
+++ b/file.c
@@ -7037,7 +7037,7 @@ const char ruby_null_device[] =
  *        f.pos = 800
  *        f.read # => ""
  *
- *  ==== Data Mode
+ *  ==== \Data Mode
  *
  *  To specify whether data is to be treated as text or as binary data,
  *  either of the following may be suffixed to any of the string read/write modes
@@ -7106,7 +7106,7 @@ const char ruby_null_device[] =
  *  - +File::CREAT+: Create file if it does not exist.
  *  - +File::EXCL+: Raise an exception if +File::CREAT+ is given and the file exists.
  *
- *  === Data Mode Specified as an \Integer
+ *  === \Data Mode Specified as an \Integer
  *
  *  Data mode cannot be specified as an integer.
  *  When the stream access mode is given as an integer,
@@ -7211,7 +7211,7 @@ const char ruby_null_device[] =
  *    f.chmod(0644)
  *    f.chmod(0444)
  *
- *  == \File Constants
+ *  == \File \Constants
  *
  *  Various constants for use in \File and \IO methods
  *  may be found in module File::Constants;