Document trailing newline behavior for ReadLine and ReadAllLines/ReadLines APIs (#12493)

Author: Copilot

xml/System.IO/File.xml

@@ -4846,6 +4846,8 @@ The following example moves a file.
 ## Remarks
  This method opens a file, reads each line of the file, then adds each line as an element of a string array. It then closes the file. A line is defined as a sequence of characters followed by a carriage return ('\r'), a line feed ('\n'), or a carriage return immediately followed by a line feed. The resulting string does not contain the terminating carriage return and/or line feed.
 
+ If the file ends with a newline sequence, no additional empty line is appended to the array. For example, a file containing `"line1\nline2\n"` produces the same two-element array (`["line1", "line2"]`) as a file containing `"line1\nline2"`.
+
  This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. Encoding formats UTF-8 and UTF-32 (both big-endian and little-endian) can be detected.
 
 
@@ -4945,6 +4947,8 @@ The following example moves a file.
 ## Remarks
  This method opens a file, reads each line of the file, and then adds each line as an element of a string array. It then closes the file. A line is defined as a sequence of characters followed by a carriage return ('\r'), a line feed ('\n'), or a carriage return immediately followed by a line feed. The resulting string does not contain the terminating carriage return and/or line feed.
 
+ If the file ends with a newline sequence, no additional empty line is appended to the array. For example, a file containing `"line1\nline2\n"` produces the same two-element array (`["line1", "line2"]`) as a file containing `"line1\nline2"`.
+
  This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. Encoding formats UTF-8 and UTF-32 (both big-endian and little-endian) can be detected.
 
 
@@ -5460,8 +5464,11 @@ You can use the <xref:System.IO.File.ReadLines*> method to do the following:
 
 This method uses <xref:System.Text.Encoding.UTF8*> for the encoding value.
 
+A line is defined as a sequence of characters followed by a carriage return ('\r'), a line feed ('\n'), or a carriage return immediately followed by a line feed, or as the final sequence of characters in the file or stream if it ends without a newline sequence. If the file ends with a newline sequence, no additional empty line is returned. For example, a file containing `"line1\nline2\n"` produces the same two lines (`"line1"` and `"line2"`) as a file containing `"line1\nline2"`.
+
 ## Examples
- The following example reads the lines of a file to find lines that contain specified strings.
+
+The following example reads the lines of a file to find lines that contain specified strings.
 
  :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadLines/program.cs" id="Snippet1":::
  :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/ReadLines/program.fs" id="Snippet1":::
@@ -5568,6 +5575,8 @@ You can use the <xref:System.IO.File.ReadLines*> method to do the following:
 - Write the returned collection of lines to a file with the <xref:System.IO.File.WriteAllLines(System.String,System.Collections.Generic.IEnumerable{System.String},System.Text.Encoding)?displayProperty=nameWithType> method, or append them to an existing file with the <xref:System.IO.File.AppendAllLines(System.String,System.Collections.Generic.IEnumerable{System.String},System.Text.Encoding)?displayProperty=nameWithType> method.
 - Create an immediately populated instance of a collection that takes an <xref:System.Collections.Generic.IEnumerable`1> collection of strings for its constructor, such as a <xref:System.Collections.Generic.IList`1> or a <xref:System.Collections.Generic.Queue`1>.
 
+A line is defined as a sequence of characters terminated by a carriage return ('\r'), a line feed ('\n'), a carriage return immediately followed by a line feed, or the end of the file or stream. If the file ends with a newline sequence, no additional empty line is returned. For example, a file containing `"line1\nline2\n"` produces the same two lines (`"line1"` and `"line2"`) as a file containing `"line1\nline2"`.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">.NET Framework and .NET Core versions older than 2.1: <paramref name="path" /> is a zero-length string, contains only white space, or contains one or more invalid characters as defined by the <see cref="M:System.IO.Path.GetInvalidPathChars" /> method.</exception>

xml/System.IO/StreamReader.xml

@@ -2520,6 +2520,8 @@ Following a call to <xref:System.IO.StreamReader.Close*>, any operations on the
 ## Remarks
  A line is defined as a sequence of characters followed by a line feed ("\n"), a carriage return ("\r"), or a carriage return immediately followed by a line feed ("\r\n"). The string that is returned does not contain the terminating carriage return or line feed. The returned value is `null` if the end of the input stream is reached.
 
+ If the stream ends with a newline sequence, no additional empty line is returned. For example, a stream containing `"line1\nline2\n"` produces the same two lines (`"line1"` and `"line2"`) as a stream containing `"line1\nline2"`.
+
  This method overrides <xref:System.IO.TextReader.ReadLine*?displayProperty=nameWithType>.
 
  If the current method throws an <xref:System.OutOfMemoryException>, the reader's position in the underlying <xref:System.IO.Stream> object is advanced by the number of characters the method was able to read, but the characters already read into the internal <xref:System.IO.StreamReader.ReadLine*> buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the <xref:System.IO.StreamReader.DiscardBufferedData*> method; however, this method slows performance and should be called only when absolutely necessary.

xml/System.IO/StringReader.xml

@@ -1058,6 +1058,8 @@ This implementation of `Close` calls the <xref:System.IO.StringReader.Dispose*>,
 
  A line is defined as a sequence of characters followed by a line feed ("\n"), a carriage return ("\r"), a carriage return immediately followed by a line feed ("\r\n"), or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The returned value is `null` if the end-of-stream marker has been reached. That is to say, if there is nothing between the last line read and the end-of-stream marker, the method returns `null`.
 
+ If the string ends with a newline sequence, no additional empty line is returned. For example, the string `"line1\nline2\n"` produces the same two lines (`"line1"` and `"line2"`) as the string `"line1\nline2"`.
+
  If the current method throws an <xref:System.OutOfMemoryException>, the reader's position in the underlying string is advanced by the number of characters the method was able to read, but the characters already read into the internal <xref:System.IO.StringReader.ReadLine*> buffer are discarded. Because the position of the reader in the string cannot be changed, the characters already read are unrecoverable, and can be accessed only by reinitializing the <xref:System.IO.StringReader>. To avoid such a situation, use the <xref:System.IO.StringReader.Read*> method and store the read characters in a preallocated buffer.
 
  The following table lists examples of other typical or related I/O tasks.
@@ -1075,8 +1077,6 @@ This implementation of `Close` calls the <xref:System.IO.StringReader.Dispose*>,
 |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)|
 |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)|
 
-
-
 ## Examples
  This code example is part of a larger example provided for the <xref:System.IO.StringReader> class.
 

xml/System.IO/TextReader.xml

@@ -1193,9 +1193,11 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- A line is defined as a sequence of characters followed by a carriage return (0x000d), a line feed (0x000a), a carriage return followed by a line feed, <xref:System.Environment.NewLine*?displayProperty=nameWithType>, or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached.
+ A line is defined as a sequence of characters followed by a carriage return (0x000d), a line feed (0x000a), a carriage return followed by a line feed, <xref:System.Environment.NewLine*?displayProperty=nameWithType>, or the end of the reader's input. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input has been reached.
 
- If the method throws an <xref:System.OutOfMemoryException> exception, the reader's position in the underlying <xref:System.IO.Stream> is advanced by the number of characters the method was able to read, but the characters that were already read into the internal <xref:System.IO.TextReader.ReadLine*> buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the <xref:System.IO.TextReader> object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying <xref:System.IO.Stream> also needs to be reinitialized.
+ If the input ends with a newline sequence, no additional empty line is returned. For example, input containing `"line1\nline2\n"` produces the same two lines (`"line1"` and `"line2"`) as input containing `"line1\nline2"`.
+
+ If the method throws an <xref:System.OutOfMemoryException> exception, the reader's position in its underlying source is advanced by the number of characters the method was able to read, but the characters that were already read into the internal <xref:System.IO.TextReader.ReadLine*> buffer are discarded. Because the reader's position in the underlying source cannot be reset, the characters that were already read are unrecoverable and can be accessed only by reinitializing the <xref:System.IO.TextReader> object. If the initial position within the underlying source is unknown or the source does not support repositioning, the underlying source also needs to be reinitialized.
 
  To avoid such a situation and produce robust code you should use the <xref:System.IO.TextReader.Read*> method and store the read characters in a preallocated buffer.