Update docs for PipeReader.TryRead #52237
Conversation
As per dotnet#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.
src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs
Outdated
Show resolved
Hide resolved
|
It's possible that TryRead should throw or block on |
The StreamPipeReader <see .. /> reference is an internal type, so it should not be mentioned in the public documentation.
| /// <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)" />. | ||
| /// <para> | ||
| /// Note: the <see cref="System.IO.Pipelines.PipeReader" /> implementation returned by <see cref="System.IO.Pipelines.PipeReader.Create(System.IO.Stream, System.IO.Pipelines.StreamPipeReaderOptions?)"/> |
There was a problem hiding this comment.
@dotnet/docs do we need to quote this and add a [!NOTE] for this to show up correctly?
I think so looking at this
There was a problem hiding this comment.
I don't know that you can use [!NOTE] because that's markdown. /// comments are HTML. I believe the only way to use markdown and the ms.docs syntax extensions (which [!NOTE] is) is to migrate this content to the external XML API files.
Tagging @BillWagner @gewarren for comment.
There was a problem hiding this comment.
You'll need to wrap it in <format> tags like this:
There was a problem hiding this comment.
I updated the comment to use markdown and to use [!IMPORTANT] within the remarks. There were no uses of [!NOTE] anywhere else, but there were a couple other uses of [!IMPORTANT] within the Pipelines XML docs, so I followed that precedent.
terrajobst
added
the
community-contribution
ghost
locked as resolved and limited conversation to collaborators
As per #30161 (comment), add some documentation to
PipeReader.TryReadto better describe some unclear behavior.The unclear behavior technically resides in the
StreamPipeReaderimplementation, which is internal, so I added this as a remark to the publicPipeReader.TryReadmethod instead, so it will show up in the public documentation.