Add /Zc:preprocessor article

Colin Robertson · Colin Robertson · commit 2a47ee2567be · 2020-09-10T16:53:22.000-07:00
diff --git a/docs/build/reference/experimental-preprocessor.md b/docs/build/reference/experimental-preprocessor.md
@@ -1,31 +1,31 @@
 ---
 title: "/experimental:preprocessor (Enable preprocessor conformance mode)"
 description: "Use the /experimental:preprocessor compiler option to enable experimental compiler support for a standard conforming preprocessor."
-ms.date: "10/31/2019"
+ms.date: 09/10/2020
 f1_keywords: ["preprocessor", "/experimental:preprocessor"]
 helpviewer_keywords: ["preprocessor conformance", "/experimental:preprocessor", "Enable preprocessor conformance mode"]
 ---
-# /experimental:preprocessor (Enable preprocessor conformance mode)
+# `/experimental:preprocessor` (Enable preprocessor conformance mode)
 
-This option enables an experimental, token-based preprocessor that more closely conforms to C++11 standards, including C99 preprocessor features. For more information, see [MSVC experimental preprocessor overview](../../preprocessor/preprocessor-experimental-overview.md).
+This option is obsolete starting in Visual Studio 2019 version 16.5, replaced by the [`/Zc:preprocessor`](zc-preprocessor.md) compiler option. **`/experimental:preprocessor`** enables an experimental, token-based preprocessor that more closely conforms to C++11 standards, including C99 preprocessor features. For more information, see [MSVC new preprocessor overview](../../preprocessor/preprocessor-experimental-overview.md).
 
 ## Syntax
 
-> **/experimental:preprocessor**[**-**]
+> **`/experimental:preprocessor`**\[**`-`**]
 
 ## Remarks
 
-Use the **/experimental:preprocessor** compiler option to enable the experimental conforming preprocessor. You can use **/experimental:preprocessor-** option to explicitly specify the traditional preprocessor.
+Use the **`/experimental:preprocessor`** compiler option to enable the experimental conforming preprocessor. You can use **`/experimental:preprocessor-`** option to explicitly specify the traditional preprocessor.
 
-The **/experimental:preprocessor** option is available starting in Visual Studio 2017 version 15.8.
+The **`/experimental:preprocessor`** option is available starting in Visual Studio 2017 version 15.8. Starting in Visual Studio 2019 version 16.5, the new preprocessor is complete, and available under the [`/Zc:preprocessor`](zc-preprocessor.md) compiler option.
 
 ### 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++** > **Command Line** property page.
 
-1. Modify the **Additional Options** property to include **/experimental:preprocessor** and then choose **OK**.
+1. Modify the **Additional Options** property to include *`/experimental:preprocessor`* and then choose **OK**.
 
 ## See also
 
diff --git a/docs/build/reference/zc-conformance.md b/docs/build/reference/zc-conformance.md
@@ -28,6 +28,7 @@ These are the **`/Zc`** compiler options:
 | [`/ZcimplicitNoexcept`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). |
 | [`/Zc:inline`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced function or data if it is COMDAT or has internal linkage only (off by default). |
 | [`/Zc:noexceptTypes`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). |
+| [`/Zc:preprocessor`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). |
 | [`/Zc:referenceBinding`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary will not bind to an non-const lvalue reference (off by default). |
 | [`/Zc:rvalueCast`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). |
 | [`/Zc:sizedDealloc`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). |
diff --git a/docs/build/reference/zc-preprocessor.md b/docs/build/reference/zc-preprocessor.md
@@ -0,0 +1,32 @@
+---
+title: "/Zc:preprocessor (Enable preprocessor conformance mode)"
+description: "Use the /Zc:preprocessor compiler option to enable compiler support for a standard conforming preprocessor."
+ms.date: 09/10/2020
+f1_keywords: ["preprocessor", "/Zc:preprocessor"]
+helpviewer_keywords: ["preprocessor conformance", "/Zc:preprocessor", "Enable preprocessor conformance mode"]
+---
+# `/Zc:preprocessor` (Enable preprocessor conformance mode)
+
+This option enables a token-based preprocessor that conforms to C99 and C++11 and later standards. For more information, see [MSVC new preprocessor overview](../../preprocessor/preprocessor-experimental-overview.md).
+
+## Syntax
+
+> **`/Zc:preprocessor`**[**-**]
+
+## Remarks
+
+Use the **`/Zc:preprocessor`** compiler option to enable the conforming preprocessor. You can use **`/Zc:preprocessor-`** option to explicitly specify the traditional (non-conforming) preprocessor.
+
+The **`/Zc:preprocessor`** option is available starting in Visual Studio 2019 version 16.5. An earlier, incomplete version of the new preprocessor option is available in versions of Visual Studio starting in Visual Studio 2017 version 15.8. For more information, see [`/experimental:preprocessor`](experimental-preprocessor.md).
+
+### 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++** > **Command Line** property page.
+
+1. Modify the **Additional Options** property to include *`/Zc:preprocessor`* and then choose **OK**.
+
+## See also
+
+[/Zc (Conformance)](zc-conformance.md)
diff --git a/docs/build/toc.yml b/docs/build/toc.yml
@@ -744,6 +744,8 @@
                       href: ../build/reference/zc-inline-remove-unreferenced-comdat.md
                     - name: "/Zc:noexceptTypes (C++17 noexcept rules)"
                       href: ../build/reference/zc-noexcepttypes.md
+                    - name: "/Zc:preprocessor (Enable preprocessor conformance mode)"
+                      href: ../build/reference/zc-preprocessor.md
                     - name: "/Zc:referenceBinding (Enforce reference binding rules)"
                       href: ../build/reference/zc-referencebinding-enforce-reference-binding-rules.md
                     - name: "/Zc:rvalueCast (Enforce type conversion rules)"
diff --git a/docs/porting/visual-cpp-porting-and-upgrading-guide.md b/docs/porting/visual-cpp-porting-and-upgrading-guide.md
@@ -1,7 +1,7 @@
 ---
 title: "Microsoft C++ porting and upgrading guide"
 description: "Upgrade Microsoft C++ code to the latest version of Visual Studio."
-ms.date: "11/18/2019"
+ms.date: 09/10/2020
 ms.assetid: f5fbcc3d-aa72-41a6-ad9a-a706af2166fb
 ms.topic: "overview"
 ---
@@ -23,7 +23,7 @@ If a legacy application is running satisfactorily, in a secure environment, and
 
 - Build times are faster, because of performance improvements in the compiler and linker.
 
-- Better standards conformance. The [/permissive-](../build/reference/permissive-standards-conformance.md) compiler option helps you identify code that doesn't conform to the current C++ standard.
+- Better standards conformance. The [/permissive-](../build/reference/permissive-standards-conformance.md) compiler option helps you identify code that doesn't conform to the current C++ standard. The [new preprocessor](../preprocessor/preprocessor-experimental-overview.md) supports code conformance, too.
 
 - Better run-time security, including more secure [C Runtime library](../c-runtime-library/security-features-in-the-crt.md) features. And, compiler features such as [guard checking](../build/reference/guard-enable-guard-checks.md) and address sanitizers (new in Visual Studio 2019 version 16.4).
 
diff --git a/docs/preprocessor/preprocessor-experimental-overview.md b/docs/preprocessor/preprocessor-experimental-overview.md
@@ -1,7 +1,7 @@
 ---
-title: "MSVC experimental preprocessor overview"
+title: "MSVC new preprocessor overview"
 description: "The MSVC preprocessor is being updated for conformance with C/C++ standards."
-ms.date: "02/09/2020"
+ms.date: 09/10/2020
 helpviewer_keywords: ["preprocessor, experimental"]
 ---
 # MSVC experimental preprocessor overview
@@ -16,13 +16,11 @@ Visual Studio 2015 uses the traditional preprocessor, which doesn't conform with
 
 We're updating the Microsoft C++ preprocessor to improve standards conformance, fix longstanding bugs, and change some behaviors that are officially undefined. We've also added new diagnostics to warn on errors in macro definitions.
 
-These changes are available by using the [/experimental:preprocessor](../build/reference/experimental-preprocessor.md) compiler switch in Visual Studio 2017 or Visual Studio 2019. The default preprocessor behavior remains the same as in previous versions.
-
-Starting in Visual Studio 2019 version 16.5, experimental preprocessor support for the C++20 standard is feature-complete.
+Starting in Visual Studio 2019 version 16.5, preprocessor support for the C++20 standard is feature-complete. These changes are available starting in Visual Studio 2019 version 16.5 by using the [/Zc:preprocessor](../build/reference/zc-preprocessor.md) compiler switch. An experimental version is available in earlier versions starting in Visual Studio 2017 version 15.8 by using the [/experimental:preprocessor](../build/reference/experimental-preprocessor.md) compiler switch. The default preprocessor behavior remains the same as in previous versions.
 
 ## New predefined macro
 
-You can detect which preprocessor is in use at compile time. Check the value of the predefined macro [\_MSVC\_TRADITIONAL](predefined-macros.md) to tell if the traditional preprocessor is in use. This macro is set unconditionally by versions of the compiler that support it, independent of which preprocessor is invoked. Its value is 1 for the traditional preprocessor. It's 0 for the conforming preprocessor.
+You can detect which preprocessor is in use at compile time. Check the value of the predefined macro [`_MSVC_TRADITIONAL`](predefined-macros.md) to tell if the traditional preprocessor is in use. This macro is set unconditionally by versions of the compiler that support it, independent of which preprocessor is invoked. Its value is 1 for the traditional preprocessor. It's 0 for the conforming preprocessor.
 
 ```cpp
 #if defined(_MSVC_TRADITIONAL) && _MSVC_TRADITIONAL
@@ -238,9 +236,9 @@ DO_THING_FIXED(1, "World");
 // do_thing_one( "Hello", "World");
 ```
 
-## Incomplete features
+## Incomplete features before 16.5
 
-Starting in Visual Studio 2019 version 16.5, the experimental preprocessor is feature-complete for C++20. In previous versions of Visual Studio, the experimental preprocessor is mostly complete, although some preprocessor directive logic still falls back to the traditional behavior. Here's a partial list of incomplete features in Visual Studio versions before 16.5:
+Starting in Visual Studio 2019 version 16.5, the new preprocessor is feature-complete for C++20. In previous versions of Visual Studio, the experimental preprocessor is mostly complete, although some preprocessor directive logic still falls back to the traditional behavior. Here's a partial list of incomplete features in Visual Studio versions before 16.5:
 
 - Support for `_Pragma`
 - C++20 features
