dotnet / dotnet/dotnet-api-docs
ValueType remarks needs improvement
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
In [System.ValueType](https://docs.microsoft.com/en-us/dotnet/api/system.valuetype?view=netframework-4.8#remarks) remarks:
>Data types are separated into value types and reference types. Value types are either stack-allocated or allocated inline in a structure. Reference types are heap-allocated.
This statement implies that the main distinction between value and reference types is their allocation mechanics, which is inaccurate and inconsistent with [Common Type System](https://docs.microsoft.com/en-us/dotnet/standard/base-types/common-type-system#types-in-net) article in .NET Guide. The allocation options for value types are beyond just "on stack" and "inline in a structure", and stack allocation is considered only implementation detail anyway.
I think, System.ValueType documentation should explain value type distinction similarly to Common Type System article, by the nature of the variable data and the meaning of assignment operation. The mention of allocation mechanics should be either removed, or reworded to reflect more clearly that it's just examples. (The "_inline in a structure_" should be then replaced with "_inline in an object_", because there's nothing special in inlining value type inside structure compared to class.) Also, some conceptual article link could be added into "see also" section, maybe Common Type System mentioned above, or C# reference article about value types.
Contributor guide
Assessment
This issue has not been assessed yet.