Skip to content

Commit ee4effc

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Document System.IO.Pipelines Platform Extensions (#2842)
* Document System.IO.Pipelines Platform Extensions * suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]> * clarify obsolete method * Update PipeReader.xml * Minor changes, particularly adding closing parens
1 parent c423aa9 commit ee4effc

File tree

5 files changed

+61
-43
lines changed

5 files changed

+61
-43
lines changed

‎xml/System.IO.Pipelines/PipeReader.xml

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -114,9 +114,9 @@
114114
<Parameter Name="leaveOpen" Type="System.Boolean" Index="0" FrameworkAlternate="dotnet-plat-ext-3.0" />
115115
</Parameters>
116116
<Docs>
117-
<param name="leaveOpen">To be added.</param>
118-
<summary>To be added.</summary>
119-
<returns>To be added.</returns>
117+
<param name="leaveOpen">An optional flag that indicates whether disposing the returned <see cref="T:System.IO.Stream"/> leaves <see cref="T:System.IO.Pipelines.PipeReader" /> open (<see langword="true" />) or completes <see cref="T:System.IO.Pipelines.PipeReader" /> (<see langword="false" />).</param>
118+
<summary>Returns the underlying <see cref="T:System.IO.Stream" /> wrapped by the <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
119+
<returns>The underlying stream.</returns>
120120
<remarks>To be added.</remarks>
121121
</Docs>
122122
</Member>
@@ -185,10 +185,10 @@
185185
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.0" />
186186
</Parameters>
187187
<Docs>
188-
<param name="destination">To be added.</param>
189-
<param name="cancellationToken">To be added.</param>
190-
<summary>To be added.</summary>
191-
<returns>To be added.</returns>
188+
<param name="destination">The pipe writer to which the contents of the current stream will be copied.</param>
189+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
190+
<summary>Asynchronously reads the bytes from the <see cref="T:System.IO.Pipelines.PipeReader" /> and writes them to the specified <see cref="T:System.IO.Pipelines.PipeWriter" />, using a specified buffer size and cancellation token.</summary>
191+
<returns>A task that represents the asynchronous copy operation.</returns>
192192
<remarks>To be added.</remarks>
193193
</Docs>
194194
</Member>
@@ -264,10 +264,19 @@
264264
<Parameter Name="state" Type="System.Object" />
265265
</Parameters>
266266
<Docs>
267-
<param name="callback">To be added.</param>
268-
<param name="state">To be added.</param>
269-
<summary>Cancels the pending <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> operation. If there is none, cancels next <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> operation, without completing the <see cref="T:System.IO.Pipelines.PipeWriter" />.</summary>
270-
<remarks>To be added.</remarks>
267+
<param name="callback">The callback to register.</param>
268+
<param name="state">The state object to pass to <paramref name="callback" /> when it's invoked.</param>
269+
<summary>Registers a callback that executes when the <see cref="T:System.IO.Pipelines.PipeWriter" /> side of the pipe is completed.</summary>
270+
<remarks>
271+
<format type="text/markdown"><![CDATA[
272+
273+
## Remarks
274+
275+
> [!IMPORTANT]
276+
> `OnWriterCompleted` may not be invoked on all implementations of <xref:System.IO.Pipelines.PipeWriter>. This method will be removed in a future release.
277+
278+
]]></format>
279+
</remarks>
271280
</Docs>
272281
</Member>
273282
<Member MemberName="ReadAsync">
@@ -324,4 +333,4 @@
324333
</Docs>
325334
</Member>
326335
</Members>
327-
</Type>
336+
</Type>

‎xml/System.IO.Pipelines/PipeWriter.xml

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@
9191
<Parameter Name="leaveOpen" Type="System.Boolean" Index="0" FrameworkAlternate="dotnet-plat-ext-3.0" />
9292
</Parameters>
9393
<Docs>
94-
<param name="leaveOpen">To be added.</param>
95-
<summary>To be added.</summary>
96-
<returns>To be added.</returns>
94+
<param name="leaveOpen">An optional flag that indicates whether disposing the returned <see cref="T:System.IO.Stream"/> leaves <see cref="T:System.IO.Pipelines.PipeReader" /> open (<see langword="true" />) or completes <see cref="T:System.IO.Pipelines.PipeReader" /> (<see langword="false" />).</param>
95+
<summary> Returns the underlying <see cref="T:System.IO.Stream" /> wrapped by the <see cref="T:System.IO.Pipelines.PipeWriter" />.</summary>
96+
<returns>The underlying stream.</returns>
9797
<remarks>To be added.</remarks>
9898
</Docs>
9999
</Member>
@@ -213,9 +213,9 @@
213213
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
214214
</Parameters>
215215
<Docs>
216-
<param name="cancellationToken">To be added.</param>
216+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="T:System.Threading.CancellationToken.None"/>.</param>
217217
<summary>Makes bytes written available to <see cref="T:System.IO.Pipelines.PipeReader" /> and runs <see cref="M:System.IO.Pipelines.PipeReader.ReadAsync(System.Threading.CancellationToken)" /> continuation.</summary>
218-
<returns>To be added.</returns>
218+
<returns>A task that represents and wraps the asynchronous flush operation.</returns>
219219
<remarks>To be added.</remarks>
220220
</Docs>
221221
</Member>
@@ -323,10 +323,19 @@ You must request a new buffer after calling <xref:System.IO.Pipelines.PipeWriter
323323
<Parameter Name="state" Type="System.Object" />
324324
</Parameters>
325325
<Docs>
326-
<param name="callback">To be added.</param>
327-
<param name="state">To be added.</param>
328-
<summary>Registers a callback that gets executed when the <see cref="T:System.IO.Pipelines.PipeReader" /> side of the pipe is completed.</summary>
329-
<remarks>To be added.</remarks>
326+
<param name="callback">The callback to register.</param>
327+
<param name="state">The state object to pass to <paramref name="callback" /> when it's invoked.</param>
328+
<summary>Registers a callback that executes when the <see cref="T:System.IO.Pipelines.PipeReader" /> side of the pipe is completed.</summary>
329+
<remarks>
330+
<format type="text/markdown"><![CDATA[
331+
332+
## Remarks
333+
334+
> [!IMPORTANT]
335+
> `OnReaderCompleted` may not be invoked on all implementations of <xref:System.IO.Pipelines.PipeWriter>. This method will be removed in a future release.
336+
337+
]]></format>
338+
</remarks>
330339
</Docs>
331340
</Member>
332341
<Member MemberName="WriteAsync">
@@ -349,12 +358,12 @@ You must request a new buffer after calling <xref:System.IO.Pipelines.PipeWriter
349358
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
350359
</Parameters>
351360
<Docs>
352-
<param name="source">To be added.</param>
353-
<param name="cancellationToken">To be added.</param>
354-
<summary>Writes <paramref name="source" /> to the pipe and makes data accessible to <see cref="T:System.IO.Pipelines.PipeReader" /></summary>
355-
<returns>To be added.</returns>
361+
<param name="source">The read-only byte memory region to write.</param>
362+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="T:System.Threading.CancellationToken.None"/>.</param>
363+
<summary>Writes the specified byte memory range to the pipe and makes data accessible to the <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
364+
<returns>A task that represents the asynchronous write operation, and wraps the flush asynchronous operation.</returns>
356365
<remarks>To be added.</remarks>
357366
</Docs>
358367
</Member>
359368
</Members>
360-
</Type>
369+
</Type>

‎xml/System.IO.Pipelines/StreamPipeExtensions.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
17+
<summary>Provides extension methods for <see cref="T:System.IO.Stream" /> that support read and write operations directly into pipes.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -46,4 +46,4 @@
4646
</Docs>
4747
</Member>
4848
</Members>
49-
</Type>
49+
</Type>

‎xml/System.IO.Pipelines/StreamPipeReaderOptions.xml

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,11 @@
3636
<Parameter Name="leaveOpen" Type="System.Boolean" />
3737
</Parameters>
3838
<Docs>
39-
<param name="pool">To be added.</param>
40-
<param name="bufferSize">To be added.</param>
41-
<param name="minimumReadSize">To be added.</param>
42-
<param name="leaveOpen">To be added.</param>
43-
<summary>To be added.</summary>
39+
<param name="pool">The memory pool to use when allocating memory. The default value is <see langword="null" />.</param>
40+
<param name="bufferSize">The minimum buffer size to use when renting memory from the <paramref name="pool" />. The default value is 4096.</param>
41+
<param name="minimumReadSize">The threshold of remaining bytes in the buffer before a new buffer is allocated. The default value is 1024.</param>
42+
<param name="leaveOpen"><see langword="true" /> to leave the underlying stream open after the <see cref="T:System.IO.Pipelines.PipeReader" /> completes; <see langword="false" /> to close it. The default is <see langword="false" />.</param>
43+
<summary>Initializes a <see cref="T:System.IO.Pipelines.StreamPipeReaderOptions" /> instance, optionally specifying a memory pool, a minimum buffer size, a minimum read size, and whether the underlying stream should be left open after the <see cref="T:System.IO.Pipelines.PipeReader" /> completes.</summary>
4444
<remarks>To be added.</remarks>
4545
</Docs>
4646
</Member>
@@ -81,8 +81,8 @@
8181
<ReturnType>System.Boolean</ReturnType>
8282
</ReturnValue>
8383
<Docs>
84-
<summary>To be added.</summary>
85-
<value>To be added.</value>
84+
<summary>Gets the value that indicates if the underlying stream should be left open after the <see cref="T:System.IO.Pipelines.PipeReader" /> completes.</summary>
85+
<value><see langword="true" /> if the underlying stream should be left open after the <see cref="T:System.IO.Pipelines.PipeReader" /> completes; otherwise, <see langword="false" />.</value>
8686
<remarks>To be added.</remarks>
8787
</Docs>
8888
</Member>
@@ -129,4 +129,4 @@
129129
</Docs>
130130
</Member>
131131
</Members>
132-
</Type>
132+
</Type>

‎xml/System.IO.Pipelines/StreamPipeWriterOptions.xml

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,10 @@
3535
<Parameter Name="leaveOpen" Type="System.Boolean" />
3636
</Parameters>
3737
<Docs>
38-
<param name="pool">To be added.</param>
39-
<param name="minimumBufferSize">To be added.</param>
40-
<param name="leaveOpen">To be added.</param>
41-
<summary>To be added.</summary>
38+
<param name="pool">The memory pool to use when allocating memory. The default value is <see langword="null" />.</param>
39+
<param name="minimumBufferSize">The minimum buffer size to use when renting memory from the <paramref name="pool" />. The default value is 4096.</param>
40+
<param name="leaveOpen"><see langword="true" /> to leave the underlying stream open after the <see cref="T:System.IO.Pipelines.PipeWriter" /> completes; <see langword="false" /> to close it. The default is <see langword="false" />.</param>
41+
<summary>Initializes a <see cref="T:System.IO.Pipelines.StreamPipeWriterOptions" /> instance, optionally specifying a memory pool, a minimum buffer size, and whether the underlying stream should be left open after the <see cref="T:System.IO.Pipelines.PipeWriter" /> completes.</summary>
4242
<remarks>To be added.</remarks>
4343
</Docs>
4444
</Member>
@@ -58,8 +58,8 @@
5858
<ReturnType>System.Boolean</ReturnType>
5959
</ReturnValue>
6060
<Docs>
61-
<summary>To be added.</summary>
62-
<value>To be added.</value>
61+
<summary>Gets the value that indicates if the underlying stream should be left open after the <see cref="T:System.IO.Pipelines.PipeWriter" /> completes.</summary>
62+
<value><see langword="true" /> if the underlying stream should be left open after the <see cref="T:System.IO.Pipelines.PipeWriter" /> completes; otherwise, <see langword="false" />.</value>
6363
<remarks>To be added.</remarks>
6464
</Docs>
6565
</Member>
@@ -106,4 +106,4 @@
106106
</Docs>
107107
</Member>
108108
</Members>
109-
</Type>
109+
</Type>

0 commit comments

Comments
 (0)