4/15/2025 AM Publish (#5873)

Albertyang0 · carsonRadtke · TylerMSFT · web-flow · commit 22029abbf621 · 2025-04-15T10:29:30.000-07:00
* docs for justification in pragma warning * docs for gsl::suppress * teach gsl::suppress("rule") instead of gsl::suppress(rule) * doc - portion of flag * acrolinx * related to #5230 - call out buffer fill behavior * edit * acrolinx/link fix * Confirm merge from FromPublicMasterBranch to main to sync with https://github.com/MicrosoftDocs/cpp-docs (branch main) (#5870) * vswprintf/_vswprintf_l return value description update. * Return value/Remarks sections update. * Behavior summary update. * Behavior summary update. * Merge pull request #5867 from MicrosoftDocs/main 4/10/2025 AM Publish * Update behavior description for `buffer` and `count` conditions The behavior is slightly different than stated. * Update return value behavior for valid buffer behave is different than written here. * Clarify vswprintf return values for count zero behavior is a little different for count = 0 case. * Update remarks and behavior summary sections The behavior in debug mode applies to all functions on this page, so made more prominent. * Fix NULL character formatting in documentation * 4/11/2025 AM Publish (#5869) * doc - portion of flag * acrolinx --------- Co-authored-by: TylerMSFT <TylerMSFT@users.noreply.github.com> Co-authored-by: Jill Grant <72043882+JillGrant615@users.noreply.github.com> * Clarify vswprintf behavior when count is zero * Standardize 'null' to 'NULL' --------- Co-authored-by: Nikita Leontiev <nikita.leontiev@gmail.com> Co-authored-by: Bo wen Yang <160521015+Albertyang0@users.noreply.github.com> Co-authored-by: learn-build-service-prod[bot] <113403604+learn-build-service-prod[bot]@users.noreply.github.com> Co-authored-by: Learn Build Service GitHub App <Learn Build Service LearnBuild@microsoft.com> Co-authored-by: Tyler Whitney <TylerMSFT@users.noreply.github.com> Co-authored-by: Jill Grant <72043882+JillGrant615@users.noreply.github.com> Co-authored-by: Courtney Wales <62625502+Court72@users.noreply.github.com> * Add Arm64 forceInterlockedFunctions option (#5822) * Learn Editor: Update compiler-options-listed-by-category.md * Learn Editor: Update compiler-options-listed-alphabetically.md * Learn Editor: Update force-interlocked-functions.md * Learn Editor: Update force-interlocked-functions.md * update Metadata * Update force-interlocked-functions.md with github id author name * Reorder compiler options in toc.yml to be alphabetical * Learn Editor: Update compiler-options-listed-alphabetically.md * Learn Editor: Update compiler-options-listed-by-category.md * Learn Editor: Update force-interlocked-functions.md * change article metadata * Learn Editor: Update force-interlocked-functions.md * Fix casing in toc.yml for forceInterlockedFunctions * Add 'items' section to toc.yml to revert previous change * Fix indentation in toc.yml file * Update metadata and improve documentation wording * Update metadata in force-interlocked-functions.md tidied up metdata * Fix typos and improve clarity in documentation * Update description for `/forceInterlockedFunctions` option * Clarify CPU capability/ runtime description in documentation * Update remark on Armv8.0 instructions * Remove unneeded template comments and update livelock remarks in documentation * Add "---" to metadata --------- Co-authored-by: Tyler Whitney <TylerMSFT@users.noreply.github.com> * address feedback * small edits --------- Co-authored-by: Carson Radtke <carsonradtke@microsoft.com> Co-authored-by: TylerMSFT <TylerMSFT@users.noreply.github.com> Co-authored-by: Jill Grant <72043882+JillGrant615@users.noreply.github.com> Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com> Co-authored-by: learn-build-service-prod[bot] <113403604+learn-build-service-prod[bot]@users.noreply.github.com> Co-authored-by: Nikita Leontiev <nikita.leontiev@gmail.com> Co-authored-by: Learn Build Service GitHub App <Learn Build Service LearnBuild@microsoft.com> Co-authored-by: Courtney Wales <62625502+Court72@users.noreply.github.com> Co-authored-by: Emily Bao <149544249+emilybao@users.noreply.github.com> Co-authored-by: Stacy Chambers <102548089+Stacyrch140@users.noreply.github.com>
diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md
@@ -67,6 +67,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/Fd`](fd-program-database-file-name.md) | Renames program database file. |
 | [`/Fe`](fe-name-exe-file.md) | Renames the executable file. |
 | [`/feature`](feature-arm64.md) | Enable architecture features.<sup>17.10</sup> |
+| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.<sup>17.14</sup> |
 | [`/FI<file>`](fi-name-forced-include-file.md) | Preprocesses the specified include file. |
 | [`/Fi`](fi-preprocess-output-file-name.md) | Specifies the preprocessed output file name. |
 | [`/Fm`](fm-name-mapfile.md) | Creates a mapfile. |
@@ -261,6 +262,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. |
 
 <sup>17.10</sup> This option is available starting in Visual Studio 2022 version 17.10.
+<sup>17.14</sup> This option is available starting in Visual Studio 2022 version 17.14.
 
 ## See also
 
diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md
@@ -44,6 +44,7 @@ This article contains a categorical list of compiler options. For an alphabetica
 | [`/EHr`](eh-exception-handling-model.md) | Always generate `noexcept` runtime termination checks. |
 | [`/EHs`](eh-exception-handling-model.md) | Enable C++ exception handling (no SEH exceptions). |
 | [`/feature`](feature-arm64.md) | Enable architecture features.<sup>17.10</sup> |
+| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.<sup>17.14</sup> |
 | [`/fp:contract`](fp-specify-floating-point-behavior.md) | Consider floating-point contractions when generating code. |
 | [`/fp:except[-]`](fp-specify-floating-point-behavior.md) | Consider floating-point exceptions when generating code. |
 | [`/fp:fast`](fp-specify-floating-point-behavior.md) | "fast" floating-point model; results are less predictable. |
@@ -329,6 +330,7 @@ Experimental options may only be supported by certain versions of the compiler.
 | [`/Zg`](zg-generate-function-prototypes.md) | Removed in Visual Studio 2015. Generates function prototypes. |
 
 <sup>17.10</sup> This option is available starting in Visual Studio 2022 version 17.10.
+<sup>17.14</sup> This option is available starting in Visual Studio 2022 version 17.14.
 
 ## See also
 
diff --git a/docs/build/reference/constexpr-control-constexpr-evaluation.md b/docs/build/reference/constexpr-control-constexpr-evaluation.md
@@ -1,51 +1,48 @@
 ---
 description: "Learn more about: /constexpr (Control constexpr evaluation)"
 title: "/constexpr (Control constexpr evaluation)"
-ms.date: "08/15/2017"
+ms.date: 04/14/2025
 f1_keywords: ["/constexpr", "-constexpr"]
 helpviewer_keywords: ["/constexpr control constexpr evaluation [C++]", "-constexpr control constexpr evaluation [C++]", "constexpr control constexpr evaluation [C++]"]
-ms.assetid: 76d56784-f5ad-401d-841d-09d1059e8b8c
 ---
 # /constexpr (Control constexpr evaluation)
 
-Use the **/constexpr** compiler options to control parameters for **`constexpr`** evaluation at compile time.
+Use the **`/constexpr`** compiler options to control parameters for **`constexpr`** evaluation at compile time.
 
 ## Syntax
 
-> **/constexpr:depth**<em>N</em>\
-> **/constexpr:backtrace**<em>N</em>\
-> **/constexpr:steps**<em>N</em>
+> `/constexpr:depth`<em>N</em>\
+> `/constexpr:backtrace`<em>N</em>\
+> `/constexpr:steps`<em>N</em>
 
 ## Arguments
 
-**depth**<em>N</em>
+**`depth`**<em>N</em>\
 Limit the depth of recursive **`constexpr`** function invocation to *N* levels. The default is 512.
 
-**backtrace**<em>N</em>
+**`backtrace`**<em>N</em>\
 Show up to *N* **`constexpr`** evaluations in diagnostics. The default is 10.
 
-**steps**<em>N</em>
-Terminate **`constexpr`** evaluation after *N* steps. The default is 100,000.
+**`steps`**<em>N</em>\
+Terminate **`constexpr`** evaluation after *N* steps. The default is 100,000. A step refers to an individual computation taken towards evaluating the constant expression. Increasing the maximum number of steps might cause compilation to take longer in cases where compilation would otherwise fail.
 
 ## Remarks
 
-The **/constexpr** compiler options control compile-time evaluation of **`constexpr`** expressions. Evaluation steps, recursion levels, and backtrace depth are controlled to prevent the compiler from spending too much time on **`constexpr`** evaluation. For more information on the **`constexpr`** language element, see [constexpr (C++)](../../cpp/constexpr-cpp.md).
+The **`/constexpr`** compiler options control compile-time evaluation of **`constexpr`** expressions. Evaluation steps, recursion levels, and backtrace depth are controlled to prevent the compiler from spending too much time on **`constexpr`** evaluation. For more information on the **`constexpr`** language element, see [`constexpr` (C++)](../../cpp/constexpr-cpp.md).
 
-The **/constexpr** options are available beginning in Visual Studio 2015.
+The **`/constexpr`** flag is available beginning in Visual Studio 2015.
 
 ### To set this compiler option in the Visual Studio development environment
 
 1. Open your project's **Property Pages** dialog box.
-
 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
-
-1. Enter any **/constexpr** compiler options in the **Additional Options** box. Choose **OK** or **Apply** to save your changes.
+1. Enter **/constexpr** compiler options in the **Additional Options** box. Choose **OK** to save your changes.
 
 ### To set this compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
 
 ## See also
 
-[MSVC Compiler Options](compiler-options.md)<br/>
+[MSVC Compiler Options](compiler-options.md)\
 [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
diff --git a/docs/build/reference/force-interlocked-functions.md b/docs/build/reference/force-interlocked-functions.md
@@ -0,0 +1,55 @@
+---
+title:       "/forceInterlockedFunctions"
+description: "Learn more about /forceInterlockedFunctions"
+ms.date:     03/07/2025
+---
+# `/forceInterlockedFunctions`
+
+Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 Large System Extension (LSE) atomic instructions based on CPU capability at runtime.
+
+## Syntax
+
+> **`/forceInterlockedFunctions`**[**`-`**]
+
+## Remarks
+When possible, this flag avoids using Armv8.0 load and store exclusive instructions, as these instructions can result in livelocks.
+This flag forces the following interlocked intrinsics to be generated as out-of-line functions:
+
+|Operation|8|16|32|64|128|Pointer|
+|-|-------|--------|--------|--------|-------|-------|
+|Add|None|None|Full|Full|None|None|
+|And|Full|Full|Full|Full|None|None|
+|CompareExchange|Full|Full|Full|Full|Full|Full|
+|Decrement|None|Full|Full|Full|None|None|
+|Exchange|Full|Full|Full|Full|None|Full|
+|ExchangeAdd|Full|Full|Full|Full|None|None|
+|Increment|None|Full|Full|Full|None|None|
+|Or|Full|Full|Full|Full|None|None|
+|Xor|Full|Full|Full|Full|None|None|
+|bittestandreset|None|None|Full|Full|None|None|
+|bittestandset|None|None|Full|Full|None|None|
+
+Key:
+
+- **Full**: supports plain, `_acq`, `_rel`, and `_nf` forms.
+
+- **None**: Not supported
+
+For more information about interlocked intrinsics, see the "Interlocked intrinsics" section in [Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md).
+
+### To set the `/forceInterlockedFunctions` compiler option in Visual Studio
+
+1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
+
+1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
+
+1. In the **Additional options** box, add *`/forceInterlockedFunctions`* to enable. Choose **OK** to save your changes.
+
+### To set this compiler option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
+
+## See also
+[Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md)\
+[MSVC compiler options](compiler-options.md)\
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
diff --git a/docs/build/reference/u-u-undefine-symbols.md b/docs/build/reference/u-u-undefine-symbols.md
@@ -1,12 +1,11 @@
 ---
 title: "/U, /u (Undefine symbols)"
 description: "Use the Microsoft C/C++ compiler /U and /u options to undefine preprocessor symbols."
-ms.date: 09/03/2020
+ms.date: 04/14/2025
 f1_keywords: ["VC.Project.VCCLCompilerTool.UndefinePreprocessorDefinitions", "VC.Project.VCCLWCECompilerTool.UndefinePreprocessorDefinitions", "VC.Project.VCCLCompilerTool.UndefineAllPreprocessorDefinitions", "/u", "VC.Project.VCCLWCECompilerTool.UndefineAllPreprocessorDefinitions"]
 helpviewer_keywords: ["-U compiler option [C++]", "Undefine Symbols compiler option", "/U compiler option [C++]", "U compiler option [C++]"]
-ms.assetid: 7bc0474f-6d1f-419b-807d-0d8816763b2a
 ---
-# /U, /u (Undefine symbols)
+# `/U`, `/u` (Undefine symbols)
 
 The **`/U`** compiler option undefines the specified preprocessor symbol. The **`/u`** compiler option undefines the Microsoft-specific symbols that the compiler defines.
 
@@ -17,7 +16,7 @@ The **`/U`** compiler option undefines the specified preprocessor symbol. The **
 
 ## Arguments
 
-*symbol*<br/>
+*`symbol`*\
 The preprocessor symbol to undefine.
 
 ## Remarks
@@ -44,9 +43,7 @@ For a complete list of Microsoft-specific predefined macros, see [Predefined mac
 ### To set this compiler option in the Visual Studio development environment
 
 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
-
-1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page.
-
+1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page.
 1. Modify the **Undefine Preprocessor Definitions** or **Undefine All Preprocessor Definitions** properties.
 
 ### To set this compiler option programmatically
@@ -55,9 +52,9 @@ For a complete list of Microsoft-specific predefined macros, see [Predefined mac
 
 ## See also
 
-[MSVC compiler options](compiler-options.md)<br/>
-[MSVC compiler command-line syntax](compiler-command-line-syntax.md)<br/>
-[**`/J`** (Default char type is unsigned)](j-default-char-type-is-unsigned.md)<br/>
-[**`/GR`** (Enable run-time type information)](gr-enable-run-time-type-information.md)<br/>
-[**`/EH`** (Exception handling model)](eh-exception-handling-model.md)<br/>
+[MSVC compiler options](compiler-options.md)\
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\
+[**`/J`** (Default char type is unsigned)](j-default-char-type-is-unsigned.md)\
+[**`/GR`** (Enable run-time type information)](gr-enable-run-time-type-information.md)\
+[**`/EH`** (Exception handling model)](eh-exception-handling-model.md)\
 [**`/MD`**, **`/MT`**, **`/LD`** (Use run-time library)](md-mt-ld-use-run-time-library.md)
diff --git a/docs/build/toc.yml b/docs/build/toc.yml
@@ -562,6 +562,9 @@ items:
                   href: ../build/reference/fc-full-path-of-source-code-file-in-diagnostics.md
                 - name: /feature (Enable architecture features)
                   href: ../build/reference/feature-arm64.md
+                - name: /forceInterlockedFunctions (Generate and link with out-of-line atomic
+                    functions)
+                  href: ./reference/force-interlocked-functions.md
                 - name: /fp (Specify floating-point behavior)
                   href: ../build/reference/fp-specify-floating-point-behavior.md
                 - name: /fpcvt (Floating-point to unsigned integer conversion behavior)
diff --git a/docs/code-quality/c26401.md b/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; 
         }
     }
diff --git a/docs/code-quality/c26409.md b/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; 
         }
     }
diff --git a/docs/code-quality/using-the-cpp-core-guidelines-checkers.md b/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;
 }
diff --git a/docs/cpp/attributes.md b/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]]`
 
diff --git a/docs/preprocessor/warning.md b/docs/preprocessor/warning.md
@@ -13,7 +13,7 @@ Enables selective modification of the behavior of compiler warning messages.
 ## Syntax
 
 > **`#pragma warning(`**\
-> &emsp;*`warning-specifier`* **`:`** *`warning-number-list`*\
+> &emsp;*`warning-specifier`* **`:`** *`warning-number-list`* [ **`,`** **`justification`** **`:`** *`string-literal`*]\
 > &emsp;[**`;`** *`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

Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ public:`
`63`	`63`	`ref_count_--;`
`64`	`64`	`if (ref_count_ == 0)`
`65`	`65`	`{`
`66`		`- [[gsl::suppress(i.11)]]`
	`66`	`+ [[gsl::suppress("i.11")]]`
`67`	`67`	`delete this;`
`68`	`68`	`}`
`69`	`69`	`}`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ public:`
`49`	`49`	`ref_count_--;`
`50`	`50`	`if (ref_count_ == 0)`
`51`	`51`	`{`
`52`		`- [[gsl::suppress(i.11)]]`
	`52`	`+ [[gsl::suppress("i.11")]]`
`53`	`53`	`delete this;`
`54`	`54`	`}`
`55`	`55`	`}`