Skip to content

Commit da91ecf

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Port System.IO.Pipelines source code comments to Docs (#2304)
* Port System.IO.Pipelines source code comments to Docs * Update xml/System.IO.Pipelines/PipeReader.xml Thank you very much for adding the missing returns value. Co-Authored-By: carlossanlop <[email protected]> * Update xml/System.IO.Pipelines/PipeReader.xml Nice catch. Thank you for the correction. Co-Authored-By: carlossanlop <[email protected]> * Update xml/System.IO.Pipelines/StreamPipeExtensions.xml Co-Authored-By: carlossanlop <[email protected]> * Added missing comments suggested by rpetrusha in PR. * close tag * Update PipeWriter.xml * Update PipeWriter.xml * Apply suggestions from code review Suggestions from anurse and mairaw. Co-Authored-By: carlossanlop <[email protected]>
1 parent 5ce4075 commit da91ecf

File tree

3 files changed

+54
-32
lines changed

3 files changed

+54
-32
lines changed

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
</AssemblyInfo>
3636
<Parameters />
3737
<Docs>
38-
<summary>To be added.</summary>
38+
<summary>Initializes a new instance of the <see cref="T:System.IO.Pipelines.PipeReader" /> class.</summary>
3939
<remarks>To be added.</remarks>
4040
</Docs>
4141
</Member>
@@ -113,8 +113,8 @@
113113
</ReturnValue>
114114
<Parameters />
115115
<Docs>
116-
<summary>To be added.</summary>
117-
<returns>To be added.</returns>
116+
<summary>Returns a read-only <see cref="T:System.IO.Stream" /> that wraps the <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
117+
<returns>The stream that wraps the <see cref="T:System.IO.Pipelines.PipeReader" />.</returns>
118118
<remarks>To be added.</remarks>
119119
</Docs>
120120
</Member>
@@ -183,10 +183,10 @@
183183
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.0" />
184184
</Parameters>
185185
<Docs>
186-
<param name="destination">To be added.</param>
187-
<param name="cancellationToken">To be added.</param>
188-
<summary>To be added.</summary>
189-
<returns>To be added.</returns>
186+
<param name="destination">The stream to which the contents of the current stream will be copied.</param>
187+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
188+
<summary>Asynchronously reads the bytes from the <see cref="T:System.IO.Pipelines.PipeReader" /> and writes them to the specified stream, using a specified cancellation token.</summary>
189+
<returns>A task that represents the asynchronous copy operation.</returns>
190190
<remarks>To be added.</remarks>
191191
</Docs>
192192
</Member>
@@ -272,4 +272,4 @@
272272
</Docs>
273273
</Member>
274274
</Members>
275-
</Type>
275+
</Type>

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

Lines changed: 40 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
</AssemblyInfo>
4040
<Parameters />
4141
<Docs>
42-
<summary>To be added.</summary>
42+
<summary>Initializes a new instance of the class.</summary>
4343
<remarks>To be added.</remarks>
4444
</Docs>
4545
</Member>
@@ -67,8 +67,8 @@
6767
<Parameter Name="bytes" Type="System.Int32" />
6868
</Parameters>
6969
<Docs>
70-
<param name="bytes">To be added.</param>
71-
<summary>To be added.</summary>
70+
<param name="bytes">The number of bytes written to the <see cref="T:System.Span`1" /> or <see cref="T:System.Memory`1" />.</param>
71+
<summary>Notifies the <see cref="T:System.IO.Pipelines.PipeWriter" /> that <paramref name="bytes" /> bytes were written to the output <see cref="T:System.Span`1" /> or <see cref="T:System.Memory`1" />. You must request a new buffer after calling <see cref="M:System.IO.Pipelines.PipeWriter.Advance(System.Int32)" /> to continue writing more data; you cannot write to a previously acquired buffer.</summary>
7272
<remarks>To be added.</remarks>
7373
<inheritdoc />
7474
</Docs>
@@ -90,8 +90,8 @@
9090
</ReturnValue>
9191
<Parameters />
9292
<Docs>
93-
<summary>To be added.</summary>
94-
<returns>To be added.</returns>
93+
<summary>Returns a write-only <see cref="T:System.IO.Stream" /> that wraps the <see cref="T:System.IO.Pipelines.PipeWriter" />.</summary>
94+
<returns>The <see cref="T:System.IO.Stream" />.</returns>
9595
<remarks>To be added.</remarks>
9696
</Docs>
9797
</Member>
@@ -160,10 +160,10 @@
160160
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="dotnet-plat-ext-3.0" />
161161
</Parameters>
162162
<Docs>
163-
<param name="source">To be added.</param>
164-
<param name="cancellationToken">To be added.</param>
165-
<summary>To be added.</summary>
166-
<returns>To be added.</returns>
163+
<param name="source">The stream from which the contents will be copied.</param>
164+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
165+
<summary>Asynchronously reads the bytes from the specified stream and writes them to the <see cref="T:System.IO.Pipelines.PipeWriter" />.</summary>
166+
<returns>A task that represents the asynchronous copy operation.</returns>
167167
<remarks>To be added.</remarks>
168168
</Docs>
169169
</Member>
@@ -215,10 +215,21 @@
215215
<Parameter Name="sizeHint" Type="System.Int32" />
216216
</Parameters>
217217
<Docs>
218-
<param name="sizeHint">To be added.</param>
219-
<summary>To be added.</summary>
220-
<returns>To be added.</returns>
221-
<remarks>To be added.</remarks>
218+
<param name="sizeHint">The minimum length of the returned <see cref="T:System.Memory`1" />. If 0, a non-empty memory buffer of arbitrary size is returned.</param>
219+
<summary>Returns a <see cref="T:System.Memory`1" /> to write to that is at least the requested size, as specified by the <paramref name="sizeHint" /> parameter.</summary>
220+
<returns>A memory buffer of at least <paramref name="sizeHint" /> bytes. If <paramref name="sizeHint" /> is 0, returns a non-empty buffer of arbitrary size.</returns>
221+
<remarks>
222+
<format type="text/markdown"><![CDATA[
223+
224+
There is no guarantee that successive calls will return the same buffer or the same-sized buffer.
225+
226+
This method never returns <xref:System.Memory`1.Empty?displayProperty=nameWithType>, but it throws an <xref:System.OutOfMemoryException> if the requested buffer size is not available.
227+
228+
You must request a new buffer after calling <xref:System.IO.Pipelines.PipeWriter.Advance%2A> to continue writing more data; you cannot write to a previously acquired buffer.
229+
230+
]]></format>
231+
</remarks>
232+
<exception cref="T:System.OutOfMemoryException">The requested buffer size is not available.</exception>
222233
<inheritdoc />
223234
</Docs>
224235
</Member>
@@ -245,10 +256,21 @@
245256
<Parameter Name="sizeHint" Type="System.Int32" />
246257
</Parameters>
247258
<Docs>
248-
<param name="sizeHint">To be added.</param>
249-
<summary>To be added.</summary>
250-
<returns>To be added.</returns>
251-
<remarks>To be added.</remarks>
259+
<param name="sizeHint">The minimum length of the returned <see cref="T:System.Span`1" />. If 0, a non-empty buffer of arbitrary size is returned.</param>
260+
<summary>Returns a <see cref="T:System.Span`1" /> to write to that is at least the requested size, as specified by the <paramref name="sizeHint" /> parameter.</summary>
261+
<returns>A buffer of at least <paramref name="sizeHint" /> bytes. If <paramref name="sizeHint" /> is 0, returns a non-empty buffer of arbitrary size.</returns>
262+
<remarks>
263+
<format type="text/markdown"><![CDATA[
264+
265+
There is no guarantee that successive calls will return the same buffer or the same-sized buffer.
266+
267+
This method never returns <see cref="P:System.Span`1.Empty" />, but it throws an <see cref="T:System.OutOfMemoryException" /> if the requested buffer size is not available.
268+
269+
You must request a new buffer after calling <xref:System.IO.Pipelines.PipeWriter.Advance(System.Int32)> to continue writing more data; you cannot write to a previously acquired buffer.
270+
271+
]]></format>
272+
</remarks>
273+
<exception cref="T:System.OutOfMemoryException">The requested buffer size is not available.</exception>
252274
<inheritdoc />
253275
</Docs>
254276
</Member>
@@ -308,4 +330,4 @@
308330
</Docs>
309331
</Member>
310332
</Members>
311-
</Type>
333+
</Type>

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,13 @@
3737
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
3838
</Parameters>
3939
<Docs>
40-
<param name="source">To be added.</param>
41-
<param name="destination">To be added.</param>
42-
<param name="cancellationToken">To be added.</param>
43-
<summary>To be added.</summary>
44-
<returns>To be added.</returns>
40+
<param name="source">The stream from which the contents of the current stream will be copied.</param>
41+
<param name="destination">The writer to which the contents of the source stream will be copied.</param>
42+
<param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" />.</param>
43+
<summary>Asynchronously reads the bytes from the <see cref="T:System.IO.Stream" /> and writes them to the specified <see cref="T:System.IO.Pipelines.PipeWriter" />, using a cancellation token.</summary>
44+
<returns>A task that represents the asynchronous copy operation.</returns>
4545
<remarks>To be added.</remarks>
4646
</Docs>
4747
</Member>
4848
</Members>
49-
</Type>
49+
</Type>

0 commit comments

Comments
 (0)