Consolidated and revised the ref local reference (#35869)

* Consolidated and revised the ref local reference

* Fixed anchors in links

* Fix interactive snippet

Author: pkulikov

docs/csharp/advanced-topics/performance/index.md

@@ -103,4 +103,4 @@ Using these features to improve performance involves these tasks:
 - *Restrict modifications*: When a `struct` type is passed by reference, the called method could modify the state of the struct. You can replace the `ref` modifier with the `in` modifier to indicate that the argument can't be modified. You can also create `readonly struct` types or `struct` types with `readonly` members to provide more control over what members of a `struct` can be modified.
 - *Directly manipulate memory*: Some algorithms are most efficient when treating data structures as a block of memory containing a sequence of elements. The `Span` and `Memory` types provide safe access to blocks of memory.
 
-None of these techniques require `unsafe` code. Used wisely, you can get performance characteristics from safe code that was previously only possible by using unsafe techniques. You can try the techniques yourself in the tutorial on [reducing memory allocations](ref-tutorial.md)
+None of these techniques require `unsafe` code. Used wisely, you can get performance characteristics from safe code that was previously only possible by using unsafe techniques. You can try the techniques yourself in the tutorial on [reducing memory allocations](ref-tutorial.md).

docs/csharp/language-reference/keywords/ref.md

@@ -8,14 +8,15 @@ helpviewer_keywords:
   - "parameters [C#], ref"
   - "ref keyword [C#]"
 ---
-# ref (C# Reference)
+# ref (C# reference)
 
-The `ref` keyword indicates that a variable is a reference, or an alias for another object. It's used in five different contexts:
+You use the `ref` keyword in the following contexts:
 
 - In a method signature and in a method call, to pass an argument to a method by reference. For more information, see [Passing an argument by reference](#passing-an-argument-by-reference).
 - In a method signature, to return a value to the caller by reference. For more information, see [Reference return values](#reference-return-values).
-- In a member body, to indicate that a reference return value is stored locally as a reference that the caller intends to modify. Or to indicate that a local variable accesses another value by reference. For more information, see [Ref locals](#ref-locals).
-- In a `struct` declaration, to declare a `ref struct` or a `readonly ref struct`. For more information, see the [`ref struct`](../builtin-types/ref-struct.md) article.
+- In a declaration of a local variable, to declare a reference variable. For more information, see the [Reference variables](../statements/declarations.md#reference-variables) section of the [Declaration statements](../statements/declarations.md) article.
+- As the part of a [conditional ref expression](../operators/conditional-operator.md#conditional-ref-expression) or a [ref assignment operator](../operators/assignment-operator.md#ref-assignment).
+- In a `struct` declaration, to declare a `ref struct`. For more information, see the [`ref struct`](../builtin-types/ref-struct.md) article.
 - In a `ref struct` declaration, to declare that a field is a reference. See the [`ref` field](../builtin-types/ref-struct.md) article.
 
 ## Passing an argument by reference
@@ -90,45 +91,16 @@ public ref decimal GetCurrentPrice()
 return ref DecimalArray[0];
 ```
 
-In order for the caller to modify the object's state, the reference return value must be stored to a variable that is explicitly defined as a [ref local](#ref-locals).
+In order for the caller to modify the object's state, the reference return value must be stored to a variable that is explicitly defined as a [reference variable](../statements/declarations.md#reference-variables).
 
 Here's a more complete ref return example, showing both the method signature and method body.
 
 :::code language="csharp" source="snippets/RefParameterModifier.cs" id="SnippetFindReturningRef":::
 
-The called method may also declare the return value as `ref readonly` to return the value by reference, and enforce that the calling code can't modify the returned value. The calling method can avoid copying the returned value by storing the value in a local [ref readonly](#ref-readonly-locals) variable.
+The called method may also declare the return value as `ref readonly` to return the value by reference, and enforce that the calling code can't modify the returned value. The calling method can avoid copying the returned value by storing the value in a local `ref readonly` reference variable.
 
 For an example, see [A ref returns and ref locals example](#a-ref-returns-and-ref-locals-example).
 
-## Ref locals
-
-A ref local variable is used to refer to values returned using `return ref`. A ref local variable can't be initialized to a non-ref return value. In other words, the right-hand side of the initialization must be a reference. Any modifications to the value of the ref local are reflected in the state of the object whose method returned the value by reference.
-
-You define a ref local by using the `ref` keyword in two places:
-
-- Before the variable declaration.
-- Immediately before the call to the method that returns the value by reference.
-
-For example, the following statement defines a ref local value that is returned by a method named `GetEstimatedValue`:
-
-```csharp
-ref decimal estValue = ref Building.GetEstimatedValue();
-```
-
-You can access a value by reference in the same way. In some cases, accessing a value by reference increases performance by avoiding a potentially expensive copy operation. For example, the following statement shows how to define a ref local variable that is used to reference a value.
-
-```csharp
-ref VeryLargeStruct reflocal = ref veryLargeStruct;
-```
-
-In both examples the `ref` keyword must be used in both places, or the compiler generates error CS8172, "Can't initialize a by-reference variable with a value."
-
-The iteration variable of the `foreach` statement can be a ref local or ref readonly local variable. For more information, see the [foreach statement](../statements/iteration-statements.md#the-foreach-statement) article. You can reassign a ref local or ref readonly local variable with the [ref assignment operator](../operators/assignment-operator.md#ref-assignment).
-
-## Ref readonly locals
-
-A ref readonly local is used to refer to values returned by a method or property that has `ref readonly` in its signature and uses `return ref`. A `ref readonly` variable combines the properties of a `ref` local variable with a `readonly` variable: it's an alias to the storage it's assigned to, and it can't be modified.
-
 ## A ref returns and ref locals example
 
 The following example defines a `Book` class that has two <xref:System.String> fields, `Title` and `Author`. It also defines a `BookCollection` class that includes a private array of `Book` objects. Individual book objects are returned by reference by calling its `GetBookByTitle` method.
@@ -161,10 +133,6 @@ The `Span<T>` type stores a reference through which it accesses the consecutive
 
 ## See also
 
-- [Avoid allocations](../../advanced-topics/performance/index.md)
-- [Ref locals](../statements/declarations.md#ref-locals)
-- [Conditional ref expression](../operators/conditional-operator.md#conditional-ref-expression)
-- [Method Parameters](method-parameters.md)
-- [C# Reference](../index.md)
-- [C# Programming Guide](../../programming-guide/index.md)
-- [C# Keywords](index.md)
+- [C# reference](../index.md)
+- [C# keywords](index.md)
+- [Method parameters](method-parameters.md)

docs/csharp/language-reference/operators/assignment-operator.md

@@ -34,7 +34,7 @@ This is called *value assignment*: the value is assigned.
 
 ## ref assignment
 
-*Ref assignment* `= ref` makes its left-hand operand an alias to the right-hand operand. The left-hand operand must be a [ref local](../keywords/ref.md#ref-locals), [ref readonly local](../keywords/ref.md#ref-readonly-locals), or a [`ref` field](../builtin-types/ref-struct.md#ref-fields) in a `ref struct`. Both operands must be of the same type.
+*Ref assignment* `= ref` makes its left-hand operand an alias to the right-hand operand. The left-hand operand must be a [local reference variable](../statements/declarations.md#reference-variables) or a [`ref` field](../builtin-types/ref-struct.md#ref-fields) in a `ref struct`. Both operands must be of the same type.
 
 The following example demonstrates the usage of the ref assignment operator:
 

docs/csharp/language-reference/operators/conditional-operator.md

@@ -53,7 +53,7 @@ a ? b : (c ? d : e)
 
 ## Conditional ref expression
 
-A [ref local](../keywords/ref.md#ref-locals) or [ref readonly local](../keywords/ref.md#ref-readonly-locals) variable can be assigned conditionally with a conditional ref expression. You can also use a conditional ref expression as a [reference return value](../keywords/ref.md#reference-return-values) or as a [`ref` method argument](../keywords/ref.md#passing-an-argument-by-reference).
+A [reference variable](../statements/declarations.md#reference-variables) can be assigned conditionally with a conditional ref expression. You can also use a conditional ref expression as a [reference return value](../keywords/ref.md#reference-return-values) or as a [`ref` method argument](../keywords/ref.md#passing-an-argument-by-reference).
 
 The syntax for a conditional ref expression is as follows: