Dotnet-api-docs: Add documentation for new SuppressMessageAttribute scope

[mavasani]

https://github.com/dotnet/roslyn/pull/31092 adds a new SuppressMessageAttribute scope for very widely requested feature: https://github.com/dotnet/roslyn/issues/486. We should document it here (and also improve the documentation for current scopes) once the fix goes out - Dev16 Preview2.

Also note that the new scope is only valid for Roslyn analyzers, and is not going to be respected for legacy binary FxCop based static analysis.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 6ead130f-1feb-2367-ef07-9f73ec63b96f
• Version Independent ID: 1900bccb-13aa-120d-81cb-91e43702a141
• Content: SuppressMessageAttribute.Scope Property (System.Diagnostics.CodeAnalysis)
• Content Source: xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml
• Product: dotnet-api
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[mavasani]

Tagging @gewarren

[gewarren]

@gregvanl You are the API ref expert...what's the best way to go about adding the new scope value of "NamespaceAndChildren" to the docs?

[gregvanl]

Adding @mairaw
The remarks for the SuppressMessageAttribute have a list of the available scopes: "Possible values for managed metadata include "member", "resource", "module", "type", "method", or "namespace"."
The remarks should be coming from /// comments in the source code so the product team can update the list in source code and then provide a new assembly and XML comment file for the API generation process.

[mavasani]

@gregvanl Note that there is a subtle design here. Scope is just a string, whose allowed values are not defined or restricted in the attribute API. The legacy FxCop infrastructure allowed the current values, and so when we added SuppressMessageAttribute encoding/decoding support to Roslyn compilers, we supported these allowed values. The new scope value's encoding/decoding is only added to Roslyn compilers, and legacy FxCop will not understand this scope.

In short, I am not sure if the allowed values or their description can directly come from the Attribute's xml doc comments, as the allowed values are open ended and for the individual encoder/decoder's to support. I am not sure how such cases are handled in our documentation.

[mairaw]

@gregvanl there’s no auto-generated content for the .NET reference. You can just click edit and add the text you want.

[mavasani]

Actually, searching more documentation, probably the right page to update for this issue would be: https://docs.microsoft.com/en-us/visualstudio/code-quality/in-source-suppression-overview?view=vs-2017

That page has detailed explanations about scopes and also has a note about existing Namespace scope’s limitation, which is addressed by this new scope.

[mavasani]

Also note that we are still considering a change to the name for the new suppression scope: https://github.com/dotnet/roslyn/issues/31196, this will be discussed at a design meeting next week. I will post an update here if the chosen name changes.

[gewarren]

PR is here: https://github.com/MicrosoftDocs/visualstudio-docs-pr/pull/3344

[gewarren]

@mavasani Does this look okay? https://review.docs.microsoft.com/en-us/visualstudio/code-quality/in-source-suppression-overview?view=vs-2017&branch=pr-en-us-3344#suppressmessage-attribute

[mairaw]

@mavasani can you please review the changes made by @gewarren? Thanks.

[mavasani]

@gewarren @mairaw The changes look good to me. However, note that we have decided to rename the new scope (https://github.com/dotnet/roslyn/pull/31940), so the doc PR needs to be updated accordingly. Thanks!

[mavasani]

FYI: The new scope has been renamed to NamespaceAndDescendants (https://github.com/dotnet/roslyn/pull/31940)

[gewarren]

I added the scope to the documentation. It will be published with Dev16 preview 2 (please let me know if it should be published sooner).