Merge pull request #4015 from MicrosoftDocs/main637922167238454474

Repo sync for protected CLA branch

Author: colin-home

docs/build/clang-support-msbuild.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: Clang/LLVM support in Visual Studio projects"
 title: "Clang/LLVM support in Visual Studio projects"
-ms.date: 11/11/2021
+ms.date: 06/29/2022
 ms.description: "Configure a Visual Studio MSBuild project to use the Clang/LLVM toolchain."
 helpviewer_keywords: ["Clang support for C++ MSBuild projects"]
 ---
@@ -35,7 +35,7 @@ To configure a Visual Studio project to use Clang, right-click on the project no
 
 If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *%VCINSTALLDIR%\\Tools\\Llvm\\bin\\* and *%VCINSTALLDIR%\\Tools\\Llvm\\x64\\bin\\*.
 
-If you're using a custom Clang installation, you can either modify **Project** > **Properties** > **VC++ Directories** > **Configuration Properties** > **Executable Directories** by adding the custom Clang installation root as the first directory there, or change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location).
+If you're using a custom Clang installation, you can change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location).
 
 ## Configure a Linux project to use Clang tools
 

docs/build/creating-precompiled-header-files.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: Precompiled header files"
 title: "Precompiled Header Files"
-ms.date: 03/02/2022
+ms.date: 06/29/2022
 helpviewer_keywords: ["precompiled header files, creating", "PCH files, creating", "cl.exe compiler, precompiling code", ".pch files, creating"]
 ms.assetid: e2cdb404-a517-4189-9771-c869c660cb1b
 ---
@@ -34,9 +34,9 @@ You can precompile both C and C++ programs. In C++ programming, it's common prac
 
 You can precompile any C or C++ code; you're not limited to precompiling only header files.
 
-Precompiling requires planning, but it offers significantly faster compilations if you precompile source code other than simple header files.
+Precompiling requires planning, but it offers much faster compilations if you precompile source code other than simple header files.
 
-Precompile code when you know that your source files use common sets of header files but don't include them in the same order, or when you want to include source code in your precompilation.
+Precompile code when you know that your source files use common sets of header files, or when you want to include source code in your precompilation.
 
 The precompiled-header options are [`/Yc` (Create Precompiled Header File)](reference/yc-create-precompiled-header-file.md) and [`/Yu` (Use Precompiled Header File)](reference/yu-use-precompiled-header-file.md). Use **`/Yc`** to create a precompiled header. When used with the optional [`hdrstop`](../preprocessor/hdrstop.md) pragma, **`/Yc`** lets you precompile both header files and source code. Select **`/Yu`** to use an existing precompiled header in the existing compilation. You can also use **`/Fp`** with the **`/Yc`** and **`/Yu`** options to provide an alternative name for the precompiled header.
 
@@ -50,7 +50,7 @@ Because PCH files contain information about the machine environment and memory a
 
 The [`/Yu`](reference/yu-use-precompiled-header-file.md) compiler option lets you specify which PCH file to use.
 
-When you use a PCH file, the compiler assumes the same compilation environment (one that uses consistent compiler options, pragmas, and so on) that was in effect when you created the PCH file, unless you specify otherwise. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections.
+When you use a PCH file, the compiler assumes the same compilation environment that was in effect when you created the PCH file, unless you specify otherwise. The compilation environment includes the compiler options, pragmas, and so on. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections.
 
 ### Compiler option consistency
 
@@ -144,7 +144,7 @@ This table lists compiler options that might trigger an inconsistency warning wh
 | **`/D `**| Define constants and macros | Must be the same between the compilation that created the precompiled header and the current compilation. The state of defined constants isn't checked. However, unpredictable results can occur if your files depend on the values of the changed constants. |
 | **`/E`** or **`/EP`** | Copy preprocessor output to standard output | Precompiled headers don't work with the **`/E`** or **`/EP`** option. |
 | **`/Fr`** or **`/FR`** | Generate Microsoft Source Browser information | For the **`/Fr`** and **`/FR`** options to be valid with the **`/Yu`** option, they must also have been in effect when the precompiled header was created. Subsequent compilations that use the precompiled header also generate Source Browser information. Browser information is placed in a single *`.sbr`* file and is referenced by other files in the same manner as CodeView information. You can't override the placement of Source Browser information. |
-| **`/GA`**, **`/GD`**, **`/GE`**, **`/Gw`**, or **`/GW`** | Windows protocol options | Must be the same between the compilation that created the precompiled header and the current compilation. If these options differ, a warning message results. |
+| **`/GA`**, **`/GD`**, **`/GE`**, **`/Gw`**, or **`/GW`** | Windows protocol options | Must be the same between the compilation that created the precompiled header and the current compilation. The compiler emits a warning if these options differ. |
 | **`/Zi`** | Generate complete debugging information | If this option is in effect when the precompiled header is created, subsequent compilations that use the precompilation can use that debugging information. If **`/Zi`** isn't in effect when the precompiled header is created, subsequent compilations that use the precompilation and the **`/Zi`** option trigger a warning. The debugging information is placed in the current object file, and local symbols defined in the precompiled header aren't available to the debugger. |
 
 > [!NOTE]
@@ -158,7 +158,7 @@ For another approach to using the manual precompiled-header options in a project
 
 ## PCH files in the build process
 
-The code base of a software project is often contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with the ones in the example code found in [Sample makefile for PCH](#sample-makefile-for-pch) and [Example code for PCH](#example-code-for-pch).
+The code base of a software project is often contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with the example code found in [Sample makefile for PCH](#sample-makefile-for-pch) and [Example code for PCH](#example-code-for-pch).
 
 The figure uses three diagrammatic devices to show the flow of the build process. Named rectangles represent each file or macro; the three macros represent one or more files. Shaded areas represent each compile or link action. Arrows show which files and macros are combined during the compilation or linking process.
 
@@ -248,6 +248,8 @@ For more information on makefiles, see [NMAKE reference](reference/nmake-referen
 
 The following source files are used in the makefile described in [PCH files in the build process](#pch-files-in-the-build-process) and [Sample makefile for PCH](#sample-makefile-for-pch). The comments contain important information.
 
+Source file `ANOTHER.H`:
+
 ```cpp
 // ANOTHER.H : Contains the interface to code that is not
 //             likely to change.
@@ -259,6 +261,8 @@ void savemoretime( void );
 #endif // __ANOTHER_H
 ```
 
+Source file `STABLE.H`:
+
 ```cpp
 // STABLE.H : Contains the interface to code that is not likely
 //            to change. List code that is likely to change
@@ -271,6 +275,8 @@ void savetime( void );
 #endif // __STABLE_H
 ```
 
+Source file `UNSTABLE.H`:
+
 ```cpp
 // UNSTABLE.H : Contains the interface to code that is
 //              likely to change. As the code in a header
@@ -285,6 +291,8 @@ void notstable( void );
 #endif // __UNSTABLE_H
 ```
 
+Source file `APPLIB.CPP`:
+
 ```cpp
 // APPLIB.CPP : This file contains the code that implements
 //              the interface code declared in the header
@@ -310,6 +318,8 @@ void notstable( void )
     }
 ```
 
+Source file `MYAPP.CPP`:
+
 ```cpp
 // MYAPP.CPP : Sample application
 //             All precompiled code other than the file listed

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

@@ -1,7 +1,7 @@
 ---
 title: "/external (External headers diagnostics)"
 description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage."
-ms.date: 02/17/2022
+ms.date: 06/29/2022
 f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external", "VC.Project.VCCLCompilerTool.ExternalDirectoriesEnv", "VC.Project.VCCLCompilerTool.ExternalIncludeDirectories", "VC.Project.VCCLCompilerTool.ExternalWarningLevel", "VC.Project.VCCLCompilerTool.TreatExternalTemplatesAsInternal"]
 helpviewer_keywords: ["/external compiler option [C++]", "-external compiler option [C++]", "external compiler option [C++]"]
 ---
@@ -68,6 +68,8 @@ All the existing mechanisms to enable, disable, and suppress warnings still work
 
 This sample program has two source files, *`program.cpp`* and *`header_file.h`*. The *`header_file.h`* file is in an *`include_dir`* subdirectory of the directory containing the *`program.cpp`* file:
 
+Source file `include_dir/header_file.h`:
+
 ```cpp
 // External header: include_dir/header_file.h
 
@@ -79,6 +81,8 @@ struct sample_struct
 };
 ```
 
+Source file `program.cpp`:
+
 ```cpp
 // User code: program.cpp
 #include <header_file.h>

docs/build/reference/gh-enable-penter-hook-function.md

@@ -1,7 +1,7 @@
 ---
 title: "/Gh (Enable _penter hook function)"
 description: "Describes the /Gh compiler option to call the supplied _penter function."
-ms.date: "07/06/2020"
+ms.date: 06/29/2022
 f1_keywords: ["_penter"]
 helpviewer_keywords: ["/Gh compiler option [C++]", "Gh compiler option [C++]", "_penter function", "-Gh compiler option [C++]"]
 ms.assetid: 1510a082-8a0e-486e-a309-6add814b494f
@@ -42,6 +42,8 @@ This declaration isn't available for 64-bit projects.
 
 The following code, when compiled with **/Gh**, shows how `_penter` is called twice; once when entering function `main` and once when entering function `x`. The example consists of two source files, which you compile separately.
 
+Source file `local_penter.cpp`:
+
 ```cpp
 // local_penter.cpp
 // compile with: cl /EHsc /c local_penter.cpp
@@ -74,6 +76,8 @@ extern "C" void __declspec(naked) __cdecl _penter( void ) {
 }
 ```
 
+Source file `Gh_compiler_option.cpp`:
+
 ```cpp
 // Gh_compiler_option.cpp
 // compile with: cl /EHsc /Gh Gh_compiler_option.cpp local_penter.obj
@@ -90,7 +94,6 @@ int main() {
 When run, the local `_penter` function is called on entry to `main` and `x`:
 
 ```Output
-
 In a function!
 In a function!
 ```

docs/build/reference/internal-partition.md

@@ -1,7 +1,7 @@
 ---
 title: "/internalPartition"
 description: "Use the /internalPartition compiler option to treat the input file as an internal partition unit."
-ms.date: 04/18/2022
+ms.date: 06/29/2022
 author: "tylermsft"
 ms.author: "twhitney"
 f1_keywords: ["/internalPartition", "VC.Project.VCCLCompilerTool.Interface"]
@@ -19,13 +19,17 @@ Use the **`/internalPartition`** compiler option to treat the input file as an *
 
 The following example demonstrates how to use the `/internalPartition` option:
 
+Source file `m-internals.cpp`:
+
 ```cpp
 // m-internals.cpp
 module m:internals;
 
 void internalFunc() {} // cannot have `export` since this is an internal partition
 ```
 
+Source file `m.ixx`:
+
 ```cpp
 // m.ixx
 export module m;

docs/build/reference/permissive-standards-conformance.md

@@ -1,12 +1,12 @@
 ---
 title: "/permissive- (Standards conformance)"
 description: "Reference guide to the Microsoft C++ /permissive- (Standards conformance) compiler option."
-ms.date: 03/15/2022
+ms.date: 06/29/2022
 f1_keywords: ["/permissive", "VC.Project.VCCLCompilerTool.ConformanceMode"]
 helpviewer_keywords: ["/permissive compiler options [C++]", "-permissive compiler options [C++]", "Standards conformance compiler options", "permissive compiler options [C++]"]
 ms.assetid: db1cc175-6e93-4a2e-9396-c3725d2d8f71
 ---
-# /permissive- (Standards conformance)
+# `/permissive-` (Standards conformance)
 
 Specify standards conformance mode to the compiler. Use this option to help you identify and fix conformance issues in your code, to make it both more correct and more portable.
 
@@ -41,7 +41,7 @@ The MSVC compiler in earlier versions of Visual Studio 2017 doesn't support all
 
 Here are some examples of code that is detected as non-conforming when you use **`/permissive-`**, along with suggested ways to fix the issues.
 
-#### Use default as an identifier in native code
+#### Use `default` as an identifier in native code
 
 ```cpp
 void func(int default); // Error C2321: 'default' is a keyword, and
@@ -103,6 +103,8 @@ union U
 
 #### Hidden friend name lookup rules
 
+A declaration outside a class can make a hidden friend visible:
+
 ```cpp
 // Example 1
 struct S {
@@ -115,6 +117,8 @@ using type = void (*)(S *);
 type p = &f; // error C2065: 'f': undeclared identifier.
 ```
 
+Use of literal `nullptr` can prevent argument dependent lookup:
+
 ```cpp
 // Example 2
 struct S {
@@ -158,19 +162,25 @@ void func() {
 }
 ```
 
-#### Use of ATL Attributes
+#### Use of ATL attributes
+
+Microsoft-specific ATL attributes can cause issues under **`/permissive-`**:
 
 ```cpp
 // Example 1
 [uuid("594382D9-44B0-461A-8DE3-E06A3E73C5EB")]
 class A {};
 ```
 
+You can fix the issue by using the **`__declspec`** form instead:
+
 ```cpp
 // Fix for example 1
 class __declspec(uuid("594382D9-44B0-461A-8DE3-E06A3E73C5EB")) B {};
 ```
 
+A more complex example:
+
 ```cpp
 // Example 2
 [emitidl];
@@ -187,6 +197,8 @@ class CFoo : public ICustom
 {};
 ```
 
+Resolution requires extra build steps. In this case, create an IDL file:
+
 ```cpp
 // Fix for example 2
 // First, create the *.idl file. The vc140.idl generated file can be
@@ -241,7 +253,7 @@ Common errors that may result from this change include:
 
 - `error C2446: ':': no conversion from 'B' to 'A'`
 
-A typical code pattern that can cause this issue is when some class `C` provides both a non-explicit constructor from another type `T` and a non-explicit conversion operator to type `T`. In this case, both the conversion of the second argument to the type of the third argument, and the conversion of the third argument to the type of the second argument, are valid conversions. Since both are valid, it's ambiguous according to the standard.
+A typical code pattern that can cause this issue is when some class `C` provides both a non-explicit constructor from another type `T` and a non-explicit conversion operator to type `T`. The conversion of the second argument to the third argument's type is a valid conversion. So is the conversion of the third argument to the second argument's type. Since both are valid, it's ambiguous according to the standard.
 
 ```cpp
 // Example 1: class that provides conversion to and initialization from some type T