Task.WaitAsync description is wrong

[raffaeler]

Type of issue

Other (describe below)

Description

https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.waitasync?view=net-10.0#system-threading-tasks-task-waitasync(system-timespan-system-timeprovider)

The description states: "Gets a Task that will complete when this Task completes or when the specified timeout expires."
This information is wrong."

When a timeout argument is specified and the timeout expires, the Task.WaitAsync always throw a TimeoutException.

Please note that the description is wrong for all the other overloads.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.waitasync?view=net-10.0#system-threading-tasks-task-waitasync(system-timespan-system-timeprovider)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading.Tasks/Task.xml

Document Version Independent Id

4975978e-14a9-88e1-bec2-ea632d3c08d7

Platform Id

4fa165a2-05cd-c7d8-44d5-b6b3d0d66862

Article author

@dotnet-bot

[tannergooding]

The description is not incorrect. A task is considered completed (i.e. Task.IsCompleted returns true) if it is one of RanToCompletion (i.e. success), Faulted (i.e. threw an exception) or Canceled

As can be seen from the source (https://source.dot.net/#System.Private.CoreLib/src/libraries/System.Private.CoreLib/src/System/Threading/Tasks/Task.cs,69846ca916c930be) the method simply defers to the centralized helper, which then wraps a TimeoutException in a task if the timeout is 0 and otherwise creates a CancellationPromise which simply does TrySetException when the timeout is reached.

Any behavior on an exception being raised is not from the method itself, but by the calling of Wait() or an equivalent such as GetAwaiter().GetResult() which will propagate it back onto the thread that did this call. Calling these is a side effect of doing await task: https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/exception-handling-task-parallel-library

If you never await the task, then it will never throw which can be trivial seen from the following code:

var task = Task.Delay(1000).WaitAsync(TimeSpan.FromMilliseconds(0));
Console.WriteLine($"IsCompleted: {task.IsCompleted}");
Console.WriteLine($"IsFaulted: {task.IsFaulted}");
await task;

This propagation can also be suppressed by using ConfigureAwait

[raffaeler]

Thanks Tanner, your explanation is of course impeccable.
I find the description misleading anyway because it provides an information that is not specific to this method, but of the TPL in general.
I would instead underline the difference between awaiting with WaitAsync and WhenAny with a Task.Delay in the array.