reorg record-related text

Author: RexJaeschke

standard/structs.md

@@ -38,25 +38,16 @@ record_struct_body
     ;
 ```
 
-A *struct_declaration* is for either a ***non-record struct*** or a ***record struct***.
+There are two kinds of struct: ***non-record struct***, as declared by *non_record_struct_declaration*, and ***record struct***, as declared by  *record_struct_declaration*. A non-record struct is the kind of struct that C# has supported since the language’s inception. Record structs were added much later and are discussed in §record-structs. The differences between the two kinds are discussed in §record-struct-diffs.
 
 A *non_record_struct_declaration* consists of an optional set of *attributes* ([§23](attributes.md#23-attributes)), followed by an optional set of *struct_modifier*s ([§16.2.2](structs.md#1622-struct-modifiers)), followed by an optional `ref` modifier ([§16.2.3](structs.md#1623-ref-modifier)), followed by an optional partial modifier ([§15.2.7](classes.md#1527-partial-type-declarations)), followed by the keyword `struct` and an *identifier* that names the struct, followed by an optional *type_parameter_list* specification ([§15.2.3](classes.md#1523-type-parameters)), followed by an optional *struct_interfaces* specification ([§16.2.5](structs.md#1625-struct-interfaces)), followed by an optional *type_parameter_constraints-clauses* specification ([§15.2.5](classes.md#1525-type-parameter-constraints)), followed by a *struct_body* ([§16.2.6](structs.md#1626-struct-body)), optionally followed by a semicolon.
 
-A *record_struct_declaration* consists of an optional set of *attributes* ([§23](attributes.md#23-attributes)), followed by an optional set of *struct_modifier*s ([§16.2.2](structs.md#1622-struct-modifiers)), followed by an optional partial modifier ([§15.2.7](classes.md#1527-partial-type-declarations)), followed by the keyword `record`, followed by the keyword `struct` and an *identifier* that names the struct, followed by an optional *type_parameter_list* specification ([§15.2.3](classes.md#1523-type-parameters)), followed by an optional *delimited_parameter_list* specification ([§15.2.1](classes.md#1521-general)), followed by an optional *struct_interfaces* specification ([§16.2.5](structs.md#1625-struct-interfaces)), followed by an optional *type_parameter_constraints-clauses* specification ([§15.2.5](classes.md#1525-type-parameter-constraints)), followed by a *record_struct_body*.
-
 A *struct_declaration* shall not supply *type_parameter_constraints_clause*s unless it also supplies a *type_parameter_list*.
 
 A *struct_declaration* that supplies a *type_parameter_list* is a generic struct declaration. Additionally, any struct nested inside a generic class declaration or a generic struct declaration is itself a generic struct declaration, since type arguments for the containing type shall be supplied to create a constructed type ([§8.4](types.md#84-constructed-types)).
 
 A *non_record_struct_declaration* that includes a `ref` modifier shall not have a *struct_interfaces* part.
 
-A *record_struct_declaration* having a *delimited_parameter_list* declares a ***positional record struct***.
-
-At most only one *record_struct_declaration* containing `partial` may provide a *delimited_parameter_list*.
-
-The parameters in *delimited_parameter_list* shall not have `ref`, `out` or `this` modifiers; however, `in` and `params` modifiers are permitted.
-For a *record_struct_declaration*, the *record_struct_body*s `{}`, `{};`, and `;` are equivalent. They all indicate that the only members are those synthesized by the compiler (§synth-members).
-
 ### 16.2.2 Struct modifiers
 
 A *struct_declaration* may optionally include a sequence of *struct_modifier*s:
@@ -145,7 +136,7 @@ struct_body
 
 ### 16.3.1 General
 
-The members of a struct consist of the members introduced by its *struct_member_declaration*s and the members inherited from the type `System.ValueType`. For a record struct, the member set also includes the synthesized members generated by the compiler (§synth-members).
+The members of a struct consist of the members introduced by its *struct_member_declaration*s and the members inherited from the type `System.ValueType`.
 
 ```ANTLR
 struct_member_declaration
@@ -169,10 +160,6 @@ struct_member_declaration
 
 Except for the differences noted in [§16.4](structs.md#164-class-and-struct-differences), the descriptions of class members provided in [§15.3](classes.md#153-class-members) through [§15.12](classes.md#1512-static-constructors) apply to struct members as well.
 
-It is an error for a member of a record struct to be named `Clone`.
-
-It is an error for an instance field of a record struct to have an unsafe type.
-
 ### 16.3.2 Readonly members
 
 An instance member definition or accessor of an instance property, indexer, or event that includes the `readonly` modifier has the following restrictions:
@@ -213,15 +200,58 @@ An instance member definition or accessor of an instance property, indexer, or e
 >
 > The `readonly` method `AddMessage` can change the state of a message list. The `InitializeMessages` member can clear and re-initialize the list of messages. In the case of `AddMessage`, the `readonly` modifier is valid. In the case of `InitializeMessages`, adding the `readonly` modifier is invalid. *end example*
 
-## §synth-members Synthesized record struct members
+## §record-structs Record structs
+
+### §record-structs-general General
+
+A record struct is a specialized value type that is optimized for storing data rather than behavior. It provides built-in functionality that would normally require significant “boilerplate” code in a non-record struct, such as value-based equality and easy immutability.
+
+```ANTLR
+record_struct_declaration
+    : attributes? struct_modifier* 'partial'? 'record' 'struct'
+      identifier type_parameter_list? delimited_parameter_list? struct_interfaces?
+      type_parameter_constraints_clause* record_struct_body
+    ;
+```
+
+A *record_struct_declaration* consists of an optional set of *attributes* ([§23](attributes.md#23-attributes)), followed by an optional set of *struct_modifier*s ([§16.2.2](structs.md#1622-struct-modifiers)), followed by an optional partial modifier ([§15.2.7](classes.md#1527-partial-type-declarations)), followed by the keyword `record`, followed by the keyword `struct` and an *identifier* that names the struct, followed by an optional *type_parameter_list* specification ([§15.2.3](classes.md#1523-type-parameters)), followed by an optional *delimited_parameter_list* specification ([§15.6.2.1](standard/classes.md#15621-general)), followed by an optional *struct_interfaces* specification ([§16.2.5](structs.md#1625-struct-interfaces)), followed by an optional *type_parameter_constraints-clauses* specification ([§15.2.5](classes.md#1525-type-parameter-constraints)), followed by a *record_struct_body*.
+
+A *record_struct_declaration* having a *delimited_parameter_list* declares a ***positional record struct***.
+
+At most only one *record_struct_declaration* containing `partial` may provide a *delimited_parameter_list*.
+
+The parameters in *delimited_parameter_list* shall not have `ref`, `out` or `this` modifiers; however, `in` and `params` modifiers are permitted.
 
-### §synth-members-general General
+### §record-structs-members Struct members
+
+For a record struct, as well as those members identified by [§16.3](structs.md#16.3-struct-members), the member set includes the synthesized members generated by the compiler (§synth-members).
+
+It is an error for a member of a record struct to be named `Clone`.
+
+It is an error for an instance field of a record struct to have an unsafe type.
+
+### §record-structs-body Record struct body
+
+The *record_struct_body* of a record struct defines the members of that struct.
+
+```ANTLR
+record_struct_body
+    : struct_body ';'?
+    | ';'
+    ;
+```
+
+For a *record_struct_declaration*, the *record_struct_body*s `{}`, `{};`, and `;` are equivalent. They all indicate that the only members are those synthesized by the compiler (§synth-members).
+
+### §synth-members Synthesized record struct members
+
+#### §synth-members-general General
 
 In the case of a record struct, members are synthesized unless a member with a “matching” signature is declared in the *record_struct_body* or an accessible concrete non-virtual member with a “matching” signature is inherited. Two members are considered matching if they have the same signature or would be considered “hiding” in an inheritance scenario. (See Signatures and overloading [§7.6](basic-concepts.md#76-signatures-and-overloading).)
 
 The synthesized members are described in the following subclauses.
 
-### §rec-struct-equalmem Equality members
+#### §rec-struct-equalmem Equality members
 
 The synthesized equality members are similar to those for a record class ([§15.16.2](classes.md#15162-equality-members)), except for the lack of `EqualityContract`, null checks, or inheritance.
 
@@ -301,7 +331,7 @@ The synthesized override of `GetHashCode()` shall return an `int` result of comb
 >
 > *end example*
 
-### §rec-struct-prtmem Printing members
+#### §rec-struct-prtmem Printing members
 
 A record struct includes a synthesized method equivalent to the following:
 
@@ -388,15 +418,15 @@ This method performs the following tasks:
 >
 > *end example*
 
-### §rec-struct-pos-mem Positional record struct members
+#### §rec-struct-pos-mem Positional record struct members
 
-#### §rec-struct-pos-mem-gen General
+##### §rec-struct-pos-mem-gen General
 
 As well as providing the members described in the preceding subclauses, positional record structs ([§16.2.1](structs.md#1621-general)) synthesize additional members with the same conditions as the other members, as described in the following subclauses.
 
-#### §rec-struct-pos-mem-pricon Primary constructor
+##### §rec-struct-pos-mem-pricon Primary constructor
 
-A record struct has a public constructor whose signature corresponds to the value parameters of the type declaration. This is called the primary constructor for the type. It is an error to have a primary constructor and a constructor with the same signature already present in the struct. If the type declaration does not include a *delimited_parameter_list*, no primary constructor is generated.
+A record struct with a *delimited_parameter_list* has a public constructor whose signature corresponds to the value parameters of the type declaration. This is called the primary constructor for the type. It is an error to have a primary constructor and a constructor with the same signature already present in the struct. If the type declaration does not include a *delimited_parameter_list*, no primary constructor is generated.
 
 > <!-- Example: {template:"standalone-lib", name:"RecordStructPrimaryConstructor1", expectedErrors:["CS0111","CS8862"]} -->
 > ```csharp
@@ -433,7 +463,7 @@ The definite assignment rules for struct instance constructors apply to the prim
 > }
 > ```
 
-#### §rec-struct-pos-mem-props Properties
+##### §rec-struct-pos-mem-props Properties
 
 For each parameter of a *delimited_parameter_list* that has the same name and type as an explicitly declared instance field, the remainder of this subclause does not apply.
 
@@ -455,13 +485,24 @@ For a record struct:
 
 - Attributes may be applied to the synthesized auto-property and its backing field by using `property:` or `field:` targets for attributes syntactically applied to the corresponding record struct parameter.
 
-#### §rec-struct-pos-mem-decon Deconstruct
+##### §rec-struct-pos-mem-decon Deconstruct
 
 A positional record struct with at least one parameter synthesizes a public `void`-returning instance method called `Deconstruct` with an out parameter declaration for each parameter of the primary constructor declaration. Each parameter of `Deconstruct` has the same type as the corresponding parameter of the primary
 constructor declaration. The body of the method assigns each parameter of the Deconstruct method to the value from an instance member access to a member of the same name.
 If the instance members accessed in the body do not include a property with a non-`readonly` `get` accessor, then the synthesized `Deconstruct` method is `readonly`.
 The method can be declared explicitly. It is an error if the explicit declaration does not match the expected signature or accessibility, or is static.
 
+## §record-struct-diffs Record struct and non-record struct differences
+
+A record struct differs from a non-record struct in several important ways:
+
+- It is declared using the keywords `record struct` instead of just `struct`.
+- It has a number of members generated for it by the implementation.
+- Its declaration may contain a *delimited_parameter_list* having zero or more parameters, which results in the generation of a primary constructor having those parameters. For each parameter, the implementation shall provide field-like storage and a property with get and init accessor. A `Deconstruct` method is also provided.
+- Its record struct body may be omitted.
+- It shall not have a member called `Clone`.
+- It shall not have an instance field with an unsafe type.
+
 ## 16.4 Class and struct differences
 
 ### 16.4.1 General