Add option for CA1806

docs/fundamentals/code-analysis/quality-rules/ca1806.md

@@ -1,7 +1,7 @@
 ---
 title: "CA1806: Do not ignore method results (code analysis)"
 description: "Learn about code analysis rule CA1806: Do not ignore method results"
-ms.date: 06/08/2020
+ms.date: 06/08/2022
 ms.topic: reference
 f1_keywords:
 - CA1806
@@ -17,11 +17,11 @@ dev_langs:
 ---
 # CA1806: Do not ignore method results
 
-| | Value |
-|-|-|
-| **Rule ID** |CA1806|
-| **Category** |[Performance](performance-warnings.md)|
-| **Fix is breaking or non-breaking** |Non-breaking|
+|                                     | Value                                  |
+|-------------------------------------|----------------------------------------|
+| **Rule ID**                         | CA1806                                 |
+| **Category**                        | [Performance](performance-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-breaking                           |
 
 ## Cause
 
@@ -31,51 +31,74 @@ There are several possible reasons for this warning:
 
 - A method that creates and returns a new string is called and the new string is never used.
 
-- A COM or P/Invoke method that returns a `HRESULT` or error code that is never used.
+- A COM or P/Invoke method that returns a `HRESULT` or error code that's never used.
 
-- A language-integrated query (LINQ) method that returns a result that is never used.
+- A language-integrated query (LINQ) method that returns a result that's never used.
 
 ## Rule description
 
 Unnecessary object creation and the associated garbage collection of the unused object degrade performance.
 
-Strings are immutable and methods such as String.ToUpper returns a new instance of a string instead of modifying the instance of the string in the calling method.
+Strings are immutable and methods such as <xref:System.String.ToUpper%2A?displayProperty=nameWithType> return a new instance of a string instead of modifying the instance of the string in the calling method.
 
-Ignoring `HRESULT` or error code can lead to unexpected behavior in error conditions or to low-resource conditions.
+Ignoring `HRESULT` or an error code can lead to low-resource conditions or unexpected behavior in error conditions.
 
 LINQ methods are known to not have side effects, and the result should not be ignored.
 
 ## How to fix violations
 
-If method A creates a new instance of B object that is never used, pass the instance as an argument to another method or assign the instance to a variable. If the object creation is unnecessary, remove it.
+If a method creates a new instance of an object that's never used, pass the instance as an argument to another method or assign the instance to a variable. If the object creation is unnecessary, remove it.
 
 -or-
 
-If method A calls method B, but does not use the new string instance that the method B returns, pass the instance as an argument to another method, assign the instance to a variable. Or remove the call if it is unnecessary.
+If method A calls method B but does not use the new string instance that method B returns, pass the instance as an argument to another method or assign the instance to a variable. Or remove the call if it's unnecessary.
 
 -or-
 
-If method A calls method B, but does not use the `HRESULT` or error code that the method returns, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method.
+If method A calls method B but does not use the `HRESULT` or error code that the method returns, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method.
 
 -or-
 
-If a LINQ method A calls method B, but does not use the result, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method.
+If a LINQ method A calls method B but does not use the result, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method.
 
 ## When to suppress warnings
 
 Do not suppress a warning from this rule unless the act of creating the object serves some purpose.
 
+## Configure code to analyze
+
+Use the following option to configure which parts of your codebase to run this rule on.
+
+### Additional methods to enforce
+
+You can configure this rule to check that results from additional custom APIs are used. Specify one or more methods as the *value* of the `additional_use_results_methods` option. To specify multiple method names, separate them with `|`. The allowable formats for the method name are:
+
+- Method name only (which will include all methods with that name, regardless of their containing type or namespace).
+- Fully qualified name in the [documentation ID format](/dotnet/csharp/language-reference/language-specification/documentation-comments#d4-processing-the-documentation-file), with an optional `M:` prefix.
+
+For example, to specify that rule CA1806 should also check that the result from a method named `MyMethod1` is used, add the following key-value pair to an *.editorconfig* file in your project.
+
+```ini
+dotnet_code_quality.CA1806.additional_use_results_methods = MyMethod1
+```
+
+Or, use the fully qualified name to disambiguate or ensure that only a specific method with that name is included.
+
+```ini
+dotnet_code_quality.CA1806.additional_use_results_methods = M:MyNamespace.MyType.MyMethod1(ParamType)
+```
+
 ## Example 1
 
-The following example shows a class that ignores the result of calling String.Trim.
+The following example shows a class that ignores the result of calling <xref:System.String.Trim%2A?displayProperty=nameWithType>.
 
 :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet1":::
 
 :::code language="vb" source="snippets/vb/all-rules/ca1806-do-not-ignore-method-results_1.vb" id="snippet1":::
 
 ## Example 2
 
-The following example fixes the previous violation by assigning the result of String.Trim back to the variable it was called on.
+The following example fixes the [Example 1](#example-1) violation by assigning the result of <xref:System.String.Trim%2A?displayProperty=nameWithType> back to the variable it was called on.
 
 :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet2":::
 
@@ -92,13 +115,11 @@ The following example shows a method that does not use an object that it creates
 
 ## Example 4
 
-The following example fixes the previous violation by removing the unnecessary creation of an object.
+The following example fixes the [Example 3](#example-3) violation by removing the unnecessary creation of an object.
 
 :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet4":::
 
 <!-- Examples don't exist for the following...
-
 The following example shows a method that ignores the error code that the native method GetShortPathName returns.
-
 The following example fixes the previous violation by checking the error code and throwing an exception when the call fails.
 -->