dotnet
"Main()" documentation should not detail hidden implementation from compiler
Describe the issue or suggestion
I created this issue to follow up on this PR comment posted by @richlander :
I'm not sure it makes sense to document all this detail. It's an implementation detail. The compiler does plenty of codegen for you. This feels similar.
In the documentation Main() and command-line arguments, the chapter Async Main return values reveal the boilerplate added by the compiler.
This level of detail is appropriate for this basic documentation, because it overwhelms novice reader with advanced concepts.
I suggest to remove boilerplate detail, but explain the task returned by Main is awaited.
Sounds good. The existing structure of the topic doesn't make much sense to me. Even though I'm quite familiar with all of it, I still find the flow confusing. It's a forest for the trees problem.
I think we need a few things:
- A very simple and high-level discussion of Main and how it works.
- A similarly simple discussion of how Async Main changes things.
- A more detailed discussion of Main.
- A more detailed discussion of Async Main.
Note that everything is sort of glommed together currently, but then there is still a break out section for Async Main. Seems odd.
https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/program-structure/main-command-line#async-main-return-values
I'm happy to work with you on a branch.
