Repo sync for protected CLA branch

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

@@ -1,15 +1,15 @@
 ---
 title: "/external (External headers diagnostics)"
 description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage."
-ms.date: 05/14/2021
+ms.date: 06/07/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 are available starting in Visual Studio 2017 version 15.6. The **`/external`** options require you also set the **`/experimental:external`** compiler option.
+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
 
@@ -28,7 +28,7 @@ Specify diagnostics behavior:
 ### Arguments
 
 **`/experimental:external`**\
-Enables the external headers options, starting in Visual Studio 2017 version 15.6.
+Enables the external headers options. This option isn't required in Visual Studio 2019 version 16.10 and later.
 
 **`/external:anglebrackets`**\
 Treats all headers included by `#include <header>`, where the *`header`* file is enclosed in angle brackets (**`< >`**), as external headers.
@@ -101,20 +101,20 @@ include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'in
 program.cpp(6): note: see reference to class template instantiation 'sample_struct<unsigned int>' being compiled
 ```
 
-To treat the header file as an external file and suppress the warning, you can use this command line instead:
+To treat the header file as an external file and suppress the warning, you can use this command line instead[\*](#note_experimental):
 
 ```cmd
-cl /EHsc /experimental:external /I include_dir /external:anglebrackets /external:W0 /W4 program.cpp
+cl /EHsc /I include_dir /external:anglebrackets /external:W0 /W4 program.cpp
 ```
 
 This command line suppresses the warning inside *`header_file.h`* while preserving warnings inside *`program.cpp`*.
 
 ### Warnings across the internal and external boundary
 
-Setting a low warning level for external headers can hide some actionable warnings. In particular, it can turn off warnings emitted on template instantiations in user code. These warnings might indicate a problem in your code that only happens in instantiations for particular types. (For example, if you forgot to apply a type trait removing `const` or `&`.) To avoid silencing warnings inside templates defined in external headers, you can use the **`/external:templates-`** option. The compiler considers both the effective warning level in the file that defines the template, and the warning level where template instantiation occurs. Warnings emitted inside an external template appear if the template is instantiated within non-external code. For example, this command line re-enables warnings from template sources in the sample code:
+Setting a low warning level for external headers can hide some actionable warnings. In particular, it can turn off warnings emitted on template instantiations in user code. These warnings might indicate a problem in your code that only happens in instantiations for particular types. (For example, if you forgot to apply a type trait removing `const` or `&`.) To avoid silencing warnings inside templates defined in external headers, you can use the **`/external:templates-`** option. The compiler considers both the effective warning level in the file that defines the template, and the warning level where template instantiation occurs. Warnings emitted inside an external template appear if the template is instantiated within non-external code. For example, this command line re-enables warnings from template sources in the sample code[\*](#note_experimental):
 
 ```cmd
-cl /EHsc /experimental:external /I include_dir /external:anglebrackets /external:W0 /external:templates- /W4 program.cpp
+cl /EHsc /I include_dir /external:anglebrackets /external:W0 /external:templates- /W4 program.cpp
 ```
 
 The C4245 warning appears again in the output, even though the template code is inside an external header.
@@ -155,20 +155,22 @@ With this change to the library header, the author of the library ensures that t
 
 ### Limitations
 
-Some warnings emitted by the compiler's back-end code generation aren't affected by the **`/external`** options. These warnings usually start with C47XX, though not all C47XX warnings are back-end warnings.  You can still disable these warnings by using `/wd47XX`. Code analysis warnings are also unaffected, since they don't have warning levels.
+Some warnings emitted by the compiler's back-end code generation aren't affected by the **`/external`** options. These warnings usually start with C47XX, though not all C47XX warnings are back-end warnings.  You can still disable these warnings individually by using `/wd47XX`. Code analysis warnings are also unaffected, since they don't have warning levels.
 
 ### 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. Enter the compiler options in the **Additional Options** box.
+1. Enter the compiler options[\*](#note_experimental) in the **Additional Options** box.
 
 ### To set this compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
 
+<a name="note_experimental"></a>\* Add the `/experimental:external` option to enable the external headers options in versions of Visual Studio before Visual Studio 2019 version 16.10.
+
 ## See also
 
 [MSVC compiler options](compiler-options.md)\

docs/c-runtime-library/reference/setlocale-wsetlocale.md

@@ -1,14 +1,13 @@
 ---
 title: "setlocale, _wsetlocale"
 description: "Describes the Microsoft C runtime (CRT) library functions setlocale and _wsetlocale."
-ms.date: "4/2/2020"
+ms.date: "6/8/2021"
 api_name: ["_wsetlocale", "setlocale", "_o__wsetlocale", "_o_setlocale"]
 api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_wsetlocale", "_tsetlocale", "setlocale"]
 helpviewer_keywords: ["wsetlocale function", "setlocale function", "tsetlocale function", "locales, defining", "_tsetlocale function", "defining locales", "_wsetlocale function"]
-ms.assetid: 3ffb684e-5990-4202-9553-b5339af9520d
 no-loc: [setlocale, _wsetlocale]
 ---
 # `setlocale`, `_wsetlocale`
@@ -171,13 +170,27 @@ The function [`_configthreadlocale`](configthreadlocale.md) is used to control w
 
 ## UTF-8 Support
 
-Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. This means that `char` strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use "`UTF-8`" as the code page when using `setlocale`. For example, `setlocale(LC_ALL, ".utf8")` will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.
+Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. This means that `char` strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use `".UTF8"` as the code page when using `setlocale`. For example, `setlocale(LC_ALL, ".UTF8")` will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.
 
-After calling `setlocale(LC_ALL, ".UTF8")`, you may pass "😊" to `mbtowcs` and it will be properly translated to a `wchar_t` string, whereas previously there was not a locale setting available to do this.
+The string to specify UTF-8 mode is:
+- case-insensitive
+- the hyphen (-) is optional
+- It must be in the code page part of the locale name, so must have a leading period '.'  For example, `"en_US.UTF8"` or `".utf8"`
 
-UTF-8 mode is also enabled for functions that have historically translated `char` strings using the default Windows ANSI code page (ACP). For example, calling [`_mkdir("😊")`](../reference/mkdir-wmkdir.md) while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 prior to running your program. Likewise, calling [`_getcwd()`](../reference/getcwd-wgetcwd.md) inside of that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.
+The following examples show how to specify the UTF-8 string:
 
-The following aspects of the C Runtime that are not able to use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): [`__argv`](../argc-argv-wargv.md), [`_acmdln`](../acmdln-tcmdln-wcmdln.md), and [`_pgmptr`](../pgmptr-wpgmptr.md).
+`".UTF8"`\
+`".UTF-8"`\
+`".utf8"`\
+`".utf-8"`\
+`"en_us.utf8"`\
+`"ja_JP.Utf-8"`
+
+After calling `setlocale(LC_ALL, ".UTF8")`, you may pass "😊" to `mbtowcs` and it will be properly translated to a `wchar_t` string, whereas previously there wasn't a locale setting available to do this.
+
+UTF-8 mode is also enabled for functions that have historically translated `char` strings using the default Windows ANSI code page (ACP). For example, calling [`_mkdir("😊")`](../reference/mkdir-wmkdir.md) while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 before running your program. Likewise, calling [`_getcwd()`](../reference/getcwd-wgetcwd.md) in that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.
+
+The following aspects of the C Runtime can't use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): [`__argv`](../argc-argv-wargv.md), [`_acmdln`](../acmdln-tcmdln-wcmdln.md), and [`_pgmptr`](../pgmptr-wpgmptr.md).
 
 Previous to this support, [`mbrtoc16`, `mbrtoc32`](../reference/mbrtoc16-mbrtoc323.md), [`c16rtomb`, and `c32rtomb`](../reference/c16rtomb-c32rtomb1.md) existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as `wchar_t` on Windows platforms) and UTF-32. For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via `setlocale`.
 
@@ -190,7 +203,7 @@ To use this feature on an OS prior to Windows 10, such as Windows 7, you must us
 |`setlocale`|`<locale.h>`|
 |`_wsetlocale`|`<locale.h>` or `<wchar.h>`|
 
-For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
+For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
 
 ## Example
 

docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md

@@ -1,7 +1,7 @@
 ---
 title: "Compiler Warnings by compiler version"
 description: "Table of Microsoft C/C++ compiler warnings by compiler version."
-ms.date: 10/18/2020
+ms.date: 06/07/2021
 helpviewer_keywords: ["warnings, by compiler version", "cl.exe compiler, setting warning options"]
 ---
 # Compiler Warnings by compiler version
@@ -40,13 +40,32 @@ These versions of the compiler introduced new warnings:
 | Visual Studio 2019 version 16.7 | 19.27.29112.0 |
 | Visual Studio 2019 version 16.8 | 19.28.29330.0 |
 | Visual Studio 2019 version 16.9 | 19.28.29500.0 |
+| Visual Studio 2019 version 16.10 | 19.28.30000.0 |
 
 You can specify only the major number, the major and minor numbers, or the major, minor, and build numbers to the **`/Wv`** option. The compiler reports all warnings that match versions that begin with the specified number. It suppresses all warnings for versions greater than the specified number. For example, **`/Wv:17`** reports warnings introduced in or before any version of Visual Studio 2012, and suppresses warnings introduced by any compiler from Visual Studio 2013 (version 18) or later. To suppress warnings introduced in Visual Studio 2015 update 2 and later, you can use **`/Wv:19.00.23506`**. Use **`/Wv:19.11`** to report the warnings introduced in any version of Visual Studio before Visual Studio 2017 version 15.5, but suppress warnings introduced in Visual Studio 2017 version 15.5 and later.
 
 The following sections list the warnings introduced by each version of Visual C++ that you can suppress by using the **`/Wv`** compiler option. The **`/Wv`** option can't suppress warnings that aren't listed, which predate the specified versions of the compiler.
 
 ::: moniker range=">= msvc-160"
 
+## Warnings introduced in Visual Studio 2019 version 16.10 (compiler version 19.29.30000.0)
+
+These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.29`**.
+
+| Warning | Message |
+|--|--|
+| C5233 | `explicit lambda capture 'identifier' is not used` |
+| C5234 | `file system error: 'filename' is not a valid header-name; ignoring` |
+| C5235 | `JSON parse error: issue; ignoring 'filename'` |
+| C5236 | `JSON ill-formed: issue; ignoring 'filename'` |
+| C5237 | `cannot resolve header unit entry 'string' to a header file in 'filename'; ignoring entry` |
+| C5238 | `file system error: cannot open 'filename' for reading; ignoring` |
+| C5239 | `'Symbol': potentially-throwing function called from a function declared __declspec(nothrow). Undefined behavior may occur if an exception is thrown.` |
+| C5240 | `'attribute-string': attribute is ignored in this syntactic position` |
+| C5241 | `'/exportHeader' usage to lookup header-name is deprecated; prefer '/headerName:arg-1 arg-2=filename'` |
+| C5242 | `syntax error in pragma 'identifier'` |
+| C5243 | `'Type-name': using incomplete class 'symbol' can cause potential one definition rule violation due to ABI limitation` |
+
 ## Warnings introduced in Visual Studio 2019 version 16.9 (compiler version 19.28.29700.0)
 
 These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.28.29500`**.