Updated C# and .NET docs supplement (markdown)

James Groom 2023-09-27 01:03:36 +10:00
parent 0fbef68422
commit 69cc869a44
1 changed files with 11 additions and 0 deletions

@ -3,6 +3,17 @@ To save us repeating our complaints about the lack of proper documentation under
Contribute to [the official docs](https://github.com/dotnet/docs) if possible.
## Const (byte/primitive) arrays
Not allowed as either array nor `Span`, despite string literals now effectively having the type `const ReadOnlySpan<char>`,
and despite arrays of primitive types being [allowed for attribute parameters](https://learn.microsoft.com/en-us/dotnet/csharp/advanced-topics/reflection-and-attributes/attribute-tutorial#add-attributes-to-code) since forever.
Use `static readonly` and weep.
## Const structs
Not allowed, even if they meet the [criteria for unmanaged types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/unmanaged-types) and are littered with [explicit layout attributes](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/customize-struct-marshalling).
First-class'd structs are no different, so fields of type `ValueTuple`, `Range`, and as noted above, `Span` cannot be `const`.
## Deceptive collection type names
`IReadOnly{Collection,Dictionary,List,Set}` are for getting read-only views of the collections that implement them. They do not mean the collection is immutable (there are [separate classes](https://learn.microsoft.com/en-us/dotnet/api/system.collections.immutable?view=net-6.0) for that). The same goes for `ReadOnlySpan`.