Skip to content

Commit 85f4376

Browse files
MSDN-WhiteKnightRon Petrusha
MSDN-WhiteKnight
authored and
Ron Petrusha
committed
Add documentation for non-generic ValueTask (#2608)
* Update ValueTask.xml Based on - Source code comments: https://github.com/dotnet/corefx/blob/b2097cbdcb26f7f317252334ddcce101a20b7f3d/src/Common/src/CoreLib/System/Threading/Tasks/ValueTask.cs#L31 - ValueTask<TResult> documentation: https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask-1?view=netcore-3.0 - Understanding the Whys, Whats, and Whens of ValueTask: https://devblogs.microsoft.com/dotnet/understanding-the-whys-whats-and-whens-of-valuetask/ * fix typo * Removed superfluous quotation mark * Corrected misformed cref * Apply suggestions from code review Co-Authored-By: Ron Petrusha <[email protected]> * Address requested changes Add remarks for equality methods and operators
1 parent bc22c16 commit 85f4376

File tree

1 file changed

+103
-45
lines changed

1 file changed

+103
-45
lines changed

‎xml/System.Threading.Tasks/ValueTask.xml‎

Lines changed: 103 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,29 @@
3333
</Attribute>
3434
</Attributes>
3535
<Docs>
36-
<summary>To be added.</summary>
37-
<remarks>To be added.</remarks>
36+
<summary>Provides an awaitable result of an asynchronous operation.</summary>
37+
<remarks>
38+
<format type="text/markdown"><![CDATA[
39+
40+
## Remarks
41+
A `ValueTask` instance may either be awaited or converted to a <xref:System.Threading.Tasks.Task> using <xref:System.Threading.Tasks.ValueTask.AsTask%2A>. A `ValueTask` instance may only be awaited once, and consumers may not call <xref:System.Threading.Tasks.ValueTask.GetAwaiter> until the instance has completed. If these limitations are unacceptable, convert the `ValueTask` to a <xref:System.Threading.Tasks.Task> by calling <xref:System.Threading.Tasks.ValueTask.AsTask%2A>.
42+
43+
The following operations should never be performed on a `ValueTask` instance:
44+
45+
- Awaiting the instance multiple times.
46+
- Calling <xref:System.Threading.Tasks.ValueTask.AsTask%2A> multiple times.
47+
- Using more than one of these techniques to consume the instance.
48+
49+
If you do any of the above, the results are undefined.
50+
51+
A `ValueTask` is a structure that can wrap either a <xref:System.Threading.Tasks.Task> or a <xref:System.Threading.Tasks.Sources.IValueTaskSource> instance. Returning a `ValueTask` that wraps a <xref:System.Threading.Tasks.Sources.IValueTaskSource> instance from an asynchronous method enables high-throughput applications to avoid allocations by using a pool of reusable <xref:System.Threading.Tasks.Sources.IValueTaskSource> objects. For more information, see [Understanding the Whys, Whats, and Whens of ValueTask](https://devblogs.microsoft.com/dotnet/understanding-the-whys-whats-and-whens-of-valuetask/).
52+
53+
Using a `ValueTask` instead of a <xref:System.Threading.Tasks.Task> introduces some overhead. Because `ValueTask` is a structure with multiple fields, returning it from the method results in copying more data compared to returning a single <xref:System.Threading.Tasks.Task> reference. As such, the default choice for any asynchronous method that does not return a result should be to return a <xref:System.Threading.Tasks.Task>. Only if performance analysis proves it worthwhile should a `ValueTask` be used instead of a <xref:System.Threading.Tasks.Task>. The <xref:System.Threading.Tasks.Task.CompletedTask?displayProperty=nameWithType> property should be used to hand back a successfully completed singleton in the case where a method returning a <xref:System.Threading.Tasks.Task> completes synchronously and successfully.
54+
55+
> [!NOTE]
56+
> The use of the `ValueTask` type is supported starting with C# 7.0 and is not supported by any version of Visual Basic.
57+
]]></format>
58+
</remarks>
3859
</Docs>
3960
<Members>
4061
<Member MemberName=".ctor">
@@ -59,8 +80,8 @@
5980
<Parameter Name="task" Type="System.Threading.Tasks.Task" />
6081
</Parameters>
6182
<Docs>
62-
<param name="task">To be added.</param>
63-
<summary>To be added.</summary>
83+
<param name="task">The task that represents the operation.</param>
84+
<summary>Initializes a new instance of the <see cref="T:System.Threading.Tasks.ValueTask" /> class using the supplied task that represents the operation.</summary>
6485
<remarks>To be added.</remarks>
6586
</Docs>
6687
</Member>
@@ -88,9 +109,9 @@
88109
<Parameter Name="token" Type="System.Int16" />
89110
</Parameters>
90111
<Docs>
91-
<param name="source">To be added.</param>
92-
<param name="token">To be added.</param>
93-
<summary>To be added.</summary>
112+
<param name="source">An object that represents the operation.</param>
113+
<param name="token">An opaque value that is passed through to the <see cref="T:System.Threading.Tasks.Sources.IValueTaskSource"/></param>
114+
<summary>Initializes a new instance of the <see cref="T:System.Threading.Tasks.ValueTask" /> class using the supplied <see cref="T:System.Threading.Tasks.Sources.IValueTaskSource" /> object that represents the operation.</summary>
94115
<remarks>To be added.</remarks>
95116
</Docs>
96117
</Member>
@@ -118,8 +139,8 @@
118139
</ReturnValue>
119140
<Parameters />
120141
<Docs>
121-
<summary>To be added.</summary>
122-
<returns>To be added.</returns>
142+
<summary>Retrieves a <see cref="T:System.Threading.Tasks.Task" /> object that represents this <see cref="T:System.Threading.Tasks.ValueTask" />.</summary>
143+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> object that is wrapped in this <see cref="T:System.Threading.Tasks.ValueTask" /> if one exists, or a new <see cref="T:System.Threading.Tasks.Task" /> object that represents the result.</returns>
123144
<remarks>To be added.</remarks>
124145
</Docs>
125146
</Member>
@@ -149,9 +170,10 @@
149170
<Parameter Name="continueOnCapturedContext" Type="System.Boolean" />
150171
</Parameters>
151172
<Docs>
152-
<param name="continueOnCapturedContext">To be added.</param>
153-
<summary>To be added.</summary>
154-
<returns>To be added.</returns>
173+
<param name="continueOnCapturedContext">
174+
<see langword="true" /> to attempt to marshal the continuation back to the captured context; otherwise, <see langword="false" />.</param>
175+
<summary>Configures an awaiter for this value.</summary>
176+
<returns>The configured awaiter.</returns>
155177
<remarks>To be added.</remarks>
156178
</Docs>
157179
</Member>
@@ -181,10 +203,18 @@
181203
<Parameter Name="obj" Type="System.Object" />
182204
</Parameters>
183205
<Docs>
184-
<param name="obj">To be added.</param>
185-
<summary>To be added.</summary>
186-
<returns>To be added.</returns>
187-
<remarks>To be added.</remarks>
206+
<param name="obj">The object to compare with the current object.</param>
207+
<summary>Determines whether the specified object is equal to the current <see cref="T:System.Threading.Tasks.ValueTask" /> instance.</summary>
208+
<returns>
209+
<see langword="true" /> if the specified object is equal to the current object; otherwise, <see langword="false" />.</returns>
210+
<remarks>
211+
<format type="text/markdown"><![CDATA[
212+
213+
## Remarks
214+
Two <xref:System.Threading.Tasks.ValueTask> instances are equal when they wrap the same <xref:System.Threading.Tasks.Task> or the same pair of the <xref:System.Threading.Tasks.Sources.IValueTaskSource> object and the token.
215+
216+
]]></format>
217+
</remarks>
188218
</Docs>
189219
</Member>
190220
<Member MemberName="Equals">
@@ -216,10 +246,18 @@
216246
<Parameter Name="other" Type="System.Threading.Tasks.ValueTask" />
217247
</Parameters>
218248
<Docs>
219-
<param name="other">To be added.</param>
220-
<summary>To be added.</summary>
221-
<returns>To be added.</returns>
222-
<remarks>To be added.</remarks>
249+
<param name="other">The object to compare with the current object.</param>
250+
<summary>Determines whether the specified <see cref="T:System.Threading.Tasks.ValueTask" /> object is equal to the current <see cref="T:System.Threading.Tasks.ValueTask" /> object.</summary>
251+
<returns>
252+
<see langword="true" /> if the specified object is equal to the current object; otherwise, <see langword="false" />.</returns>
253+
<remarks>
254+
<format type="text/markdown"><![CDATA[
255+
256+
## Remarks
257+
Two <xref:System.Threading.Tasks.ValueTask> instances are equal when they wrap the same <xref:System.Threading.Tasks.Task> or the same pair of the <xref:System.Threading.Tasks.Sources.IValueTaskSource> object and the token.
258+
259+
]]></format>
260+
</remarks>
223261
</Docs>
224262
</Member>
225263
<Member MemberName="GetAwaiter">
@@ -246,8 +284,8 @@
246284
</ReturnValue>
247285
<Parameters />
248286
<Docs>
249-
<summary>To be added.</summary>
250-
<returns>To be added.</returns>
287+
<summary>Creates an awaiter for this value.</summary>
288+
<returns>The awaiter.</returns>
251289
<remarks>To be added.</remarks>
252290
</Docs>
253291
</Member>
@@ -275,8 +313,8 @@
275313
</ReturnValue>
276314
<Parameters />
277315
<Docs>
278-
<summary>To be added.</summary>
279-
<returns>To be added.</returns>
316+
<summary>Returns the hash code for this instance.</summary>
317+
<returns>The hash code for the current object.</returns>
280318
<remarks>To be added.</remarks>
281319
</Docs>
282320
</Member>
@@ -303,8 +341,9 @@
303341
<ReturnType>System.Boolean</ReturnType>
304342
</ReturnValue>
305343
<Docs>
306-
<summary>To be added.</summary>
307-
<value>To be added.</value>
344+
<summary>Gets a value that indicates whether this object represents a canceled operation.</summary>
345+
<value>
346+
<see langword="true" /> if this object represents a canceled operation; otherwise, <see langword="false" />.</value>
308347
<remarks>To be added.</remarks>
309348
</Docs>
310349
</Member>
@@ -331,8 +370,9 @@
331370
<ReturnType>System.Boolean</ReturnType>
332371
</ReturnValue>
333372
<Docs>
334-
<summary>To be added.</summary>
335-
<value>To be added.</value>
373+
<summary>Gets a value that indicates whether this object represents a completed operation.</summary>
374+
<value>
375+
<see langword="true" /> if this object represents a completed operation; otherwise, <see langword="false" />.</value>
336376
<remarks>To be added.</remarks>
337377
</Docs>
338378
</Member>
@@ -359,8 +399,9 @@
359399
<ReturnType>System.Boolean</ReturnType>
360400
</ReturnValue>
361401
<Docs>
362-
<summary>To be added.</summary>
363-
<value>To be added.</value>
402+
<summary>Gets a value that indicates whether this object represents a successfully completed operation.</summary>
403+
<value>
404+
<see langword="true" /> if this object represents a successfully completed operation; otherwise, <see langword="false" />.</value>
364405
<remarks>To be added.</remarks>
365406
</Docs>
366407
</Member>
@@ -387,8 +428,9 @@
387428
<ReturnType>System.Boolean</ReturnType>
388429
</ReturnValue>
389430
<Docs>
390-
<summary>To be added.</summary>
391-
<value>To be added.</value>
431+
<summary>Gets a value that indicates whether this object represents a failed operation.</summary>
432+
<value>
433+
<see langword="true" /> if this object represents a failed operation; otherwise, <see langword="false" />.</value>
392434
<remarks>To be added.</remarks>
393435
</Docs>
394436
</Member>
@@ -419,11 +461,19 @@
419461
<Parameter Name="right" Type="System.Threading.Tasks.ValueTask" />
420462
</Parameters>
421463
<Docs>
422-
<param name="left">To be added.</param>
423-
<param name="right">To be added.</param>
424-
<summary>To be added.</summary>
425-
<returns>To be added.</returns>
426-
<remarks>To be added.</remarks>
464+
<param name="left">The first value to compare.</param>
465+
<param name="right">The second value to compare.</param>
466+
<summary>Compares two <see cref="T:System.Threading.Tasks.ValueTask" /> values for equality.</summary>
467+
<returns>
468+
<see langword="true" /> if the two <see cref="T:System.Threading.Tasks.ValueTask" /> values are equal; otherwise, <see langword="false" />.</returns>
469+
<remarks>
470+
<format type="text/markdown"><![CDATA[
471+
472+
## Remarks
473+
Two <xref:System.Threading.Tasks.ValueTask> instances are equal when they wrap the same <xref:System.Threading.Tasks.Task> or the same pair of the <xref:System.Threading.Tasks.Sources.IValueTaskSource> object and the token.
474+
475+
]]></format>
476+
</remarks>
427477
</Docs>
428478
</Member>
429479
<Member MemberName="op_Inequality">
@@ -453,11 +503,19 @@
453503
<Parameter Name="right" Type="System.Threading.Tasks.ValueTask" />
454504
</Parameters>
455505
<Docs>
456-
<param name="left">To be added.</param>
457-
<param name="right">To be added.</param>
458-
<summary>To be added.</summary>
459-
<returns>To be added.</returns>
460-
<remarks>To be added.</remarks>
506+
<param name="left">The first value to compare.</param>
507+
<param name="right">The second value to compare.</param>
508+
<summary>Determines whether two <see cref="T:System.Threading.Tasks.ValueTask" /> values are unequal.</summary>
509+
<returns>
510+
<see langword="true" /> if the two <see cref="T:System.Threading.Tasks.ValueTask" /> values are not equal; otherwise, <see langword="false" />.</returns>
511+
<remarks>
512+
<format type="text/markdown"><![CDATA[
513+
514+
## Remarks
515+
Two <xref:System.Threading.Tasks.ValueTask> instances are equal when they wrap the same <xref:System.Threading.Tasks.Task> or the same pair of the <xref:System.Threading.Tasks.Sources.IValueTaskSource> object and the token.
516+
517+
]]></format>
518+
</remarks>
461519
</Docs>
462520
</Member>
463521
<Member MemberName="Preserve">
@@ -484,10 +542,10 @@
484542
</ReturnValue>
485543
<Parameters />
486544
<Docs>
487-
<summary>To be added.</summary>
488-
<returns>To be added.</returns>
545+
<summary>Gets a <see cref="T:System.Threading.Tasks.ValueTask"/> that may be used at any point in the future.</summary>
546+
<returns>The preserved <see cref="T:System.Threading.Tasks.ValueTask"/>.</returns>
489547
<remarks>To be added.</remarks>
490548
</Docs>
491549
</Member>
492550
</Members>
493-
</Type>
551+
</Type>

0 commit comments

Comments
 (0)