dotnet / dotnet/dotnet-api-docs

ValueType remarks needs improvement

Open
#2,348 0 comments 0 reactions 0 assignees View on GitHub
area-System.Runtime Pri3 untriaged
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

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.