Manually document System.IO.BufferedStream (#2770)

* Manually document System.IO.BufferedStream

* suggestions by rpetrusha

Co-Authored-By: Ron Petrusha <[email protected]>

Author: carlossanlop

xml/System.IO/BufferedStream.xml

@@ -355,8 +355,8 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the buffer size in bytes for this buffered stream.</summary>
+        <value>An integer representing the buffer size in bytes.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -647,10 +647,19 @@ bufStream->Close();
         <Parameter Name="bufferSize" Type="System.Int32" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="destination">To be added.</param>
-        <param name="bufferSize">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="destination">The stream to which the contents of the current buffered stream will be copied.</param>
+        <param name="bufferSize">The size of the buffer. This value must be greater than zero. The default size is 81920.</param>
+        <summary>Reads the bytes from the current buffered stream and writes them to another stream.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="destination" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="bufferSize" /> is negative or zero.</exception>
+        <exception cref="T:System.NotSupportedException">The current stream does not support reading.
+
+-or-
+
+<paramref name="destination" /> does not support writing.</exception>
+        <exception cref="T:System.ObjectDisposedException">Either the current stream or <paramref name="destination" /> was closed before the <see cref="M:System.IO.Stream.CopyTo(System.IO.Stream)" /> method was called.</exception>
+        <exception cref="T:System.IO.IOException">An I/O error occurred.</exception>
       </Docs>
     </Member>
     <Member MemberName="CopyToAsync">
@@ -682,12 +691,24 @@ bufStream->Close();
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="destination">To be added.</param>
-        <param name="bufferSize">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="destination">The stream to which the contents of the current buffered stream will be copied.</param>
+        <param name="bufferSize">The size, in bytes, of the buffer. This value must be greater than zero. The default sizer is 81920.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
+        <summary>Asynchronously reads the bytes from the current buffered stream and writes them to another stream, using a specified buffer size and cancellation token.</summary>
+        <returns>A task that represents the asynchronous copy operation.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+The `CopyToAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.  
+
+If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status%2A> property.  
+
+Copying begins at the current position in the current stream.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Dispose">
@@ -725,9 +746,21 @@ bufStream->Close();
         <Parameter Name="disposing" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="disposing">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="disposing"><see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
+        <summary>Releases the unmanaged resources used by the buffered stream and optionally releases the managed resources.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+You should release all resources by specifying `true` for `disposing`. When `disposing` is `true`, the stream can also ensure data is flushed to the underlying buffer, and access other finalizable objects. This may not be possible when called from a finalizer due a lack of ordering among finalizers.
+
+If your stream is using an operating system handle to communicate with its source, consider using a subclass of <xref:System.Runtime.InteropServices.SafeHandle> for this purpose.
+
+This method is called by the public <xref:System.ComponentModel.Component.Dispose> method and the <xref:System.Object.Finalize%2A> method. <xref:System.ComponentModel.Component.Dispose> invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose(Boolean)` with `disposing` set to `false`.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="DisposeAsync">
@@ -757,9 +790,21 @@ bufStream->Close();
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <summary>Asynchronously releases the unmanaged resources used by the buffered stream.</summary>
+        <returns>A task that represents the asynchronous dispose operation.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The `DisposeAsync` method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
+
+This method disposes the stream by writing any changes to the backing store and closing the stream to release resources.
+
+Calling `DisposeAsync` allows the resources used by the <xref:System.IO.BufferedStream> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md).
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="EndRead">
@@ -1097,10 +1142,22 @@ bufStream->Close();
         <Parameter Name="destination" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="destination">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="destination">A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source.</param>
+        <summary>Copies bytes from the current buffered stream to a byte span and advances the position within the buffered stream by the number of bytes read.</summary>
+        <returns>The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks
+
+Use the <xref:System.IO.BufferedStream.CanRead%2A> property to determine whether the current instance supports reading. Use the <xref:System.IO.BufferedStream.ReadAsync%2A> method to read asynchronously from the current stream.
+
+Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. The implementation will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.
+
+Use <xref:System.IO.BinaryReader> for reading primitive data types.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Read">
@@ -1213,11 +1270,23 @@ bufStream->Close();
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="buffer">The region of memory to write the data into.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
+        <summary>Asynchronously reads a sequence of bytes from the current buffered stream and advances the position within the buffered stream by the number of bytes read.</summary>
+        <returns>A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.ValueTask`1.Result" /> property contains the total number of bytes read into the buffer. The result value can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or it can be 0 (zero) if the end of the stream has been reached.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
+
+Use the <xref:System.IO.BufferedStream.CanRead%2A> property to determine whether the current instance supports reading.
+
+If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status> property.
+
+            ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ReadAsync">
@@ -1483,8 +1552,8 @@ bufStream->Close();
         <ReturnType>System.IO.Stream</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the underlying <see cref="T:System.IO.Stream" /> instance for this buffered stream.</summary>
+        <value>The underlying stream instance.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1516,9 +1585,19 @@ bufStream->Close();
         <Parameter Name="buffer" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="buffer">A region of memory. This method copies the contents of this region to the current buffered stream.</param>
+        <summary>Writes a sequence of bytes to the current buffered stream and advances the current position within this buffered stream by the number of bytes written.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+Use the <xref:System.IO.BufferedStream.CanWrite%2A> property to determine whether the current instance supports writing. Use the <xref:System.IO.BufferedStream.WriteAsync%2A> method to write asynchronously to the current buffered stream.
+
+If the write operation is successful, the position within the buffered stream advances by the number of bytes written. If an exception occurs, the position within the buffered stream remains unchanged.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Write">
@@ -1622,11 +1701,23 @@ bufStream->Close();
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="buffer">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="buffer">The region of memory to write data from.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
+        <summary>Asynchronously writes a sequence of bytes to the current buffered stream, advances the current position within this buffered stream by the number of bytes written, and monitors cancellation requests.</summary>
+        <returns>A task that represents the asynchronous write operation.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
+
+Use the <xref:System.IO.BufferedStream.CanWrite%2A> property to determine whether the current instance supports writing.
+
+If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled?displayProperty=nameWithType> value for the <xref:System.Threading.Tasks.Task.Status%2A?displayProperty=nameWithType> property.
+
+            ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteAsync">
@@ -1727,7 +1818,15 @@ bufStream->Close();
       <Docs>
         <param name="value">A byte to write to the stream.</param>
         <summary>Writes a byte to the current position in the buffered stream.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+Use the <xref:System.IO.BufferedStream.CanWrite%2A> property to determine whether the current instance supports writing.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.NotSupportedException">The stream does not support writing.</exception>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
@@ -1738,4 +1837,4 @@ bufStream->Close();
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>