From 144e8e0bc4bafa7e009c0916a910894f0c0947d6 Mon Sep 17 00:00:00 2001 From: Julien Couvreur Date: Thu, 12 Oct 2023 10:56:52 -0700 Subject: [PATCH 1/4] Clarify rules for diagnostic ID in `[Experimental]` attribute --- .../csharp-12.0/experimental-attribute.md | 31 +++++++++++++------ 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/proposals/csharp-12.0/experimental-attribute.md b/proposals/csharp-12.0/experimental-attribute.md index a596ee17dc..7f2bf920d7 100644 --- a/proposals/csharp-12.0/experimental-attribute.md +++ b/proposals/csharp-12.0/experimental-attribute.md @@ -29,23 +29,36 @@ namespace System.Diagnostics.CodeAnalysis } ``` -## Warnings -The warning message is a specific message, where `'{0}'` is the fully-qualified type or member name. -``` -'{0}' is for evaluation purposes only and is subject to change or removal in future updates. -``` +## Reported diagnostic + +Although the diagnostic is technically a warning (so that the compiler allows suppressing it), +it is treated as an error for purpose of reporting. This causes the build to fail if the diagnostic +is not suppressed. -The warning is reported for any reference to a type or member that is either: +The diagnostic is reported for any reference to a type or member that is either: - marked with the attribute, - in an assembly or module marked with the attribute, except when the reference occurs within `[Experimental]` members (automatic suppression). -It is also possible to suppress the warning by usual means, such as an explicit compiler option or `#pragma`. +It is also possible to suppress the diagnostic by usual means, such as an explicit compiler option or `#pragma`. +For example, if the API is marked with `[Experimental("DiagID")]` or `[Experimental("DiagID", UrlFormat = "https://example.org/{0}")]`, +the diagnostic can be suppressed with `#pragma warning disable DiagID`. + +The diagnostic ID given to the experimental attribute must be a [valid C# identifier](https://github.com/dotnet/csharpstandard/blob/standard-v7/standard/lexical-structure.md#643-identifiers). +This means the diagnostic ID should be valid as a variable name in C#. -The attribute is not inherited from base types or overridden members. -The warning is promoted to an error for purpose of reporting. +The diagnostic message is a specific message, where `'{0}'` is the fully-qualified type or member name. +``` +'{0}' is for evaluation purposes only and is subject to change or removal in future updates. +``` + + + + + +The attribute is not inherited from base types or overridden members. ## ObsoleteAttribute and DeprecatedAttribute From c783158950951bda1e654d9b26db8e76323c90c2 Mon Sep 17 00:00:00 2001 From: Julien Couvreur Date: Thu, 12 Oct 2023 10:57:57 -0700 Subject: [PATCH 2/4] Update experimental-attribute.md --- proposals/csharp-12.0/experimental-attribute.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/proposals/csharp-12.0/experimental-attribute.md b/proposals/csharp-12.0/experimental-attribute.md index 7f2bf920d7..9596a968b6 100644 --- a/proposals/csharp-12.0/experimental-attribute.md +++ b/proposals/csharp-12.0/experimental-attribute.md @@ -54,10 +54,6 @@ The diagnostic message is a specific message, where `'{0}'` is the fully-qualifi '{0}' is for evaluation purposes only and is subject to change or removal in future updates. ``` - - - - The attribute is not inherited from base types or overridden members. ## ObsoleteAttribute and DeprecatedAttribute From 527e87dadc1b3211684cc7897b5b313e76d3b997 Mon Sep 17 00:00:00 2001 From: Julien Couvreur Date: Mon, 16 Oct 2023 11:08:37 -0700 Subject: [PATCH 3/4] Update proposals/csharp-12.0/experimental-attribute.md Co-authored-by: Tim Ritzer --- proposals/csharp-12.0/experimental-attribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/csharp-12.0/experimental-attribute.md b/proposals/csharp-12.0/experimental-attribute.md index 9596a968b6..1f7fda7cd8 100644 --- a/proposals/csharp-12.0/experimental-attribute.md +++ b/proposals/csharp-12.0/experimental-attribute.md @@ -46,7 +46,7 @@ For example, if the API is marked with `[Experimental("DiagID")]` or `[Experimen the diagnostic can be suppressed with `#pragma warning disable DiagID`. The diagnostic ID given to the experimental attribute must be a [valid C# identifier](https://github.com/dotnet/csharpstandard/blob/standard-v7/standard/lexical-structure.md#643-identifiers). -This means the diagnostic ID should be valid as a variable name in C#. +This means the diagnostic ID needs to follow the same naming rules as a variable in C#. The diagnostic message is a specific message, where `'{0}'` is the fully-qualified type or member name. From 5002d8303063d6961f350977b07ee9b5278033c7 Mon Sep 17 00:00:00 2001 From: Julien Couvreur Date: Mon, 16 Oct 2023 11:09:52 -0700 Subject: [PATCH 4/4] Update experimental-attribute.md --- proposals/csharp-12.0/experimental-attribute.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/proposals/csharp-12.0/experimental-attribute.md b/proposals/csharp-12.0/experimental-attribute.md index 1f7fda7cd8..06f8b436bd 100644 --- a/proposals/csharp-12.0/experimental-attribute.md +++ b/proposals/csharp-12.0/experimental-attribute.md @@ -45,9 +45,7 @@ It is also possible to suppress the diagnostic by usual means, such as an explic For example, if the API is marked with `[Experimental("DiagID")]` or `[Experimental("DiagID", UrlFormat = "https://example.org/{0}")]`, the diagnostic can be suppressed with `#pragma warning disable DiagID`. -The diagnostic ID given to the experimental attribute must be a [valid C# identifier](https://github.com/dotnet/csharpstandard/blob/standard-v7/standard/lexical-structure.md#643-identifiers). -This means the diagnostic ID needs to follow the same naming rules as a variable in C#. - +An error is produced if the diagnostic ID given to the experimental attribute is not a [valid C# identifier](https://github.com/dotnet/csharpstandard/blob/standard-v7/standard/lexical-structure.md#643-identifiers). The diagnostic message is a specific message, where `'{0}'` is the fully-qualified type or member name. ```