Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for PipeReader.TryRead #52237

Merged
merged 5 commits into from
Oct 21, 2021
+9 −1
Merged

Update docs for PipeReader.TryRead #52237

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
855ff2e
Update docs for PipeReader.TryRead
waf May 4, 2021
8ca456b
remove doc reference to internal StreamPipeReader
waf Jun 29, 2021
ecc247c
Merge branch 'main' into update-docs-for-streampipereader-tryread
jeffhandley Oct 9, 2021
e61099b
Format remarks as markdown and use !IMPORTANT
jeffhandley Oct 9, 2021
8ac322c
Merge branch 'main' into update-docs-for-streampipereader-tryread
jeffhandley Oct 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeReader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
/// 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?)"/>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dotnet/docs do we need to quote this and add a [!NOTE] for this to show up correctly?

I think so looking at this

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You'll need to wrap it in <format> tags like this:

runtime/src/libraries/System.IO.Pipelines/src/System/IO/Pipelines/PipeWriter.cs

Line 46 in 57bfe47

/// <remarks><format type="text/markdown"><![CDATA[
.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

/// will not read new data from the backing <see cref="System.IO.Stream"/> when <see cref="System.IO.Pipelines.PipeReader.TryRead(out System.IO.Pipelines.ReadResult)"/> is called.
/// <see cref="System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> must be called to read new data from the backing <see cref="System.IO.Stream"/>.
/// Any unconsumed data from a previous asynchronous read will be available to <see cref="System.IO.Pipelines.PipeReader.TryRead(out System.IO.Pipelines.ReadResult)"/>.
/// </para>
/// </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>
Expand Down