Document System.IO.Pipelines.PipeReader (#3493)

* Document System.IO.Pipelines.PipeReader

* suggestions by halter73

Co-Authored-By: Stephen Halter <[email protected]>

* MemberGroup for AdvanceTo

* suggestion by mairaw (overload summary different)

* Fix to be added

* Fix MemberGroup format

Author: carlossanlop

xml/System.IO.Pipelines/PipeReader.xml

@@ -39,6 +39,26 @@
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
+    <MemberGroup MemberName="AdvanceTo">
+      <AssemblyInfo>
+        <AssemblyName>System.IO.Pipelines</AssemblyName>
+        <AssemblyVersion>4.0.0.0</AssemblyVersion>
+        <AssemblyVersion>4.0.0.1</AssemblyVersion>
+        <AssemblyVersion>4.0.1.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Docs>
+        <summary>Moves forward the pipeline's read cursor to after the consumed data.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The memory for the consumed data will be released and no longer available. The examined data communicates to the pipeline when it should signal more data is available.
+
+          ]]></format>
+        </remarks>
+      </Docs>
+    </MemberGroup>
     <Member MemberName="AdvanceTo">
       <MemberSignature Language="C#" Value="public abstract void AdvanceTo (SequencePosition consumed);" />
       <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void AdvanceTo(valuetype System.SequencePosition consumed) cil managed" />
@@ -61,8 +81,8 @@
       </Parameters>
       <Docs>
         <param name="consumed">Marks the extent of the data that has been successfully processed.</param>
-        <summary>Moves forward the pipeline's read cursor to after the consumed data.</summary>
-        <remarks>The memory for the consumed data will be released and no longer available. The examined data communicates to the pipeline when it should signal more data is available.</remarks>
+        <summary>Moves forward the pipeline's read cursor to after the consumed data, marking the data as processed.</summary>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="AdvanceTo">
@@ -89,10 +109,8 @@
       <Docs>
         <param name="consumed">Marks the extent of the data that has been successfully processed.</param>
         <param name="examined">Marks the extent of the data that has been read and examined.</param>
-        <summary>Moves forward the pipeline's read cursor to after the consumed data.</summary>
-        <remarks>The memory for the consumed data will be released and no longer available.
-            The examined data communicates to the pipeline when it should signal more data is available.
-        </remarks>
+        <summary>Moves forward the pipeline's read cursor to after the consumed data, marking the data as processed, read and examined.</summary>
+       <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="AsStream">
@@ -329,7 +347,7 @@
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="cancellationToken">To be added.</param>
+        <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see langword="default" />.</param>
         <summary>Asynchronously reads a sequence of bytes from the current <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
         <returns>A <see cref="T:System.Threading.Tasks.ValueTask`1" /> representing the asynchronous read operation.</returns>
         <remarks>To be added.</remarks>
@@ -356,11 +374,18 @@
         <Parameter Name="result" Type="System.IO.Pipelines.ReadResult" RefType="out" />
       </Parameters>
       <Docs>
-        <param name="result">The <see cref="T:System.IO.Pipelines.ReadResult" /></param>
+        <param name="result">When this method returns <see langword="true" />, this value is set to a <see cref="T:System.IO.Pipelines.ReadResult" /> instance that represents the result of the read call; otherwise, this value is set to <see langword="default" />.</param>
         <summary>Attempts to synchronously read data the <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
-        <returns>
-          <see langword="true" /> if data was available, or if the call was canceled or the writer was completed; otherwise, <see langword="false" />.</returns>
-        <remarks>If the pipe returns <see langword="false" />, there's no need to call <see cref="M:System.IO.Pipelines.PipeReader.AdvanceTo(System.SequencePosition,System.SequencePosition)" />.</remarks>
+        <returns><see langword="true" /> if data was available, or if the call was canceled or the writer was completed; otherwise, <see langword="false" />.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the pipe returns `false`, there is no need to call <xref:System.IO.Pipelines.PipeReader.AdvanceTo(System.SequencePosition,System.SequencePosition)>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>