Update SuppressMessageAttribute (dotnet#5293)

gewarren · web-flow · commit d19373f551fc · 2021-01-29T08:06:35.000-08:00
diff --git a/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml
@@ -48,24 +48,24 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Suppresses reporting of a specific static analysis tool rule violation, allowing multiple suppressions on a single code artifact. Does not apply to compiler diagnostics.</summary>
+    <summary>Suppresses reporting of a specific code analysis rule violation, allowing multiple suppressions on a single code artifact. Does not apply to compiler diagnostics.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This attribute can be applied to any application element. For a complete list of the violations that can be suppressed, see [Code Analysis for Managed Code Warnings](/visualstudio/code-quality/code-analysis-for-managed-code-warnings).  
-  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+ This attribute can be applied to any application element. For a complete list of the violations that can be suppressed, see [Code quality rules](/dotnet/fundamentals/code-analysis/quality-rules/).
+
 > [!NOTE]
->  The <xref:System.Diagnostics.ConditionalAttribute> is applied to this class, specifying the preprocessing symbol "CODE_ANALYSIS" as the conditional symbol that determines whether the attribute call is included or omitted. If the symbol is defined, the attribute call is included; otherwise, the call is omitted.  
->   
->  When you right-click a Code Analysis warning in the Visual Studio **Error List** and then click **Suppress Message(s)**, a **SuppressMessage** attribute is added either in your code or to the project's global suppressions file. For more information about the **SuppressMessage** attribute and its use in Visual Studio, see [In Source Suppression Overview](/visualstudio/code-quality/in-source-suppression-overview).  
+> The <xref:System.Diagnostics.ConditionalAttribute> is applied to this class, specifying the preprocessing symbol "CODE_ANALYSIS" as the conditional symbol that determines whether the attribute call is included or omitted. If the symbol is defined, the attribute call is included; otherwise, the call is omitted.
+>
+> When you right-click a code analysis warning in Visual Studio and choose **Suppress <rule-ID> > in Suppression File** or **Suppress <rule-ID> > in Source (attribute)**, a **SuppressMessage** attribute is added to either the global suppressions file or to the source code file. For more information about the **SuppressMessage** attribute and its use in Visual Studio, see [Suppress code analysis violations](/visualstudio/code-quality/in-source-suppression-overview).
+
+## Examples
+ The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress performance warning messages.
 
-## Examples  
- The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress performance warning messages.  
-  
  [!code-csharp[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/CS/program.cs#1)]
- [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#1)]  
-  
+ [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#1)]
+
  ]]></format>
     </remarks>
   </Docs>
@@ -107,24 +107,24 @@
       <Docs>
         <param name="category">The category for the attribute.</param>
         <param name="checkId">The identifier of the analysis tool rule the attribute applies to.</param>
-        <summary>Initializes a new instance of the <see cref="T:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute" /> class, specifying the category of the static analysis tool and the identifier for an analysis rule.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute" /> class, specifying the category of the code analysis tool and the identifier for an analysis rule.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The `category` parameter value is specific to the analysis tool and categorizes the rule identified by the `checkId` parameter. The two parameters concatenated together form a unique identifier for the rule.
 
-The `category` parameter value is specific to the analysis tool and categorizes the rule identified by the `checkId` parameter. The two parameters concatenated together form a unique identifier for the rule.  
-  
 > [!NOTE]
 > The preprocessor symbol "CODE_ANALYSIS" must be defined for this attribute to be effective. The absence of the preprocessor symbol results in the attribute not being applied.
-  
-## Examples  
 
-The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.  
-  
+## Examples
+
+The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.
+
  [!code-csharp[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/CS/program.cs#2)]
- [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]  
-  
+ [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]
+
  ]]></format>
         </remarks>
       </Docs>
@@ -167,18 +167,18 @@ The following code example shows the use of the <xref:System.Diagnostics.CodeAna
         <summary>Gets the category identifying the classification of the attribute.</summary>
         <value>The category identifying the attribute.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Category%2A> property describes the tool or tool analysis category for which a message suppression attribute applies.
-  
-## Examples  
- The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.  
-  
+
+## Examples
+ The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.
+
  [!code-csharp[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/CS/program.cs#2)]
- [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]  
-  
+ [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]
+
  ]]></format>
         </remarks>
       </Docs>
@@ -218,21 +218,21 @@ The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Category%2A>
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the identifier of the static analysis tool rule to be suppressed.</summary>
-        <value>The identifier of the static analysis tool rule to be suppressed.</value>
+        <summary>Gets the identifier of the code analysis tool rule to be suppressed.</summary>
+        <value>The identifier of the code analysis tool rule to be suppressed.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 Concatenated together, the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Category%2A> and <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.CheckId%2A> properties form a unique check identifier.
-  
-## Examples  
- The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.  
-  
+
+## Examples
+ The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.
+
  [!code-csharp[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/CS/program.cs#2)]
- [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]  
-  
+ [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]
+
  ]]></format>
         </remarks>
       </Docs>
@@ -310,21 +310,24 @@ Concatenated together, the <xref:System.Diagnostics.CodeAnalysis.SuppressMessage
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets an optional argument expanding on exclusion criteria.</summary>
+        <summary>Gets or sets the expanded exclusion criteria.</summary>
         <value>A string containing the expanded exclusion criteria.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
-
-The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.MessageId%2A> property is an optional argument that specifies additional exclusion where the literal metadata target is not sufficiently precise. For example, the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> cannot be applied within a method, and it may be desirable to suppress a violation against a statement in the method that will give a rule violation, but not against all statements in the method.
-  
-## Examples  
- The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for a specific parameter in a method declaration and a specific field in the method. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.MessageId%2A> property is an optional argument that specifies additional exclusion where the literal metadata target is not sufficiently precise. For example, the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> cannot be applied within a method, but you may want to suppress a violation against a single statement in the method.
+
+> [!NOTE]
+> This property is only respected by [legacy code analysis](/visualstudio/code-quality/static-code-analysis-for-managed-code-overview).
+
+## Examples
+ The following code example shows the use of the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> attribute to suppress warnings for a specific parameter in a method declaration and a specific field in the method. This code example is part of a larger example provided for the <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute> class.
+
  [!code-csharp[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/CS/program.cs#2)]
- [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]  
-  
+ [!code-vb[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.CodeAnalysis.SuppressMessageAttribute/VB/program.vb#2)]
+
  ]]></format>
         </remarks>
       </Docs>
@@ -366,12 +369,22 @@ The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.MessageId%2A>
         <summary>Gets or sets the scope of the code that is relevant for the attribute.</summary>
         <value>The scope of the code that is relevant for the attribute.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
+          <format type="text/markdown"><![CDATA[
+
 ## Remarks
 
-The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Scope%2A> property is an optional argument that specifies the metadata scope for which the attribute is relevant. Possible values for managed metadata include "member", "resource", "module", "type", "method", "namespace", or "namespaceanddescendants" (available since Visual Studio 2019). For more information about scopes, see [Suppress code analysis warnings](/visualstudio/code-quality/in-source-suppression-overview#suppressmessage-attribute).  
-  
+The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Scope%2A> property is an optional argument that specifies the metadata scope for which the attribute is relevant. The following table shows the possible values.
+
+| Value | Description |
+| - | - |
+| `"member"` | Suppresses warnings against a member. |
+| `"module"` | Suppresses warnings against an assembly. It is a global suppression that applies to the entire project. |
+| `"namespace"` | This scope suppresses warnings against the namespace itself. It does not suppress warnings against types within the namespace. |
+| `"namespaceanddescendants"` | Suppresses warnings in a namespace and all its descendant symbols. This value is ignored by [legacy code analysis](/visualstudio/code-quality/static-code-analysis-for-managed-code-overview). |
+| `"type"` | Suppresses warnings against a type. |
+
+For [legacy code analysis](/visualstudio/code-quality/static-code-analysis-for-managed-code-overview), `"resource"` is also a valid value. For more information about scopes, see [Suppress code analysis warnings](/visualstudio/code-quality/in-source-suppression-overview#suppressmessage-attribute).
+
  ]]></format>
         </remarks>
       </Docs>
@@ -410,14 +423,14 @@ The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Scope%2A> pro
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets a fully qualified path that represents the target of the attribute.</summary>
-        <value>A fully qualified path that represents the target of the attribute.</value>
+        <summary>Gets or sets a fully qualified path that represents the code analysis target.</summary>
+        <value>A fully qualified path that represents the code analysis target.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Target%2A> property is an optional argument identifying the analysis target of the attribute. An example value is "System.IO.Stream.ctor():System.Void". Because it is fully qualified, it can be long, particularly for targets such as parameters. The analysis tool user interface should be capable of automatically formatting the parameter.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ The <xref:System.Diagnostics.CodeAnalysis.SuppressMessageAttribute.Target%2A> property is an optional argument identifying the analysis target of the attribute. An example value is "System.IO.Stream.ctor():System.Void". Because it is fully qualified, it can be long, particularly for targets such as parameters. The analysis tool user interface should be capable of automatically formatting the parameter.
+
  ]]></format>
         </remarks>
       </Docs>
