Improve annotations documentation and rule references

.github/copilot-instructions.md

@@ -35,6 +35,13 @@ When a rule in this analyzer is equivalent to or similar to a rule in another an
 
 Do NOT add equivalence/similarity notes directly to individual rule documentation files (e.g., `docs/Rules/MA0158.md`).
 
+## Maintaining Meziantou.Analyzer.Annotations
+
+When you change any file under `src/Meziantou.Analyzer.Annotations`, you MUST:
+
+- Update [`src/Meziantou.Analyzer.Annotations/README.md`](/src/Meziantou.Analyzer.Annotations/README.md) if the package behavior, exposed attributes, or usage guidance changed.
+- Bump `<Version>` in [`src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj`](/src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj).
+
 ## Implementing Roslyn analyzers
 
 - When creating a new rule, create a new constant in `src/Meziantou.Analyzer/RuleIdentifiers.cs` using the name of the new rule. The value must be unique and incremented from the last rule.

docs/Rules/MA0003.md

@@ -32,8 +32,8 @@ MA0003.excluded_methods = M:A.B(System.Int32) | M:C.D()
 MA0003.excluded_methods_regex = Sample.*Test
 ````
 
-You can annotate a parameter with `Meziantou.Analyzer.Annotations.RequireNamedArgumentAttribute`. This attribute is available using the
-`Meziantou.Analyzer.Annotations` NuGet package.
+You can annotate a parameter with `Meziantou.Analyzer.Annotations.RequireNamedArgumentAttribute`.
+To use this attribute, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md).
 
 ```c#
 Test("test"); // report a diagnostic as the parameter is not named

docs/Rules/MA0011.md

@@ -39,4 +39,4 @@ MA0011.exclude_tostring_methods=true
 MA0011.consider_nullable_types=true
 ````
 
-You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for more details.
+You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options.

docs/Rules/MA0042.md

@@ -111,7 +111,8 @@ MA0042.enable_sqlite_special_cases = true
 MA0042.enable_db_special_cases = true
 ````
 
-You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations:
+You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations.
+To use `Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md).
 
 ```csharp
 [assembly: Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute("M:System.Threading.Tasks.Task.Wait")]

docs/Rules/MA0045.md

@@ -54,7 +54,8 @@ MA0042.enable_sqlite_special_cases = true
 MA0042.enable_db_special_cases = true
 ````
 
-You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations:
+You can also exclude specific method/property diagnostics for MA0042/MA0045 using assembly-level annotations.
+To use `Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md).
 
 ```csharp
 [assembly: Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute("M:System.Threading.Tasks.Task.Wait")]

docs/Rules/MA0075.md

@@ -45,4 +45,4 @@ MA0075.exclude_tostring_methods=true
 MA0075.consider_nullable_types=true
 ````
 
-You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for more details.
+You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options.

docs/Rules/MA0076.md

@@ -21,4 +21,4 @@ MA0076.exclude_tostring_methods=true
 MA0076.consider_nullable_types=true
 ````
 
-You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for more details.
+You can also annotate a type with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to disable the rule for this type. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options.

docs/Rules/MA0124.md

@@ -35,6 +35,7 @@ Then, you need to add the file to the `AdditionalFiles` collection in the `cspro
 ````
 
 You can also configure the allowed types by using an assembly attribute. These attributes are applied only for the current assembly. The rule does not consider attributes defined in referenced assemblies.
+To use `Meziantou.Analyzer.Annotations.StructuredLogFieldAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md).
 
 ````c#
 // Requires the Meziantou.Analyzer.Annotations package

docs/Rules/MA0139.md

@@ -35,6 +35,7 @@ Then, you need to add the file to the `AdditionalFiles` collection in the `cspro
 ````
 
 You can also configure the allowed types by using an assembly attribute. These attributes are applied only for the current assembly. The rule does not consider attributes defined in referenced assemblies.
+To use `Meziantou.Analyzer.Annotations.StructuredLogFieldAttribute`, add the `Meziantou.Analyzer.Annotations` NuGet package (or copy the attribute source into your project). See [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md).
 
 ````c#
 // Requires the Meziantou.Analyzer.Annotations package

docs/Rules/MA0185.md

@@ -30,6 +30,8 @@ The analyzer detects when all interpolated values are culture-invariant, such as
 - Boolean values
 - and other culture-insensitive types
 
+You can annotate custom types with `[Meziantou.Analyzer.Annotations.CultureInsensitiveTypeAttribute]` to mark them as culture-insensitive and make additional `string.Create(CultureInfo.InvariantCulture, ...)` usages eligible for simplification. See [CultureInsensitiveTypeAttribute](../CultureInsensitiveTypeAttribute.md) for details and [Meziantou.Analyzer.Annotations README](https://github.com/meziantou/Meziantou.Analyzer/blob/main/src/Meziantou.Analyzer.Annotations/README.md) for installation options.
+
 The analyzer will NOT suggest simplification when:
 - Any parameter is culture-sensitive (e.g., `double`, `DateTime` with culture-sensitive format)
 - The culture is not `CultureInfo.InvariantCulture`

src/Meziantou.Analyzer.Annotations/Meziantou.Analyzer.Annotations.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0</TargetFrameworks>
-    <Version>1.3.0</Version>
+    <Version>1.3.1</Version>
     <Description>Annotations to configure Meziantou.Analyzer</Description>
     <PackageTags>Meziantou.Analyzer, analyzers</PackageTags>
     <GenerateDocumentationFile>True</GenerateDocumentationFile>

src/Meziantou.Analyzer.Annotations/README.md

@@ -1,9 +1,28 @@
+# Meziantou.Analyzer.Annotations
+
 `Meziantou.Analyzer.Annotations` enables you to configure certain analyzer rules by adding annotations directly to your code.
 
+`Meziantou.Analyzer.Annotations` is a separate dependency from `Meziantou.Analyzer`. If you want to use these attributes in your code, add an explicit package reference:
+
+```bash
+dotnet add package Meziantou.Analyzer.Annotations
+```
+
+You can also copy the attribute source files into your project as long as the namespace and type names match. The copied types can be `public` or `internal`.
+
 By default, all usages of attributes from `Meziantou.Analyzer.Annotations` are removed from the compiled assembly metadata. This means your binaries will not reference the `Meziantou.Analyzer.Annotations.dll` assembly.
 
 If you want to keep these attributes in the metadata (for example, for reflection or tooling purposes), define the `MEZIANTOU_ANALYZER_ANNOTATIONS` conditional compilation symbol in your project settings.
 
+## Available attributes
+
+| Attribute | Purpose | Related rules |
+| --- | --- | --- |
+| `CultureInsensitiveTypeAttribute` | Marks a type (or a specific format) as culture-insensitive. | [MA0011](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0011.md), [MA0075](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0075.md), [MA0076](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0076.md), [MA0185](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0185.md) |
+| `ExcludeFromBlockingCallAnalysisAttribute` | Excludes specific methods/properties from blocking-call diagnostics. | [MA0042](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0042.md), [MA0045](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0045.md) |
+| `RequireNamedArgumentAttribute` | Requires named arguments for decorated parameters. | [MA0003](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0003.md) |
+| `StructuredLogFieldAttribute` | Declares allowed types for named log properties in an assembly. | [MA0124](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0124.md), [MA0139](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0139.md) |
+
 ## ExcludeFromBlockingCallAnalysisAttribute
 
 Use `ExcludeFromBlockingCallAnalysisAttribute` to exclude specific MA0042/MA0045 method/property diagnostics at the assembly level.