Merge pull request #5809 from carsonRadtke/suppression-justification

Updates to Warning Suppression Documentation

Author: prmerger-automator[bot]

docs/code-quality/c26401.md

@@ -63,7 +63,7 @@ public:
         ref_count_--;
         if (ref_count_ == 0)
         {
-            [[gsl::suppress(i.11)]]
+            [[gsl::suppress("i.11")]]
             delete this; 
         }
     }

docs/code-quality/c26409.md

@@ -49,7 +49,7 @@ public:
         ref_count_--;
         if (ref_count_ == 0)
         {
-            [[gsl::suppress(i.11)]]
+            [[gsl::suppress("i.11")]]
             delete this; 
         }
     }

docs/code-quality/using-the-cpp-core-guidelines-checkers.md

@@ -74,7 +74,7 @@ int main()
     int arr[10];           // warning C26494
     int* p = arr;          // warning C26485
 
-    [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1
+    [[gsl::suppress("bounds.1", justification : "This attribute suppresses Bounds rules #1")]]
     {
         int* q = p + 1;    // warning C26481 (suppressed)
         p = q++;           // warning C26481 (suppressed)
@@ -104,7 +104,7 @@ c:\users\username\documents\visual studio 2015\projects\corecheckexample\coreche
 ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
 ```
 
-The C++ Core Guidelines are there to help you write better and safer code. However, you might find an instance where a rule or a profile shouldn't be applied. It's easy to suppress it directly in the code. You can use the `[[gsl::suppress]]` attribute to keep C++ Core Check from detecting and reporting any violation of a rule in the following code block. You can mark individual statements to suppress specific rules. You can even suppress the entire bounds profile by writing `[[gsl::suppress(bounds)]]` without including a specific rule number.
+The C++ Core Guidelines are there to help you write better and safer code. However, you might find an instance where a rule or a profile shouldn't be applied. It's easy to suppress it directly in the code. You can use the `[[gsl::suppress]]` attribute to keep C++ Core Check from detecting and reporting any violation of a rule in the following code block. You can mark individual statements to suppress specific rules. You can even suppress the entire bounds profile by writing `[[gsl::suppress("bounds")]]` without including a specific rule number.
 
 ## Supported rule sets
 
@@ -197,10 +197,10 @@ The Microsoft C++ compiler has limited support for the `[[gsl::suppress]]` attri
 
 ```cpp
 // Suppress only warnings from the 'r.11' rule in expression.
-[[gsl::suppress(r.11)]] new int;
+[[gsl::suppress("r.11")]] new int;
 
 // Suppress all warnings from the 'r' rule group (resource management) in block.
-[[gsl::suppress(r)]]
+[[gsl::suppress("r")]]
 {
     new int;
 }
@@ -209,7 +209,7 @@ The Microsoft C++ compiler has limited support for the `[[gsl::suppress]]` attri
 // For declarations, you might need to use the surrounding block.
 // Macros are not expanded inside of attributes.
 // Use plain numbers instead of macros from the warnings.h.
-[[gsl::suppress(26400)]]
+[[gsl::suppress("26400")]]
 {
     int *p = new int;
 }

docs/cpp/attributes.md

@@ -77,16 +77,18 @@ The `[[noreturn]]` attribute specifies that a function never returns; in other w
 
 ## Microsoft-specific attributes
 
-### `[[gsl::suppress(rules)]]`
+### `[[gsl::suppress(<tag> [, justification: <narrow-string-literal>])]]`
 
-The Microsoft-specific `[[gsl::suppress(rules)]]` attribute is used to suppress warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules in code. For example, consider this code snippet:
+`<tag>` is a string that specifies the name of the rule to suppress. The optional `justification` field allows you to explain why a warning is being disabled or suppressed. This value will appear in the SARIF output when the `/analyze:log:includesuppressed` option is specified. Its value is a UTF-8 encoded narrow string literal. The `[[gsl::suppress]]` attribute is available in Visual Studio 2022 version 17.14 and later versions.
+
+The Microsoft-specific `[[gsl::suppress]]` attribute is used to suppress warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules in code. For example, consider this code snippet:
 
 ```cpp
 int main()
 {
     int arr[10]; // GSL warning C26494 will be fired
     int* p = arr; // GSL warning C26485 will be fired
-    [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1
+    [[gsl::suppress("bounds.1", justification: "This attribute suppresses Bounds rule #1")]]
     {
         int* q = p + 1; // GSL warning C26481 suppressed
         p = q--; // GSL warning C26481 suppressed
@@ -102,7 +104,7 @@ The example raises these warnings:
 
 - [C26481](../code-quality/c26481.md) (Bounds Rule 1: Don't use pointer arithmetic. Use span instead.)
 
-The first two warnings fire when you compile this code with the CppCoreCheck code analysis tool installed and activated. But the third warning doesn't fire because of the attribute. You can suppress the entire bounds profile by writing `[[gsl::suppress(bounds)]]` without including a specific rule number. The C++ Core Guidelines are designed to help you write better and safer code. The suppress attribute makes it easy to turn off the warnings when they aren't wanted.
+The first two warnings fire when you compile this code with the CppCoreCheck code analysis tool installed and activated. But the third warning doesn't fire because of the attribute. You can suppress the entire bounds profile by writing `[[gsl::suppress("bounds")]]` without including a specific rule number. The C++ Core Guidelines are designed to help you write better and safer code. The suppress attribute makes it easy to turn off the warnings when they aren't wanted.
 
 ### `[[msvc::flatten]]`
 

docs/preprocessor/warning.md

@@ -13,7 +13,7 @@ Enables selective modification of the behavior of compiler warning messages.
 ## Syntax
 
 > **`#pragma warning(`**\
->  *`warning-specifier`* **`:`** *`warning-number-list`*\
+>  *`warning-specifier`* **`:`** *`warning-number-list`* [ **`,`** **`justification`** **`:`** *`string-literal`*]\
 >  [**`;`** *`warning-specifier`* **`:`** *`warning-number-list`* ... ] **`)`**\
 > **`#pragma warning( push`** [ **`,`** *n* ] **`)`**\
 > **`#pragma warning( pop )`**
@@ -26,17 +26,26 @@ The following warning-specifier parameters are available.
 |--|--|
 | `1`, `2`, `3`, `4` | Apply the given level to the specified warnings. Also turns on a specified warning that is off by default. |
 | `default` | Reset warning behavior to its default value. Also turns on a specified warning that is off by default. The warning will be generated at its default, documented, level.<br /><br /> For more information, see [Compiler warnings that are off by default](../preprocessor/compiler-warnings-that-are-off-by-default.md). |
-| `disable` | Don't issue the specified warning messages. |
+| `disable` | Don't issue the specified warning messages. The optional **`justification`** property is allowed. |
 | `error` | Report the specified warnings as errors. |
 | `once` | Display the specified message(s) only one time. |
-| `suppress` | Pushes the current state of the pragma on the stack, disables the specified warning for the next line, and then pops the warning stack so that the pragma state is reset. |
+| `suppress` | Pushes the current state of the pragma on the stack, disables the specified warning for the next line, and then pops the warning stack so that the pragma state is reset. The optional **`justification`** property is allowed. |
 
 The following code statement illustrates that a *`warning-number-list`* parameter can contain multiple warning numbers, and that multiple *`warning-specifier`* parameters can be specified in the same pragma directive.
 
 ```cpp
 #pragma warning( disable : 4507 34; once : 4385; error : 164 )
 ```
 
+However, when the **`justification`** field is present, only one warning number can be specified. The following code statement illustrates the use of the **`justification`** field.
+
+```cpp
+#pragma warning( disable : 4507, justification : "This warning is disabled" )
+```
+
+The **`justification`** fields allows you to explain why a warning is being disable or
+suppressed. The **`justification`** field is only supported for the **`disable`** and **`suppress`** *`warning-specifier`*. This value will appear in the SARIF output when the `/analyze:log:includesuppressed` option is specified. Its value is a UTF-8 encoded narrow string literal.
+
 This directive is functionally equivalent to the following code:
 
 ```cpp