proofread and edit

Author: BillWagner

docs/csharp/language-reference/operators/deconstruction.md

@@ -5,23 +5,25 @@ ms.date: 12/17/2024
 ---
 # Deconstruction expression - Extract properties of fields from a tuple or other user defined type
 
-A *deconstruction expression* deconstructs data fields in an instance of an object. Each discrete data element is stored in a distinct variable, as shown in the following example:
+A *deconstruction expression* extracts data fields from an instance of an object. Each discrete data element is written to a distinct variable, as shown in the following example:
 
 :::code language="csharp" source="./snippets/shared/Deconstruction.cs" id="TupleDeconstruction":::
 
-The preceding code snippets creates a [tuple](../builtin-types/value-tuples.md) that has two integer values, `X` and `Y`. The second statement *deconstructs* that tuple and stores the tuple elements in discrete variables `x`, and `y`.
+The preceding code snippet creates a [tuple](../builtin-types/value-tuples.md) that has two integer values, `X` and `Y`. The second statement *deconstructs* that tuple and stores the tuple elements in discrete variables `x`, and `y`.
 
 ## Tuple deconstruction
 
 All [tuple types](../builtin-types/value-tuples.md) support deconstruction expressions. Tuple deconstruction extracts all the tuple's elements. If you only want some of the tuple elements, use a [discard](../tokens/discard.md) for the unused tuple members, as shown in the following example:
 
 :::code language="csharp" source="./snippets/shared/Deconstruction.cs" id="TupleDeconstructionWithDiscard":::
 
-In the preceding example, the `Y` and `label` members are discarded. You can specify multiple discards in the same deconstruction expression.
+In the preceding example, the `Y` and `label` members are discarded. You can specify multiple discards in the same deconstruction expression. You can use discards for all the members of the tuple. The following example is legal, although not useful:
+
+:::code language="csharp" source="./snippets/shared/Deconstruction.cs" id="AllDiscards":::
 
 ## Record deconstruction
 
-All [record](../builtin-types/record.md) types that have a [primary constructor](../builtin-types/record.md#positional-syntax-for-property-definition) support deconstruction. The compiler synthesizes a deconstruct method that extracts all properties declared in the primary constructor. Deconstruction for records doesn't extract properties that aren't declared using the primary constructor syntax.
+[Record](../builtin-types/record.md) types that have a [primary constructor](../builtin-types/record.md#positional-syntax-for-property-definition) support deconstruction for positional parameters. The compiler synthesizes a `Deconstruct` method that extracts the properties synthesized from positional parameters in the primary constructor. The compiler synthesized `Deconstruction` method doesn't extract properties declared as properties in the record type.
 
 The `record` shown in the following code declares two positional properties, `SquareFeet` and `Address`, along with another property, `RealtorNotes`:
 
@@ -35,17 +37,17 @@ You can make use of this behavior to specify which properties of your record typ
 
 ## Declare `Deconstruct` methods
 
-You can add deconstruct support to any class, struct, or interface you declare. You declare one or `Deconstruct` methods in your type, or as extension methods on that type. A deconstruction expression can resolve to a unique method `void Deconstruct(out var p1, ..., out var pn)`. The `Deconstruct` method can be either an instance method or an extension method. The type of each parameter in the `Deconstruct` method must match the type of the corresponding argument in the deconstruct method. The deconstruction expression assigns the value of each argument to the value of the corresponding `out` parameter in the `Deconstruct` method. If multiple `Deconstruct` methods match the deconstruction expression, the compiler reports an ambiguity.
+You can add deconstruction support to any class, struct, or interface you declare. You declare one or `Deconstruct` methods in your type, or as extension methods on that type. A deconstruction expression calls a  method `void Deconstruct(out var p1, ..., out var pn)`. The `Deconstruct` method can be either an instance method or an extension method. The type of each parameter in the `Deconstruct` method must match the type of the corresponding argument in the deconstruction expression. The deconstruction expression assigns the value of each argument to the value of the corresponding `out` parameter in the `Deconstruct` method. If multiple `Deconstruct` methods match the deconstruction expression, the compiler reports an error for the ambiguity.
 
 The following code declares a `Point3D` struct that has two `Deconstruct` methods:
 
 :::code language="csharp" source="./snippets/shared/Deconstruction.cs" id="StructDeconstruction":::
 
-The first method supports deconstruction expressions that extract all three axes values: `X`, `Y`, and `Z`. The second method supports deconstructing only the planar values, `X` and `Y`. The first method has an *arity* of 3, the second has an arity of 2.
+The first method supports deconstruction expressions that extract all three axes values: `X`, `Y`, and `Z`. The second method supports deconstructing only the planar values: `X` and `Y`. The first method has an *arity* of 3; the second has an arity of 2.
 
-The preceding section described the compiler synthesized `Deconstruct` method for `record` types with a primary constructor. You can declare additional `Deconstruct` methods in record types. These can either add additional properties, remove some of the default properties, or both. You can also declare a `Deconstruct` that matches the compiler synthesized signature. If you declare such a `Deconstruct` method, the compiler won't synthesize one.
+The preceding section described the compiler synthesized `Deconstruct` method for `record` types with a primary constructor. You can declare more `Deconstruct` methods in record types. These methods can either add other properties, remove some of the default properties, or both. You can also declare a `Deconstruct` that matches the compiler synthesized signature. If you declare such a `Deconstruct` method, the compiler doesn't synthesize one.
 
-In most cases, multiple `Deconstruct` methods for the same type have different arities. This isn't a strict requirement. As long as the compiler can determine one unique `Deconstruct` method for a deconstruction expression, the multiple `Deconstruct` methods are allowed. However, in many cases, too many `Deconstruct` methods can lead to ambiguity errors and misleading results.
+Typically, multiple `Deconstruct` methods for the same type have different numbers of parameters. You can create multiple `Deconstruct` methods providing the signatures have different parameter types. As long as the compiler can determine one unique `Deconstruct` method for a deconstruction expression, the multiple `Deconstruct` methods are allowed. However, in many cases, too many `Deconstruct` methods can lead to ambiguity errors and misleading results.
 
 ## C# language specification
 

docs/csharp/language-reference/operators/snippets/shared/Deconstruction.cs

@@ -23,6 +23,10 @@ public static void Examples()
         var (x2, _, _) = tuple2;
         // </TupleDeconstructionWithDiscard>
 
+        // <AllDiscards>
+        var (_, _, _) = tuple2;
+        // </AllDiscards>
+
         // <RecordDeconstructionUsage>
         var house = new House(1000, "123 Coder St.")
         {

docs/csharp/language-reference/tokens/discard.md

@@ -9,11 +9,11 @@ The `_` character services as a *discard*, which is a placeholder for an unused
 
 There are two uses for the *discard* token:
 
-1. To declare a variable with a storage location that won't ever be read. You may need to declare a variable that you don't intend to read or otherwise use its value:
+1. To declare an unused variable. A discard can't be read or accessed.
    - Unused `out` arguments: `var r = M(out int _, out var _, out _);`
    - Unused lambda expression parameters: `Action<int> _ => WriteMessage();`
    - Unused deconstruction arguments: `(int _, var answer) = M();`
-1. In a [discard pattern](../operators/patterns.md#discard-pattern) to match any expression. You'll usually add a `_` pattern to satisfy exhaustiveness requirements.
+1. To match any expression in a [discard pattern](../operators/patterns.md#discard-pattern). You can add a `_` pattern to satisfy exhaustiveness requirements.
 
 The `_` token is a valid identifier in C#. The `_` token is interpreted as a discard only when no valid identifier named `_` is found in scope.
 

docs/csharp/language-reference/tokens/index.md

@@ -16,11 +16,11 @@ ms.assetid: 4c5c0539-2e37-40b7-91ce-75af5aabd3f9
 
 # C# Special Characters
 
-Special characters are predefined, contextual characters that modify the program element (a literal string, an identifier, or an attribute name) to which they are prepended. C# supports the following special characters:
+Special characters are predefined, contextual characters that modify the program element (a literal string, an identifier, or an attribute name) to which they're prepended. C# supports the following special characters:
 
 - [@](./verbatim.md), the verbatim identifier character.
 - [$](./interpolated.md), the interpolated string character.
 - ["""](./raw-string.md), A sequence of three or more `"` characters provides the delimiters for a raw string literal.
 - [_](./discard.md), a `_` represents a *discard*, a placeholder for an unused variable.
 
-This section only includes those tokens that are not operators. See the [operators](../operators/index.md) section for all operators.
+This section only includes those tokens that aren't operators. See the [operators](../operators/index.md) section for all operators.