dotnet / dotnet/dotnet-api-docs

Remarks for Task should be modernized

Open
#8,138 1 comment 0 reactions 0 assignees View on GitHub
area-System.Threading.Tasks help wanted Pri3
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

[The remarks for `System.Threading.Tasks.Task`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task?view=net-6.0#remarks) seem to largely originate from the .Net Framework 4.0 era and could use some modernization. Some of the issues:

* The first thing mentioned is the `Task` constructor, the second is `StartNew()` and the fourth is `RunSynchronously()`. Those methods should be used only rarely, so they either should not be mentioned here at all, or at a much less prominent place.
* Most of the examples use `Wait()` and not `await`. I think this proportion should be reversed.
* When the example does use `await`, it does not explain it. For something so important to `Task`, I think a sentence with a link to the documentation for the keyword is the minimum.

Less important notes:

* There's quite a few `Main`s in the examples, so they could benefit from using top-level statements, assuming that's acceptable.
* The section *For debugger developers* documents implementation details and has incredibly niche audience. That might have been useful when .Net was not open source, but now debugger developers can read the source code, which [contains the same information](https://github.com/dotnet/runtime/blob/1f15373/src/libraries/System.Private.CoreLib/src/System/Threading/Tasks/Task.cs#L101-L110). So I think this section should be deleted here.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.