Description
[Enter feedback here]
In my opinion, the documentation on this page is not clear. It is making hard for developers to understand how the nullable contexts works. It needs to be organized a bit more logically.
First the page have to specify what problem is with examples.
Then how it is fixed, why there are annotation and warning contexts, what are they and why developer need to care about them. Also more examples here. As the page stands now the possible values enable and disable are given even before we can understand what they mean.
The details of the values for the context and their combinations should be provided at the end, with more examples.
More in detail. These are some point that I find confusing:
- In the first section, it is not made clear if this warnings provided by the compiler are the default behaviour or if they happen when enabling annotations, warnings or both.
- The intro is jumping between the previous and the new compiler behaviour explanation in an unclear way, I would use past and present tenses and the words "previous/old" and "new".
- It is not clear how a type can become oblivious or unknown. An example would be useful.
- The section Nullable contexts section is not providing an actual definition of both context. What is the intention to provide both?
- It is mentioned that the forgiving operator cannot be used in a disabled annotation context. I can use the operator without any error, so I guess it is an error.
- It is mentioned that the compiler will show warnings when the annotation context is enabled. Does this happen even if the warning context is disabled? It is not very clear.
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
- ID: a690704d-da32-dca7-ea3e-66b84fb1d00d
- Version Independent ID: 11f314de-dd3a-362e-b2bb-d0a2133cfc7b
- Content: Nullable reference types
- Content Source: docs/csharp/nullable-references.md
- Product: dotnet-csharp
- Technology: csharp-null-safety
- GitHub Login: @BillWagner
- Microsoft Alias: wiwagn