dotnet · gewarren · Dec 15, 2020 · Dec 11, 2020 · Dec 11, 2020 · Dec 11, 2020
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1000.md b/docs/fundamentals/code-analysis/quality-rules/ca1000.md
@@ -27,7 +27,7 @@ dev_langs:
 
 A generic type contains a `static` (`Shared` in Visual Basic) member.
 
-By default, this rule only looks at externally visible types, but this is [configurable](#configurability).
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -59,16 +59,16 @@ To fix a violation of this rule, remove the static member or change it to an ins
 
 Do not suppress a warning from this rule. Providing generics in a syntax that is easy to understand and use reduces the time that is required to learn and increases the adoption rate of new libraries.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1000.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Related rules
 
 - [CA1005: Avoid excessive parameters on generic types](ca1005.md)

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1001.md b/docs/fundamentals/code-analysis/quality-rules/ca1001.md
@@ -45,13 +45,13 @@ In general, do not suppress a warning from this rule. It is OK to suppress the w
 
 ## Configure code to analyze
 
-This rule has the following configurable options that can be configured for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
-
 Use the following options to configure which parts of your codebase to run this rule on.
 
 - [Exclude specific symbols](#exclude-specific-symbols)
 - [Exclude specific types and their derived types](#exclude-specific-types-and-their-derived-types)
 
+These options can be configured for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
+
 [!INCLUDE[excluded-symbol-names](~/includes/code-analysis/excluded-symbol-names.md)]
 
 [!INCLUDE[excluded-type-names-with-derived-types](~/includes/code-analysis/excluded-type-names-with-derived-types.md)]

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1002.md b/docs/fundamentals/code-analysis/quality-rules/ca1002.md
@@ -24,6 +24,8 @@ ms.author: gewarren
 
 A type contains an externally visible member that is a <xref:System.Collections.Generic.List%601?displayProperty=fullName> type, returns a <xref:System.Collections.Generic.List%601> type, or whose signature includes a <xref:System.Collections.Generic.List%601> parameter.
 
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze).
+
 ## Rule description
 
 <xref:System.Collections.Generic.List%601?displayProperty=fullName> is a generic collection that's designed for performance and not inheritance. <xref:System.Collections.Generic.List%601> does not contain virtual members that make it easier to change the behavior of an inherited class. The following generic collections are designed for inheritance and should be exposed instead of <xref:System.Collections.Generic.List%601>.
@@ -46,16 +48,16 @@ To fix a violation of this rule, change the <xref:System.Collections.Generic.Lis
 
 Do not suppress a warning from this rule unless the assembly that raises this warning is not meant to be a reusable library. For example, it would be safe to suppress this warning in a performance-tuned application where a performance benefit was gained from the use of generic lists.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1002.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Related rules
 
 [CA1005: Avoid excessive parameters on generic types](ca1005.md)

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1003.md b/docs/fundamentals/code-analysis/quality-rules/ca1003.md
@@ -27,7 +27,7 @@ dev_langs:
 
 A type contains a delegate that returns void and whose signature contains two parameters (the first an object and the second a type that is assignable to EventArgs), and the containing assembly targets .NET.
 
-By default, this rule only looks at externally visible types, but this is [configurable](#configurability).
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -43,16 +43,16 @@ If the delegate is autogenerated by the Visual Basic compiler, change the syntax
 
 Do not suppress a warning from this rule.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1003.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Example
 
 The following example shows a delegate that violates the rule. In the Visual Basic example, comments describe how to modify the example to satisfy the rule. For the C# example, an example follows that shows the modified code.

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1005.md b/docs/fundamentals/code-analysis/quality-rules/ca1005.md
@@ -24,6 +24,8 @@ ms.author: gewarren
 
 An externally visible generic type has more than two type parameters.
 
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze).
+
 ## Rule description
 
 The more type parameters a generic type contains, the more difficult it is to know and remember what each type parameter represents. It is usually obvious with one type parameter, as in `List<T>`, and in certain cases with two type parameters, as in `Dictionary<TKey, TValue>`. If more than two type parameters exist, the difficulty becomes too great for most users (for example, `TooManyTypeParameters<T, K, V>` in C# or `TooManyTypeParameters(Of T, K, V)` in Visual Basic).
@@ -36,16 +38,16 @@ To fix a violation of this rule, change the design to use no more than two type
 
 Do not suppress a warning from this rule unless the design absolutely requires more than two type parameters. Providing generics in a syntax that is easy to understand and use reduces the time that is required to learn and increases the adoption rate of new libraries.
 
-## Configurability
+## Configure code to analyze
 
-Starting with version 3.0.0 of the analyzer package, You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1005.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Related rules
 
 [CA1010: Collections should implement generic interface](ca1010.md)

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1008.md b/docs/fundamentals/code-analysis/quality-rules/ca1008.md
@@ -27,7 +27,7 @@ dev_langs:
 
 An enumeration without an applied <xref:System.FlagsAttribute?displayProperty=fullName> does not define a member that has a value of zero. Or, an enumeration that has an applied <xref:System.FlagsAttribute> defines a member that has a value of zero but its name is not 'None'. Or, the enumeration defines multiple, zero-valued members.
 
-By default, this rule only looks at externally visible enumerations, but this is [configurable](#configurability).
+By default, this rule only looks at externally visible enumerations, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -43,16 +43,16 @@ To fix a violation of this rule for non-flags-attributed enumerations, define a
 
 Do not suppress a warning from this rule except for flags-attributed enumerations that have previously shipped.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1008.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Example
 
 The following example shows two enumerations that satisfy the rule and an enumeration, `BadTraceOptions`, that violates the rule.

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1010.md b/docs/fundamentals/code-analysis/quality-rules/ca1010.md
@@ -26,7 +26,7 @@ ms.author: gewarren
 
 A type implements the <xref:System.Collections.IEnumerable?displayProperty=fullName> interface but does not implement the <xref:System.Collections.Generic.IEnumerable%601?displayProperty=fullName> interface, and the containing assembly targets .NET. This rule ignores types that implement <xref:System.Collections.IDictionary?displayProperty=fullName>.
 
-By default, this rule only looks at externally visible types, but this is [configurable](#configurability). You can also configure additional interfaces to require that a generic interface be implemented.
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze). You can also configure additional interfaces to require that a generic interface be implemented.
 
 ## Rule description
 
@@ -48,15 +48,16 @@ To fix a violation of this rule, implement one of the following generic collecti
 
 It is safe to suppress a warning from this rule; however, the use of the collection will be more limited.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following options to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1010.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
+- [Additional required generic interfaces](#additional-required-generic-interfaces)
 
-You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
+You can configure these options for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
+
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
 
 ### Additional required generic interfaces
 

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1012.md b/docs/fundamentals/code-analysis/quality-rules/ca1012.md
@@ -26,7 +26,7 @@ dev_langs:
 
 A type is abstract and has a constructor.
 
-By default, this rule only looks at externally visible types, but this is [configurable](#configurability).
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -40,16 +40,16 @@ To fix a violation of this rule, either make the constructor protected or don't
 
 Do not suppress a warning from this rule. The abstract type has a public constructor.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1012.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Example
 
 The following code snippet contains an abstract type that violates this rule.

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1021.md b/docs/fundamentals/code-analysis/quality-rules/ca1021.md
@@ -26,7 +26,7 @@ ms.author: gewarren
 
 A public or protected method in a public type has an `out` parameter.
 
-By default, this rule only looks at externally visible types, but this is [configurable](#configurability).
+By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -48,16 +48,16 @@ To fix a violation of this rule that is caused by a reference type, make sure th
 
 It is safe to suppress a warning from this rule. However, this design could cause usability issues.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1021.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Example 1
 
 The following library shows two implementations of a class that generates responses to user feedback. The first implementation (`BadRefAndOut`) forces the library user to manage three return values. The second implementation (`RedesignedRefAndOut`) simplifies the user experience by returning an instance of a container class (`ReplyData`) that manages the data as a single unit.

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1024.md b/docs/fundamentals/code-analysis/quality-rules/ca1024.md
@@ -27,7 +27,7 @@ dev_langs:
 
 A method has a name that starts with `Get`, takes no parameters, and returns a value that is not an array.
 
-By default, this rule only looks at public and protected methods, but this is [configurable](#configurability).
+By default, this rule only looks at public and protected methods, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -61,16 +61,16 @@ To fix a violation of this rule, change the method to a property.
 
 Suppress a warning from this rule if the method meets at least one of the previously listed criteria.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1024.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Control property expansion in the debugger
 
 One reason programmers avoid using a property is because they do not want the debugger to autoexpand it. For example, the property might involve allocating a large object or calling a P/Invoke, but it might not actually have any observable side effects.

diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1027.md b/docs/fundamentals/code-analysis/quality-rules/ca1027.md
@@ -24,7 +24,7 @@ ms.author: gewarren
 
 The values of an enumeration are powers of two or are combinations of other values that are defined in the enumeration, and the <xref:System.FlagsAttribute?displayProperty=fullName> attribute is not present. To reduce false positives, this rule does not report a violation for enumerations that have contiguous values.
 
-By default, this rule only looks at public enumerations, but this is [configurable](#configurability).
+By default, this rule only looks at public enumerations, but this is [configurable](#configure-code-to-analyze).
 
 ## Rule description
 
@@ -40,16 +40,16 @@ To fix a violation of this rule, add <xref:System.FlagsAttribute> to the enumera
 
 Suppress a warning from this rule if you do not want the enumeration values to be combinable.
 
-## Configurability
+## Configure code to analyze
 
-You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an *.editorconfig* file in your project:
+Use the following option to configure which parts of your codebase to run this rule on.
 
-```ini
-dotnet_code_quality.ca1027.api_surface = private, internal
-```
+- [Include specific API surfaces](#include-specific-api-surfaces)
 
 You can configure this option for just this rule, for all rules, or for all rules in this category (Design). For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
+[!INCLUDE[api-surface](~/includes/code-analysis/api-surface.md)]
+
 ## Example
 
 In the following example, `DaysEnumNeedsFlags` is an enumeration that meets the requirements for using <xref:System.FlagsAttribute> but doesn't have it. The `ColorEnumShouldNotHaveFlag` enumeration does not have values that are powers of two but incorrectly specifies <xref:System.FlagsAttribute>. This violates rule [CA2217: Do not mark enums with FlagsAttribute](ca2217.md).