Improvements for CA config options (#44647)

Author: gewarren

docs/fundamentals/code-analysis/code-quality-rule-options.md

@@ -0,0 +1,10 @@
+### Include specific API surfaces
+
+You can configure which parts of your codebase to run this rule on, based on their accessibility, by setting the [api_surface](../../code-quality-rule-options.md#api_surface) option. 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:
+
+```ini
+dotnet_code_quality.CAXXXX.api_surface = private, internal
+```
+
+> [!NOTE]
+> Replace the `XXXX` part of `CAXXXX` with the ID of the applicable rule.

docs/fundamentals/code-analysis/includes/api-surface.md

@@ -0,0 +1,51 @@
+### Configure dispose ownership transfer
+
+The [dispose_ownership_transfer_at_constructor](../../code-quality-rule-options.md#dispose_ownership_transfer_at_constructor) and [dispose_ownership_transfer_at_method_call](../../code-quality-rule-options.md#dispose_ownership_transfer_at_method_call) options configure the transfer of dispose ownership.
+
+For example, to specify that the rule transfers dispose ownership for arguments passed to constructors, add the following key-value pair to an *.editorconfig* file in your project:
+
+```ini
+dotnet_code_quality.CAXXXX.dispose_ownership_transfer_at_constructor = true
+```
+
+> [!NOTE]
+> Replace the `XXXX` part of `CAXXXX` with the ID of the applicable rule.
+
+#### dispose_ownership_transfer_at_constructor
+
+Consider the following code example.
+
+```csharp
+class A : IDisposable
+{
+    public void Dispose() { }
+}
+
+class Test
+{
+    DisposableOwnerType M1()
+    {
+        return new DisposableOwnerType(new A());
+    }
+}
+```
+
+- If `dotnet_code_quality.dispose_ownership_transfer_at_constructor` is set to `true`, dispose ownership for the `new A()` allocation is transferred to the returned `DisposableOwnerType` instance.
+- If `dotnet_code_quality.dispose_ownership_transfer_at_constructor` is set to `false`, `Test.M1()` has the dispose ownership for `new A()`, and results in a `CA2000` violation for a dispose leak.
+
+#### dispose_ownership_transfer_at_method_call
+
+Consider the following code example.
+
+```csharp
+class Test
+{
+    void M1()
+    {
+        TransferDisposeOwnership(new A());
+    }
+}
+```
+
+- If `dotnet_code_quality.dispose_ownership_transfer_at_method_call` is set to `true`, dispose ownership for the `new A()` allocation is transferred to the `TransferDisposeOwnership` method.
+- If `dotnet_code_quality.dispose_ownership_transfer_at_method_call` is set to `false`, `Test.M1()` has the dispose ownership for `new A()`, and results in a `CA2000` violation for a dispose leak.

docs/fundamentals/code-analysis/includes/config-options/api-surface.md

@@ -1,6 +1,6 @@
 ### Exclude specific symbols
 
-You can exclude specific symbols, such as types and methods, from analysis. For example, to specify that the rule should not run on any code within types named `MyType`, add the following key-value pair to an *.editorconfig* file in your project:
+You can exclude specific symbols, such as types and methods, from analysis by setting the [excluded_symbol_names](../../code-quality-rule-options.md#excluded_symbol_names) option. For example, to specify that the rule should not run on any code within types named `MyType`, add the following key-value pair to an *.editorconfig* file in your project:
 
 ```ini
 dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType
@@ -12,7 +12,7 @@ dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType
 Allowed symbol name formats in the option value (separated by `|`):
 
 - Symbol name only (includes all symbols with the name, regardless of the containing type or namespace).
-- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings). Each symbol name requires a symbol-kind prefix, such as `M:` for methods, `T:` for types, and `N:` for namespaces.
+- Fully qualified names in the symbol's [documentation ID format](../../../../csharp/language-reference/xmldoc/index.md#id-strings). Each symbol name requires a symbol-kind prefix, such as `M:` for methods, `T:` for types, and `N:` for namespaces.
 - `.ctor` for constructors and `.cctor` for static constructors.
 
 Examples:

docs/fundamentals/code-analysis/includes/config-options/dispose-ownership-transfer.md

@@ -1,6 +1,6 @@
 ### Exclude specific types and their derived types
 
-You can exclude specific types and their derived types from analysis. For example, to specify that the rule should not run on any methods within types named `MyType` and their derived types, add the following key-value pair to an *.editorconfig* file in your project:
+You can exclude specific types and their derived types from analysis by setting the [excluded_type_names_with_derived_types](../../code-quality-rule-options.md#excluded_type_names_with_derived_types) option. For example, to specify that the rule should not run on any methods within types named `MyType` and their derived types, add the following key-value pair to an *.editorconfig* file in your project:
 
 ```ini
 dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType
@@ -12,12 +12,12 @@ dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType
 Allowed symbol name formats in the option value (separated by `|`):
 
 - Type name only (includes all types with the name, regardless of the containing type or namespace).
-- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings), with an optional `T:` prefix.
+- Fully qualified names in the symbol's [documentation ID format](../../../../csharp/language-reference/xmldoc/index.md#id-strings), with an optional `T:` prefix.
 
 Examples:
 
 <!-- markdownlint-disable MD056 -->
-| Option Value | Summary |
+| Option value | Summary |
 | --- | --- |
 |`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType` | Matches all types named `MyType` and all of their derived types. |
 |`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2` | Matches all types named either `MyType1` or `MyType2` and all of their derived types. |

docs/fundamentals/code-analysis/includes/excluded-symbol-names.md renamed to docs/fundamentals/code-analysis/includes/config-options/excluded-symbol-names.md

@@ -0,0 +1,12 @@
+### Ignore InternalsVisibleTo attribute
+
+By default, this rule is disabled if the assembly being analyzed uses <xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute> to expose its internal symbols. You can set the [ignore_internalsvisibleto](../../code-quality-rule-options.md#ignore_internalsvisibleto) option to change the configuration. To specify that the rule should run even if the assembly is marked with <xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute>, add the following key-value pair to an *.editorconfig* file in your project:
+
+```ini
+dotnet_code_quality.CAXXXX.ignore_internalsvisibleto = true
+```
+
+> [!NOTE]
+> Replace the `XXXX` part of `CAXXXX` with the ID of the applicable rule.
+
+This option is available starting in .NET 8.

docs/fundamentals/code-analysis/includes/excluded-type-names-with-derived-types.md renamed to docs/fundamentals/code-analysis/includes/config-options/excluded-type-names-with-derived-types.md

@@ -87,7 +87,7 @@ Use the following option to configure which parts of your codebase to run this r
 
 You can configure this option for just this rule, for all rules that it applies to, or for all rules in this category ([Design](design-warnings.md)) that it applies to. For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
-[!INCLUDE[api-surface](../includes/api-surface.md)]
+[!INCLUDE[api-surface](../includes/config-options/api-surface.md)]
 
 ## Related rules
 

docs/fundamentals/code-analysis/includes/config-options/ignore-ivt.md

@@ -72,9 +72,9 @@ Use the following options to configure which parts of your codebase to run this
 
 These options can be configured for just this rule, for all rules it applies to, or for all rules in this category ([Design](design-warnings.md)) that it applies to. For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
 
-[!INCLUDE[excluded-symbol-names](../includes/excluded-symbol-names.md)]
+[!INCLUDE[excluded-symbol-names](../includes/config-options/excluded-symbol-names.md)]
 
-[!INCLUDE[excluded-type-names-with-derived-types](../includes/excluded-type-names-with-derived-types.md)]
+[!INCLUDE[excluded-type-names-with-derived-types](../includes/config-options/excluded-type-names-with-derived-types.md)]
 
 ## Example