Update docs for PipeReader.TryRead (#52237)

* Update docs for PipeReader.TryRead

As per #30161 (comment), add some documentation to `PipeReader.TryRead` to better document some unclear behavior.

The unclear behavior technically resides in the `StreamPipeReader.TryRead` implementation, which is internal, so I added this as a `<remark>` to the public `PipeReader.TryRead` method instead.

* remove doc reference to internal StreamPipeReader

The StreamPipeReader <see .. /> reference is an internal type, so it should not be mentioned in the public documentation.

* Format remarks as markdown and use !IMPORTANT

Co-authored-by: Jeff Handley <jeff.handley@microsoft.com>

Author: waf

src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs

@@ -15,7 +15,15 @@ public abstract partial class PipeReader
         /// <summary>Attempts to synchronously read data from the <see cref="System.IO.Pipelines.PipeReader" />.</summary>
         /// <param name="result">When this method returns <see langword="true" />, this value is set to a <see cref="System.IO.Pipelines.ReadResult" /> instance that represents the result of the read call; otherwise, this value is set to <see langword="default" />.</param>
         /// <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 is no need to call <see cref="System.IO.Pipelines.PipeReader.AdvanceTo(System.SequencePosition,System.SequencePosition)" />.</remarks>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// If the pipe returns <see langword="false" />, there is no need to call <see cref="System.IO.Pipelines.PipeReader.AdvanceTo(System.SequencePosition,System.SequencePosition)" />.
+        /// [!IMPORTANT]
+        /// The `System.IO.Pipelines.PipeReader` implementation returned by `System.IO.Pipelines.PipeReader.Create(System.IO.Stream, System.IO.Pipelines.StreamPipeReaderOptions?)`
+        /// will not read new data from the backing `System.IO.Stream` when `System.IO.Pipelines.PipeReader.TryRead(out System.IO.Pipelines.ReadResult)` is called.
+        ///
+        /// `System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)` must be called to read new data from the backing `System.IO.Stream`.
+        /// Any unconsumed data from a previous asynchronous read will be available to `System.IO.Pipelines.PipeReader.TryRead(out System.IO.Pipelines.ReadResult)`.
+        /// ]]></format></remarks>
         public abstract bool TryRead(out ReadResult result);
 
         /// <summary>Asynchronously reads a sequence of bytes from the current <see cref="System.IO.Pipelines.PipeReader" />.</summary>