dotnet / dotnet/dotnet-api-docs
Remarks for Task should be modernized
- 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
Assessment
This issue has not been assessed yet.