Resolve syncing conflicts from FromPrivateLiveToMaster to main (#4587)

* wordsmithing

* add build iso standard library modules option

* wording update, plus pickup some acrolinx fixes

* acrollinx

* remove note that IDE doesn't support importing std

* unsaved file

* Delete build-an-opengl-es-application-on-android-and-ios.md

Visual Studio no longer supports opengl, updating documentation to reflect his.

* Update index.yml

* Update visual-cpp-for-cross-platform-mobile-development.md

Removing references to opengl-es

* Update cross-platform-mobile-development-examples.md

Remove opengl examples

* Update toc.yml

* add last available version

* small updates

* add version

* restore

* Update documentation for warning C28196.

* Update build-an-opengl-es-application-on-android-and-ios.md

* Update c28196.md

small edit pass

* removed note about default setting

* fix broken links

* restore toc

---------

Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com>
Co-authored-by: Garrett Campbell <86264750+gcampbell-msft@users.noreply.github.com>
Co-authored-by: Garrett Campbell <gcampbell@microsoft.com>
Co-authored-by: Michael Woerister <michaelwoerister@posteo>
Co-authored-by: Tyler Whitney <TylerMSFT@users.noreply.github.com>
Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com>
Co-authored-by: Jill Grant <v-jillg@microsoft.com>
Co-authored-by: Jeff Borsecnik <123032460+American-Dipper@users.noreply.github.com>
Co-authored-by: huypub <38988242+huypub@users.noreply.github.com>

Author: 9 people

docs/build/cmake-presets-vs.md

@@ -1,7 +1,7 @@
 ---
 title: Configure and build with CMake Presets
 description: "Reference for using CMake Presets to configure and build CMake projects."
-ms.date: 02/01/2023
+ms.date: 06/09/2023
 ms.topic: reference
 ---
 
@@ -386,9 +386,9 @@ Instead, set the path to `vcpkg.cmake` by using the `VCPKG_ROOT` environment var
  },
 ```
 
-`VCPKG_ROOT` should be set to the root of your vcpkg installation. For more information, see [vcpkg environment variables](https://github.com/microsoft/vcpkg/blob/master/docs/users/config-environment.md).
+`VCPKG_ROOT` should be set to the root of your vcpkg installation. For more information, see [vcpkg environment variables](/vcpkg/users/config-environment).
 
-If you're already using a CMake toolchain file and want to enable vcpkg integration, see [Using multiple toolchain files](https://github.com/microsoft/vcpkg/blob/master/docs/users/buildsystems/integration.md#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg.
+If you're already using a CMake toolchain file and want to enable vcpkg integration, see [Using multiple toolchain files](/vcpkg/users/buildsystems/cmake-integration#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg.
 
 ## Variable substitution in  *`launch.vs.json`* and  *`tasks.vs.json`*
 

docs/build/reference/c-cpp-prop-page.md

@@ -1,10 +1,9 @@
 ---
 title: "C/C++ Project Properties (Visual Studio)"
 description: "Reference guide to the Visual Studio Microsoft C/C++ project Property Pages properties."
-ms.date: 11/17/2022
+ms.date: 6/9/2023
 ms.topic: "article"
 f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalModuleDirectories", "VC.Project.VCCLCompilerTool.ScanSourceForModuleDependencies"]
-ms.assetid: 16375038-4917-4bd0-9a2a-26343c1708b7
 ---
 # C/C++ Property Pages
 
@@ -51,7 +50,7 @@ Specifies the type of debugging information generated by the compiler.  This pro
 - **None** - Produces no debugging information, so compilation may be faster.
 - **C7 compatible** - Select the type of debugging information created for your program and whether this information is kept in object (.obj) files or in a program database (PDB).
 - **Program Database** - Produces a program database (PDB) that contains type information and symbolic debugging information for use with the debugger. The symbolic debugging information includes the names and types of variables and functions, and line numbers.
-- **Program Database for Edit And Continue** - Produces a program database, as described above, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature.
+- **Program Database for Edit And Continue** - Produces a program database, as described previously, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature.
 
 ### Support Just My Code Debugging
 
@@ -142,7 +141,7 @@ Select the level of [inline function](../../cpp/inline-functions-cpp.md) expansi
 - **Default**
 - **Disabled** - Disables inline expansion, which is on by default.
 - **Only __inline** - Expands only functions marked as **`inline`**, **`__forceinline`**, or **`__inline`**. Or, in a C++ member function, defined within a class declaration.
-- **Any Suitable** - Expands functions marked as **`inline`** or **`__inline`** and any other function that the compiler chooses. (Expansion occurs at the compiler's discretion, often referred to as *auto-inlining*.)
+- **Any Suitable** - Expands functions marked as **`inline`** or **`__inline`** and any other function that the compiler chooses. (Expansion occurs at the compiler's discretion, often referred to as *autoinlining*.)
 
 ### Enable Intrinsic Functions
 
@@ -243,21 +242,21 @@ Specify runtime library for linking. Sets [`/MT`, `/MTd`, `/MD`, `/MDd`](md-mt-l
 #### Choices
 
 - **Multi-threaded** - Causes your application to use the multithread, static version of the run-time library.
-- **Multi-threaded Debug** - Defines _DEBUG and _MT. This option also causes the compiler to place the library name *LIBCMTD.lib* into the *`.obj`* file so that the linker will use *LIBCMTD.lib* to resolve external symbols.
+- **Multi-threaded Debug** - Defines `_DEBUG` and `_MT`. This option also causes the compiler to place the library name *`LIBCMTD.lib`* into the *`.obj`* file so that the linker will use *`LIBCMTD.lib`* to resolve external symbols.
 - **Multi-threaded DLL** - Causes your application to use the multithread- and DLL-specific version of the run-time library. Defines `_MT` and `_DLL` and causes the compiler to place the library name *MSVCRT.lib* into the *`.obj`* file.
-- **Multi-threaded Debug DLL** - Defines `_DEBUG`, `_MT`, and `_DLL` and causes your application to use the debug multithread- and DLL-specific version of the run-time library. It also causes the compiler to place the library name *MSVCRTD.lib* into the *`.obj`* file.
+- **Multi-threaded Debug DLL** - Defines `_DEBUG`, `_MT`, and `_DLL` and causes your application to use the debug multithread- and DLL-specific version of the run-time library. It also causes the compiler to place the library name *`MSVCRTD.lib`* into the *`.obj`* file.
 
 ### Struct Member Alignment
 
 Specifies 1, 2, 4, or 8-byte boundaries for struct member alignment. Sets [`/Zp`](zp-struct-member-alignment.md).
 
 #### Choices
 
-- **1 Byte** - Packs structures on 1-byte boundaries. Same as **`/Zp`**.
-- **2 Bytes** - Packs structures on 2-byte boundaries.
-- **4 Bytes** - Packs structures on 4-byte boundaries.
-- **8 Bytes** - Packs structures on 8-byte boundaries (default).
-- **16 Bytes** - Packs structures on 16-byte boundaries.
+- **1 Byte** - Packs structures on one-byte boundaries. Same as **`/Zp`**.
+- **2 Bytes** - Packs structures on two-byte boundaries.
+- **4 Bytes** - Packs structures on four-byte boundaries.
+- **8 Bytes** - Packs structures on eight-byte boundaries (default).
+- **16 Bytes** - Packs structures on sixteen-byte boundaries.
 - **Default** - Default alignment settings.
 
 ### Security Check
@@ -288,7 +287,7 @@ Allows the compiler to generate parallel code for loops identified using `#pragm
 
 ### Enable Enhanced Instruction Set
 
-Enable use of instructions found on processors that support enhanced instruction sets. For example, the SSE, SSE2, AVX, and AVX2 enhancements to IA-32. And, the AVX and AVX2 enhancements to x64. Currently **`/arch:SSE`** and **`/arch:SSE2`** are only available when building for the x86 architecture. If no option is specified, the compiler will use instructions found on processors that support SSE2. Use of enhanced instructions can be disabled with **`/arch:IA32`**. For more information, see [`/arch (x86)`](arch-x86.md), [`/arch (x64)`](arch-x64.md), [`/arch (ARM64)`](arch-arm64.md), and [`/arch (ARM)`](arch-arm.md).
+Enable use of instructions found on processors that support enhanced instruction sets. For example, the SSE, SSE2, AVX, and AVX2 enhancements to IA-32. And, the AVX and AVX2 enhancements to x64. Currently **`/arch:SSE`** and **`/arch:SSE2`** are only available when building for the x86 architecture. If no option is specified, the compiler uses instructions found on processors that support SSE2. Use of enhanced instructions can be disabled with **`/arch:IA32`**. For more information, see [`/arch (x86)`](arch-x86.md), [`/arch (x64)`](arch-x64.md), [`/arch (ARM64)`](arch-arm64.md), and [`/arch (ARM)`](arch-arm.md).
 
 #### Choices
 
@@ -332,11 +331,7 @@ Spectre mitigations for CVE 2017-5753. Sets [`/Qspectre`](qspectre.md).
 
 Suppresses or enables language extensions. Sets [`/Za`](za-ze-disable-language-extensions.md).
 
-### Conformance mode
-
-Enables or suppresses conformance mode. Sets [`/permissive-`](permissive-standards-conformance.md).
-
-### Treat wchar_t As Built in Type
+### Treat WChar_t As Built in Type
 
 When specified, the type **`wchar_t`** becomes a native type that maps to **`__wchar_t`** in the same way that **`short`** maps to **`__int16`**. [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) is on by default.
 
@@ -360,9 +355,9 @@ Adds code for checking C++ object types at run time (*runtime type information*,
 
 Enables OpenMP 2.0 language extensions. Sets [`/openmp`](openmp-enable-openmp-2-0-support.md).
 
-### C++ Language Standard
+### <a name="cpplang"></a> C++ Language Standard
 
-Determines the C++ language standard the compiler enables. The default value doesn't set a standard option, so the compiler uses its default C++14 setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md).
+Determines the C++ language standard that the compiler enables. The default value doesn't set a standard option, so the compiler uses its default C++14 setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md).
 
 #### Choices
 
@@ -372,10 +367,28 @@ Determines the C++ language standard the compiler enables. The default value doe
 - **ISO C++20 Standard (/std:c++20)**
 - **Preview - Features from the Latest C++ Working Draft  (/std:c++latest)**
 
-### Enable C++ Modules (experimental)
+### C Language Standard
+
+Determines the C language standard that the compiler enables. The default value doesn't set a standard option, so the compiler uses its default legacy MSVC setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md).
+
+#### Choices
+
+- **Default (Legacy MSVC)**
+- **ISO C11 Standard (/std:c11)**
+- **ISO C17 (2018) Standard (/std:c17)**
+
+### Conformance mode
+
+Enables or suppresses conformance mode. Sets [`/permissive-`](permissive-standards-conformance.md).
+
+### Enable Experimental C++ Standard Library Modules
 
 Experimental support for the C++ Modules TS and Standard Library modules.
 
+### Build ISO C++23 Standard Library Modules
+
+Starting in Visual Studio 17.6, when this property is enabled and [C++ Language Standard](#cpplang) is set to `/std:c++latest`, Visual C++ projects automatically find and build ISO C++23 Standard Library modules. This enables you to `import std` or `import std.compat` in your C++ code.
+
 ## C/C++ Precompiled Headers Properties
 
 ### Create/Use Precompiled Header

docs/code-quality/c28196.md

@@ -2,12 +2,53 @@
 description: "Learn more about: Warning C28196"
 title: Warning C28196
 ms.date: 11/04/2016
-f1_keywords: ["C28196"]
+f1_keywords: ["C28196", "RETURNING_BAD_RESULT", "__WARNING_RETURNING_BAD_RESULT"]
 helpviewer_keywords: ["C28196"]
 ms.assetid: 5ee89e96-2796-4316-a64c-702463ca1374
 ---
 # Warning C28196
 
 > The requirement is not satisfied. (The expression does not evaluate to true.)
 
-This warning indicates that the function prototype for the function being analyzed has a `__notnull`, `__null` or `__drv_valueIs` on an `_Out_` parameter or the return value, but the value returned is inconsistent with that annotation.
+This warning indicates that the function being analyzed has a `__notnull`, `__null`, `__drv_valueIs` or similar annotation on an `_Out_` parameter or the return value, but the value returned is inconsistent with that annotation.
+
+## Remarks
+
+Annotations like `__notnull` describe invariants about `_Out_` parameters and return values, which serves both as documentation and as a sanity check for the author of the function. Warning C28196 indicates a mismatch between the annotations and the actual behavior of the function. The warning can be useful for discovering cases where a function might behave unexpectedly for certain input values. It's then up to the author to decide what the intended behavior of the function is and either adapt the annotations or the implementation accordingly.
+
+## Examples
+
+The following function causes warning C28196 because it's annotated with `_Ret_notnull_` even though some code paths return a null pointer.
+
+```cpp
+#include <sal.h>
+
+_Ret_notnull_
+Item *get_item(_In_reads_(len) Item *items, size_t len, size_t index) {
+    if (index >= len) {
+        return nullptr;
+    }
+
+    return items + index;
+}
+```
+
+To resolve this issue, refine the annotation to accurately reflect the function's behavior.
+
+```cpp
+#include <sal.h>
+
+_When_(index < len, _Ret_notnull_)
+Item *get_item(_In_reads_(len) Item *items, size_t len, size_t index) {
+    if (index >= len) {
+        return nullptr;
+    }
+
+    return items + index;
+}
+```
+
+## See also
+
+[Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md)
+[Specifying When and Where an Annotation Applies](./specifying-when-and-where-an-annotation-applies.md)

docs/cpp/modules-cpp.md

@@ -1,22 +1,22 @@
 ---
 title: "Overview of modules in C++"
-ms.date: 03/30/2022
+ms.date: 04/24/2023
 helpviewer_keywords: ["modules [C++]", "modules [C++], overview"]
 description: Modules in C++20 provide a modern alternative to header files.
 ---
 # Overview of modules in C++
 
-C++20 introduces *modules*, a modern solution that turns C++ libraries and programs into components. A *module* is a set of source code files that are compiled independently of the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming)) that import them. Modules eliminate or reduce many of the problems associated with the use of header files. They often reduce compilation times. Macros, preprocessor directives, and non-exported names declared in a module aren't visible outside the module. They have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit don't participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions, and templates. The compiler can process that file much faster than a header file. And, the compiler can reuse it every place where the module is imported in a project.
+C++20 introduces *modules*, a modern solution that turns C++ libraries and programs into components. A *module* is a set of source code files that are compiled independently of the source files (or more precisely, the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming)) that import them. Modules eliminate or reduce many of the problems associated with the use of header files. They often reduce compilation times. Macros, preprocessor directives, and non-exported names declared in a module aren't visible outside the module. They have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit don't participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions, and templates. The compiler can process that file much faster than a header file. And, the compiler can reuse it every place where the module is imported in a project.
 
-You can use modules side by side with header files. A C++ source file can `import` modules and also `#include` header files. In some cases, you can import a header file as a module rather than include it textually by using `#include` in the preprocessor. We recommend you use modules in new projects rather than header files as much as possible. For larger existing projects under active development, experiment with converting legacy headers to modules. Base your adoption on whether you get a meaningful reduction in compilation times.
+You can use modules side by side with header files. A C++ source file can `import` modules and also `#include` header files. In some cases, you can import a header file as a module, which is faster than using `#include` to process it with the preprocessor. We recommend that you use modules in new projects rather than header files as much as possible. For larger existing projects under active development, experiment with converting legacy headers to modules. Base your adoption on whether you get a meaningful reduction in compilation times.
 
 To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md).
 
 ## Enable modules in the Microsoft C++ compiler
 
 As of Visual Studio 2022 version 17.1, C++20 standard modules are fully implemented in the Microsoft C++ compiler.
 
-Before it was specified by the C++20 standard, Microsoft had experimental support for modules in the Microsoft C++ compiler. The compiler also supported importing the Standard Library as modules, described below.
+Before it was specified by the C++20 standard, Microsoft had experimental support for modules. The compiler also supported importing pre-built Standard Library modules, described below.
 
 Starting with Visual Studio 2022 version 17.5, importing the Standard Library as a module is both standardized and fully implemented in the Microsoft C++ compiler. This section describes the older, experimental method, which is still supported. For information about the new standardized way to import the Standard Library using modules, see [Import the C++ standard library using modules](tutorial-import-stl-named-module.md).