Add system_header pragma doc

Author: Colin Robertson

docs/build/reference/external-external-headers-diagnostics.md

@@ -1,19 +1,19 @@
 ---
 title: "/external (External headers diagnostics)"
 description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage."
-ms.date: 06/07/2021
+ms.date: 07/02/2021
 f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external"]
 helpviewer_keywords: ["/external compiler option [C++]", "-external compiler option [C++]", "external compiler option [C++]"]
 ---
 # `/external` (External headers diagnostics)
 
-The **`/external`** compiler options let you specify compiler diagnostic behavior for certain header files. "External" headers are the natural complement of "Just my code": Header files such as system files or third-party library files that you can't or don't intend to change. Since you aren't going to change these files, you may decide it isn't useful to see diagnostic messages from the compiler about them. The `/external` compiler options give you control over these warnings.
+The **`/external`** compiler options let you specify compiler diagnostic behavior for certain header files. "External" headers are the natural complement of "Just my code": Header files such as system files or third-party library files that you can't or don't intend to change. Since you aren't going to change these files, you may decide it isn't useful to see diagnostic messages from the compiler about them. The **`/external`** compiler options give you control over these warnings.
 
 The **`/external`** compiler options are available starting in Visual Studio 2017 version 15.6. In versions of Visual Studio before Visual Studio 2019 version 16.10, the **`/external`** options require you also set the **`/experimental:external`** compiler option.
 
 ## Syntax
 
-Use external header options:
+Use external header options (Not required in 16.10 and later):
 > **`/experimental:external`**
 
 Specify external headers:
@@ -22,7 +22,11 @@ Specify external headers:
 > **`/external:I`** *`path`*
 
 Specify diagnostics behavior:
-> **`/external:W`**_`n`_\
+> **`/external:W0`**\
+> **`/external:W1`**\
+> **`/external:W2`**\
+> **`/external:W3`**\
+> **`/external:W4`**\
 > **`/external:templates-`**
 
 ### Arguments
@@ -40,7 +44,9 @@ Defines a root directory that contains external headers. All recursive subdirect
 Specifies the name of an environment variable *`var`* that holds a semicolon-separated list of external header directories. It's useful for build systems that rely on environment variables such as `INCLUDE`, which you use to specify the list of external include files. Or, `CAExcludePath`, for files that shouldn't be analyzed by `/analyze`. For example, you can specify `/external:env:INCLUDE` to make every directory in `INCLUDE` an external header directory at once. It's the same as using **`/external:I`** to specify the individual directories, but much less verbose. There should be no space between *`var`* and **`/external:env:`**.
 
 **`/external:Wn`**\
-This option sets the default warning level to *`n`* (a value from 0 to 4) for external headers. For example, **`/external:W0`** effectively turns off warnings for external headers. The **`/external:Wn`** option has an effect similar to wrapping an included header in a `#pragma warning` directive:
+This option sets the default warning level to *`n`* (a value from 0 to 4) for external headers. For example, **`/external:W0`** effectively turns off warnings for external headers. If this option isn't specified, the compiler issues command line warning D9007 for other **`/external`** options. Those options are ignored, because they would have no effect.
+
+The **`/external:Wn`** option has an effect similar to wrapping an included header in a `#pragma warning` directive:
 
 ```cpp
 #pragma warning (push, 0)
@@ -151,7 +157,9 @@ struct sample_struct
 
 With this change to the library header, the author of the library ensures that the global warning level in this header is 4, no matter what gets specified in **`/external:Wn`**. Now all level 4 and above warnings are reported. The library author can also force certain warnings to be errors, disabled, suppressed, or emitted only once in the header. The **`/external`** options don't override that deliberate choice.
 
-`#pragma system_header` is an intrusive header marker that allows library writers to mark certain headers as external. These headers have the warning level specified by **`/external:Wn`**, if any.
+### `system_header` pragma
+
+`#pragma system_header` is an intrusive header marker that allows library writers to mark certain headers as external. A header file containing `#pragma system_header` is considered external from the point of the pragma onward, exactly as if it was in a directory that was specified as external on the command line. The compiler emits any diagnostics after the marker at the warning level specified by **`/external:Wn`**.
 
 ### Limitations
 

docs/cppcx/collections-c-cx.md

@@ -54,7 +54,7 @@ Any element to be stored in a [Platform::Collections::Vector](../cppcx/platform-
 
 [Platform::Collections::VectorIterator](../cppcx/platform-collections-vectoriterator-class.md) and [Platform::Collections::VectorViewIterator](../cppcx/platform-collections-vectorviewiterator-class.md) enable the use of `range for` loops and algorithms like [std::sort](../standard-library/algorithm-functions.md#sort) with an [IVector\<T>](/uwp/api/windows.foundation.collections.ivector-1) container. But `IVector` elements cannot be accessed through C++ pointer dereference; they can be accessed only through [GetAt](/uwp/api/windows.foundation.collections.ivector-1.getat) and [SetAt](/uwp/api/windows.foundation.collections.ivector-1.setat) methods. Therefore, these iterators use the proxy classes `Platform::Details::VectorProxy<T>` and `Platform::Details::ArrowProxy<T>` to provide access to the individual elements through __\*__, __->__, and __\[]__ operators, as required by the Standard Library. Strictly speaking, given an `IVector<Person^> vec`, the type of `*begin(vec)` is `VectorProxy<Person^>`. However, the proxy object is almost always transparent to your code. These proxy objects are not documented because they are only for internal use by the iterators, but it is useful to know how the mechanism works.
 
-When you use a `range for` loop over `IVector` containers, use `auto&&` to enable the iterator variable to bind correctly to the `VectorProxy` elements. If you use **`auto`** or `auto&`, compiler warning C4239 is raised and `VectoryProxy` is mentioned in the warning text.
+When you use a range-based **`for`** loop over `IVector` containers, use `auto&&` to enable the iterator variable to bind correctly to the `VectorProxy` elements. If you use `auto&`, compiler warning [C4239](../error-messages/compiler-warnings/compiler-warning-level-4-c4239.md) is raised and `VectoryProxy` is mentioned in the warning text.
 
 The following illustration shows a `range for` loop over an `IVector<Person^>`. Notice that execution is stopped on the breakpoint on line 64. The **QuickWatch** window shows that the iterator variable `p` is in fact a `VectorProxy<Person^>` that has `m_v` and `m_i` member variables. However, when you call `GetType` on this variable, it returns the identical type to the `Person` instance `p2`. The takeaway is that although `VectorProxy` and `ArrowProxy` might appear in **QuickWatch**, the debugger certain compiler errors, or other places, you typically don't have to explicitly code for them.
 

docs/preprocessor/system-header-pragma.md

@@ -0,0 +1,30 @@
+---
+description: "Learn more about the system_header pragma."
+title: "system_header pragma"
+ms.date: 07/02/2021
+f1_keywords: ["vc-pragma.system_header", "system_header_CPP", "system_header"]
+helpviewer_keywords: ["pragma, system_header", "system_header pragma"]
+no-loc: ["pragma"]
+---
+# `system_header` pragma
+
+Treat the rest of the file as external for diagnostics reports.
+
+## Syntax
+
+> **`#pragma system_header`**
+
+## Remarks
+
+Starting in Visual Studio 2017 version 15.6, the compiler lets you set two different default diagnostic warning levels on the command line. Normally, you use a [`/W0`, `/W1`, `/W2`, `/W3`, or `/W4`](../build/reference/compiler-option-warning-level.md) compiler option to specify a single diagnostic level for all code in a project. However, your project might include system header files or files from external libraries that generate warnings at the specified level. When you can't or don't want to edit these files, you can specify them as *external*. Files specified as external can have a separate compiler diagnostic level applied to them as a group. For more information on how to specify external files and the external warning level to the compiler, see [`/external`](../build/reference/external-external-headers-diagnostics.md).
+
+For example, a common scenario uses the **`/external:W1`** option to apply a **`/W1`** warning level to external library header files, while you use **`/W4 /WX`** on your own code. Then you don't see minor diagnostics for the code that isn't yours.
+
+The **`system_header`** pragma tells the compiler to show diagnostics at the **`/external:Wn`** level for the rest of the source file. The **`system_header`** pragma applies even if no other files are specified as external to the compiler. However, if no **`/external:Wn`** option level is specified, the compiler issues a diagnostic and uses the same warning level it applies to non-external files. Other pragma directives that affect warning behavior still apply after a **`system_header`** pragma.
+
+The **`system_header`** pragma is available starting in Visual Studio 2019 version 16.10.
+
+## See also
+
+[`/external`](../build/reference/external-external-headers-diagnostics.md)
+[Pragma directives and the `__pragma` and `_Pragma` keywords](./pragma-directives-and-the-pragma-keyword.md)