Improve CancelPendingRead/Flush() docs (#5033)

* Improve PipeWriter.CancelPendingFlush() docs

* Improve PipeReader.CancelPendingRead() docs

* Apply suggestions from code review

Co-authored-by: Carlos Sanchez <[email protected]>

Co-authored-by: Carlos Sanchez <[email protected]>

Author: halter73

xml/System.IO.Pipelines/FlushResult.xml

@@ -71,9 +71,9 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets a value that indicates whether the current <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> operation was canceled.</summary>
+        <summary>Gets a value that indicates whether the current <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> operation was canceled by <see cref="M:System.IO.Pipelines.PipeWriter.CancelPendingFlush" />.</summary>
         <value>
-          <see langword="true" /> if the current <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> operation was canceled; otherwise, <see langword="false" />.</value>
+          <see langword="true" /> if the current <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> operation was canceled by <see cref="M:System.IO.Pipelines.PipeWriter.CancelPendingFlush" />; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.IO.Pipelines/PipeReader.xml

@@ -198,8 +198,16 @@ The examined parameter should be greater than or equal to the examined position
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Cancels to currently pending or if none is pending next call to <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" />, without completing the <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Cancels the pending <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> operation without causing it to throw and without completing the <see cref="T:System.IO.Pipelines.PipeReader" />. If there is no pending operation, this cancels the next operation.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The canceled <xref:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)> operation returns a <xref:System.IO.Pipelines.ReadResult> where <xref:System.IO.Pipelines.ReadResult.IsCanceled> is `true`.
+
+              ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Complete">

xml/System.IO.Pipelines/PipeWriter.xml

@@ -126,8 +126,16 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Cancels the pending <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> operation. If there is none, cancels next <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> operation, without completing the <see cref="T:System.IO.Pipelines.PipeWriter" />.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Cancels the pending <see cref="M:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)" /> or <see cref="M:System.IO.Pipelines.PipeWriter.WriteAsync(System.ReadOnlyMemory{System.Byte},System.Threading.CancellationToken)" /> operation without causing the operation to throw and without completing the <see cref="T:System.IO.Pipelines.PipeWriter" />. If there is no pending operation, this cancels the next operation.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The canceled <xref:System.IO.Pipelines.PipeWriter.FlushAsync(System.Threading.CancellationToken)> or <xref:System.IO.Pipelines.PipeWriter.WriteAsync(System.ReadOnlyMemory{System.Byte},System.Threading.CancellationToken)> operation returns a <xref:System.IO.Pipelines.FlushResult> where <xref:System.IO.Pipelines.FlushResult.IsCanceled> is `true`.
+
+              ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Complete">

xml/System.IO.Pipelines/ReadResult.xml

@@ -96,7 +96,7 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets a value that indicates whether the current <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> operation was canceled.</summary>
+        <summary>Gets a value that indicates whether the current <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> operation was canceled by <see cref="M:System.IO.Pipelines.PipeReader.CancelPendingRead" />.</summary>
         <value>
           <see langword="true" /> if the <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> operation that produced this <see cref="T:System.IO.Pipelines.ReadResult" /> was canceled by <see cref="M:System.IO.Pipelines.PipeReader.CancelPendingRead" />; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>