Review and update ref fields

Add attribite, update examples, add a few prose areas.

Author: BillWagner

standard/attributes.md

@@ -1258,6 +1258,10 @@ It is an error to use `[UnscopedRef]` on
 
 See §scoped-modifier for more information.
 
+### §ScopedRefAttribute The ScopedRef attribute
+
+The name `System.Runtime.CompilerServices.ScopedRefAttribute` is reserved for compiler use. The compiler emits this attribute on a parameter when the parameter's `scoped` annotation differs from its default state, in order to encode the `scoped` modifier (§scoped-modifier) in metadata. This attribute is not permitted in source.
+
 ### 23.5.8 The EnumeratorCancellation attribute
 
 Specifies the parameter representing the `CancellationToken` for an asynchronous iterator ([§15.15](classes.md#1515-synchronous-and-asynchronous-iterators)). The argument for this parameter shall be combined with the argument passed to `IAsyncEnumerable<T>.GetAsyncEnumerator(CancellationToken)`. This combined token shall be polled by `IAsyncEnumerator<T>.MoveNextAsync()` ([§15.15.5.2](classes.md#151552-advance-the-enumerator)). The tokens shall be combined into a single token as if by `CancellationToken.CreateLinkedTokenSource` and its `Token` property. The combined token will be canceled if either of the two source tokens are canceled. The combined token is seen as the argument to the asynchronous iterator method ([§15.15](classes.md#1515-synchronous-and-asynchronous-iterators)) in the body of that method.

standard/classes.md

@@ -1715,6 +1715,8 @@ The value of a field is obtained in an expression using a *simple_name* ([§12.8
 
 A field declaration that declares multiple fields is equivalent to multiple declarations of single fields with the same attributes, modifiers, and type.
 
+> *Note*: Inside a `ref struct`, a field may also be declared as a reference variable; see §Ref-Fields. *end note*
+
 > *Example*:
 >
 > <!-- Example: {template:"standalone-lib-without-using", name:"Fields1", ignoredWarnings:["CS0649"]} -->
@@ -2374,6 +2376,8 @@ It is a compile-time error to modify the value of an input parameter.
 
 > *Note*: The primary purpose of input parameters is for efficiency. When the type of a method parameter is a large struct (in terms of memory requirements), it is useful to be able to avoid copying the whole value of the argument when calling the method. Input parameters allow methods to refer to existing values in memory, while providing protection against unwanted changes to those values. *end note*
 
+An input parameter may carry the `scoped` modifier (§scoped-modifier) or the `[UnscopedRef]` attribute (§UnscopedRefAttribute).
+
 ##### 15.6.2.3.3 Reference parameters
 
 A parameter declared with a `ref` modifier is a ***reference parameter***. For definite-assignment rules, see [§9.2.6](variables.md#926-reference-parameters).
@@ -2437,14 +2441,18 @@ A parameter declared with a `ref` modifier is a ***reference parameter***. For d
 >
 > *end example*
 
-For a `struct` type, within an instance method, instance accessor ([§12.2.1](expressions.md#1221-general)), or instance constructor with a constructor initializer, the `this` keyword behaves exactly as a reference parameter of the struct type ([§12.8.14](expressions.md#12814-this-access)).
+For a `struct` type, within an instance method, instance accessor ([§12.2.1](expressions.md#1221-general)), or instance constructor with a constructor initializer, the `this` keyword behaves exactly as a reference parameter of the struct type ([§12.8.14](expressions.md#12814-this-access)). The `this` parameter of a struct instance method is implicitly `scoped ref` (§scoped-modifier).
+
+A reference parameter may carry the `scoped` modifier (§scoped-modifier) or the `[UnscopedRef]` attribute (§UnscopedRefAttribute).
 
 ##### 15.6.2.3.4 Output parameters
 
 A parameter declared with an `out` modifier is an ***output parameter***. For definite-assignment rules, see [§9.2.7](variables.md#927-output-parameters).
 
 A method declared as an optional partial method ([§15.6.9.2](classes.md#15692-optional-partial-methods)) shall not have output parameters.
 
+An output parameter is implicitly `scoped` (§scoped-modifier); the `[UnscopedRef]` attribute (§UnscopedRefAttribute) may be applied to widen its ref-safe-context.
+
 > *Note*: Output parameters are typically used in methods that produce multiple return values. *end note*
 <!-- markdownlint-disable MD028 -->
 

standard/structs.md

@@ -754,7 +754,12 @@ struct_field_declaration
 
 A *struct_field_declaration* without `ref`, `readonly ref`, or `ref readonly` is as described in [§15.5](classes.md#155-fields).
 
-A `ref` or `readonly ref` field is a reference variable and shall only be declared in a `ref` struct.
+A `ref` or `readonly ref` field is a reference variable and is subject to the following constraints:
+
+- It shall only be declared in a `ref struct`.
+- It shall not be declared `static`, `volatile`, or `const`.
+- Its type shall not itself be a `ref struct` type.
+- In a `readonly ref struct`, every `ref` field shall be declared `readonly ref` (it may additionally be declared `readonly ref readonly`).
 
 Consider the following ref struct declaration:
 

standard/variables.md

@@ -1498,6 +1498,53 @@ Consider the following declarations and their safe contexts:
 
 In this relationship the *ref-safe-context* of a value can never be wider than the *safe-context*.
 
+> *Example*: The following illustrates how `scoped` restricts the lifetime of a local and prevents it from escaping its enclosing function:
+>
+> <!-- Example: {template:"standalone-lib-without-using", name:"ScopedLocalCannotEscape", expectedErrors:["CS8352"]} -->
+> ```csharp
+> using System;
+>
+> class C
+> {
+>     static Span<int> Bad()
+>     {
+>         // Without `scoped`, the safe-context of `s` would be caller-context
+>         // because the right-hand side has safe-context of caller-context.
+>         // The `scoped` modifier forces the safe-context to function-member,
+>         // so `s` cannot be returned.
+>         scoped Span<int> s = default;
+>         return s;   // Error: s has safe-context of function-member
+>     }
+> }
+> ```
+>
+> *end example*
+
+> *Example*: The following illustrates how `scoped ref` on a parameter prevents the parameter from being captured by a constructed `ref struct` value that the method returns:
+>
+> <!-- Example: {template:"standalone-lib-without-using", name:"ScopedRefParameter", expectedErrors:["CS8347","CS8166"]} -->
+> ```csharp
+> ref struct RS
+> {
+>     public ref int RefField;
+>     public RS(ref int i) { RefField = ref i; }
+> }
+>
+> class C
+> {
+>     // `scoped ref` means `value` does not contribute ref-safe-context
+>     // to the return value. The `RS` constructor requires a ref argument
+>     // with ref-safe-context of caller-context, but `value` only contributes
+>     // function-member, so the call is rejected.
+>     static RS CreateWithoutCapture(scoped ref int value)
+>         => new RS(ref value);
+> }
+> ```
+>
+> *end example*
+
+In summary, two `ref` locations are implicitly `scoped`: the `this` parameter of a struct instance method, and every `out` parameter. See §9.7.2.3.
+
 ### §parameter-scope-variance Parameter scope variance
 
 The `scoped` modifier (§scoped-modifier) and `[UnscopedRef]` attribute (§UnscopedRefAttribute) on parameters affect overriding, interface implementation, and `delegate` conversion. The signature for an override, interface implementation, or `delegate` conversion may: