Add additional examples.

Add three more examples to illustrate the ref safety rules for scoped ref. These highlight the potential issues with an unscoped ref.

Author: BillWagner

standard/structs.md

@@ -1150,6 +1150,37 @@ The safe-context of an object initializer expression is the narrowest of:
 
 > *Note*: Another way of modeling this is to consider any argument to a member initializer that can be assigned to the receiver as being an argument to the constructor. *end note*
 
+> *Example*: The following illustrates how an object initializer narrows the safe-context of the resulting value:
+>
+> <!-- Example: {template:"standalone-lib-without-using", name:"ObjectInitializerSafeContext", expectedErrors:["CS8352"]} -->
+> ```csharp
+> using System;
+>
+> ref struct S
+> {
+>     public Span<int> Field;
+>     public S(ref int i) { }
+> }
+>
+> class C
+> {
+>     static S Example()
+>     {
+>         Span<int> stackSpan = stackalloc int[42];
+>         int i = 0;
+>
+>         // safe-context is narrowest of:
+>         //   constructor safe-context (caller-context) and
+>         //   RHS of Field assignment (stackSpan: function-member)
+>         // = function-member
+>         var x = new S(ref i) { Field = stackSpan };
+>         return x; // Error: x has safe-context of function-member
+>     }
+> }
+> ```
+>
+> *end example*
+
 #### 16.5.15.7 stackalloc
 
 The result of a stackalloc expression has safe-context of function-member.

standard/variables.md

@@ -1364,6 +1364,31 @@ For a parameter `p`:
 
 When a parameter is annotated with `[UnscopedRef]` ([§UnscopedRefAttribute](attributes.md#unscopedrefattribute-the-unscopedref-attribute)), its ref-safe-context is widened by one level from its default: function-member becomes return-only, and return-only becomes caller-context.
 
+> *Example*: The following illustrates how the implicit `this` parameter of a struct instance method is `scoped ref` (ref-safe-context of *function-member*), and how `[UnscopedRef]` widens it to *return-only*, enabling ref returns of fields:
+>
+> <!-- Example: {template:"standalone-lib-without-using", name:"ParameterRefSafeContext", expectedErrors:["CS8170"]} -->
+> ```csharp
+> using System.Diagnostics.CodeAnalysis;
+>
+> struct S
+> {
+>     private int _field;
+>
+>     // Error: ref-safe-context of `this` is function-member,
+>     // so ref-safe-context of `_field` is also function-member,
+>     // which does not satisfy the return-only requirement.
+>     public ref int Bad() => ref _field;
+>
+>     // OK: [UnscopedRef] widens `this` from function-member to
+>     // return-only, so `_field` also has ref-safe-context of
+>     // return-only, satisfying the ref return requirement.
+>     [UnscopedRef]
+>     public ref int Good() => ref _field;
+> }
+> ```
+>
+> *end example*
+
 #### 9.7.2.4 Field ref safe context
 
 For a variable designating a reference to a field, `e.F`:
@@ -1481,3 +1506,29 @@ Any other difference with respect to `scoped` or `[UnscopedRef]` between the bas
 The `scoped` modifier and `[UnscopedRef]` attribute do not affect hiding.
 
 Overloads shall not differ only on `scoped` or `[UnscopedRef]`.
+
+> *Example*: The following illustrates valid and invalid scope variance in overrides:
+>
+> <!-- Example: {template:"standalone-lib-without-using", name:"ParameterScopeVariance", expectedErrors:["CS0111"]} -->
+> ```csharp
+> using System;
+>
+> class Base
+> {
+>     public virtual void M(ref Span<int> x) { }
+> }
+>
+> class Derived : Base
+> {
+>     // OK: adds scoped to a ref parameter
+>     public override void M(scoped ref Span<int> x) { }
+> }
+>
+> class C
+> {
+>     void N(Span<int> x) { }
+>     void N(scoped Span<int> x) { }  // Error: overloads differ only on scoped
+> }
+> ```
+>
+> *end example*