Correct bufferSize parameter descriptions in StreamReader and StreamWriter XML docs

Author: ViveliDuCh

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "githubPullRequests.ignoredPullRequestBranches": [
+        "main"
+    ]
+}

xml/System.IO/StreamReader.xml

@@ -974,13 +974,13 @@
         <param name="stream">The stream to be read.</param>
         <param name="encoding">The character encoding to use.</param>
         <param name="detectEncodingFromByteOrderMarks">Indicates whether to look for byte order marks at the beginning of the file.</param>
-        <param name="bufferSize">The minimum buffer size.</param>
+        <param name="bufferSize">The minimum buffer size, in bytes.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamReader" /> class for the specified stream, with the specified character encoding, byte order mark detection option, and buffer size.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used.
+ The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used.
 
  This constructor allows you to change the encoding the first time you read from the <xref:System.IO.StreamReader> object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the <xref:System.Text.Encoding.GetPreamble%2A?displayProperty=nameWithType> method for more information.
 
@@ -1008,7 +1008,7 @@
         <exception cref="T:System.ArgumentNullException">
           <paramref name="stream" /> or <paramref name="encoding" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is less than or equal to zero.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <altmember cref="T:System.Text.Encoding" />
         <related type="Article" href="/dotnet/standard/io/">File and Stream I/O</related>
         <related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read Text from a File</related>
@@ -1077,7 +1077,7 @@
         <param name="path">The complete file path to be read.</param>
         <param name="encoding">The character encoding to use.</param>
         <param name="detectEncodingFromByteOrderMarks">Indicates whether to look for byte order marks at the beginning of the file.</param>
-        <param name="bufferSize">The minimum buffer size, in number of 16-bit characters.</param>
+        <param name="bufferSize">The minimum buffer size, in bytes.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamReader" /> class for the specified file name, with the specified character encoding, byte order mark detection option, and buffer size.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -1087,7 +1087,7 @@
 
  This constructor allows you to change the encoding the first time you read from the <xref:System.IO.StreamReader> object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the <xref:System.Text.Encoding.GetPreamble%2A?displayProperty=nameWithType> method for more information.
 
- The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used.
+ The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used.
 
  The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share.
 
@@ -1115,7 +1115,7 @@
         <exception cref="T:System.NotSupportedException">
           <paramref name="path" /> includes an incorrect or invalid syntax for file name, directory name, or volume label.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is less than or equal to zero.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <altmember cref="T:System.Text.Encoding" />
         <related type="Article" href="/dotnet/standard/io/">File and Stream I/O</related>
         <related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read Text from a File</related>
@@ -1249,7 +1249,7 @@
         <param name="encoding">The character encoding to use.</param>
         <param name="detectEncodingFromByteOrderMarks">
           <see langword="true" /> to look for byte order marks at the beginning of the file; otherwise, <see langword="false" />.</param>
-        <param name="bufferSize">The minimum buffer size.</param>
+        <param name="bufferSize">The minimum buffer size, in bytes.</param>
         <param name="leaveOpen">
           <see langword="true" /> to leave the stream open after the <see cref="T:System.IO.StreamReader" /> object is disposed; otherwise, <see langword="false" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamReader" /> class for the specified stream based on the specified character encoding, byte order mark detection option, and buffer size, and optionally leaves the stream open.</summary>
@@ -1259,7 +1259,7 @@
 ## Remarks
  Unless you set the `leaveOpen` parameter to `true`, the <xref:System.IO.StreamReader> object calls <xref:System.IO.Stream.Dispose> on the provided <xref:System.IO.Stream> object when <xref:System.IO.StreamReader.Dispose%2A?displayProperty=nameWithType> is called.
 
- The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used.
+ The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used.
 
  This constructor enables you to change the encoding the first time you read from the <xref:System.IO.StreamReader> object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the <xref:System.Text.Encoding.GetPreamble%2A?displayProperty=nameWithType> method for more information.
 

xml/System.IO/StreamWriter.xml

@@ -612,7 +612,7 @@
       <Docs>
         <param name="stream">The stream to write to.</param>
         <param name="encoding">The character encoding to use.</param>
-        <param name="bufferSize">The buffer size, in bytes.</param>
+        <param name="bufferSize">The buffer size, in characters.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamWriter" /> class for the specified stream by using the specified encoding and buffer size.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -640,7 +640,7 @@
         <exception cref="T:System.ArgumentNullException">
           <paramref name="stream" /> or <paramref name="encoding" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is negative.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <exception cref="T:System.ArgumentException">
           <paramref name="stream" /> is not writable.</exception>
         <altmember cref="T:System.Text.Encoding" />
@@ -871,7 +871,7 @@
       <Docs>
         <param name="stream">The stream to write to.</param>
         <param name="encoding">The character encoding to use.</param>
-        <param name="bufferSize">The buffer size, in bytes.</param>
+        <param name="bufferSize">The buffer size, in characters.</param>
         <param name="leaveOpen">
           <see langword="true" /> to leave the stream open after the <see cref="T:System.IO.StreamWriter" /> object is disposed; otherwise, <see langword="false" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamWriter" /> class for the specified stream by using the specified encoding and buffer size, and optionally leaves the stream open.</summary>
@@ -899,7 +899,7 @@
         <exception cref="T:System.ArgumentNullException">
           <paramref name="stream" /> or <paramref name="encoding" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is negative.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <exception cref="T:System.ArgumentException">
           <paramref name="stream" /> is not writable.</exception>
       </Docs>
@@ -967,7 +967,7 @@
         <param name="append">
           <see langword="true" /> to append data to the file; <see langword="false" /> to overwrite the file. If the specified file does not exist, this parameter has no effect, and the constructor creates a new file.</param>
         <param name="encoding">The character encoding to use.</param>
-        <param name="bufferSize">The buffer size, in bytes.</param>
+        <param name="bufferSize">The buffer size, in characters.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamWriter" /> class for the specified file on the specified path, using the specified encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -1003,7 +1003,7 @@
         <exception cref="T:System.ArgumentNullException">
           <paramref name="path" /> or <paramref name="encoding" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is negative.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <exception cref="T:System.IO.IOException">
           <paramref name="path" /> includes an incorrect or invalid syntax for file name, directory name, or volume label syntax.</exception>
         <exception cref="T:System.Security.SecurityException">The caller does not have the required permission.</exception>