Repo sync for protected CLA branch

docs/build/projects-and-build-systems-cpp.md

@@ -1,14 +1,14 @@
 ---
 title: "C/C++ projects and build systems in Visual Studio"
-ms.description: "Use Visual Studio to compile and build C++ projects for Windows, ARM or Linux based on any project system."
+description: "Use Visual Studio to compile and build C++ projects for Windows, ARM, or Linux based on any project system."
 ms.date: "07/17/2019"
 helpviewer_keywords: ["builds [C++]", "C++ projects, building", "projects [C++], building", "builds [C++], options", "C++, build options"]
 ms.assetid: fa6ed4ff-334a-4d99-b5e2-a1f83d2b3008
 ms.topic: "overview"
 ---
 # C/C++ projects and build systems in Visual Studio
 
-You can use Visual Studio to edit, compile and build any C++ code base with full IntelliSense support without having to convert that code into a Visual Studio project or compile with the MSVC toolset. For example, you can edit a cross-platform CMake project in Visual Studio on a Windows machine, then compile it for Linux using g++ on a remote Linux machine.
+You can use Visual Studio to edit, compile, and build any C++ code base with full IntelliSense support without having to convert that code into a Visual Studio project or compile with the MSVC toolset. For example, you can edit a cross-platform CMake project in Visual Studio on a Windows machine, then compile it for Linux using g++ on a remote Linux machine.
 
 ## C++ compilation
 
@@ -22,25 +22,25 @@ Basic C++ compilation involves three main steps:
 
 ## The MSVC toolset
 
-The Microsoft C++ compiler, linker, standard libraries, and related utilities comprise the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the toolset as a standalone package for free from the [Build Tools for Visual Studio 2019 download location](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019).
+The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the toolset as a free standalone package from [Build Tools for Visual Studio 2019 download](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019).
 
 You can build simple programs by invoking the MSVC compiler (cl.exe) directly from the command line. The following command accepts a single source code file, and invokes cl.exe to build an executable called *hello.exe*:
 
 ```cmd
 cl /EHsc hello.cpp
 ```
 
-Note that here the compiler (cl.exe) automatically invokes the C++ preprocessor and the linker to produce the final output file.  For more information, see [Building on the command line](building-on-the-command-line.md).
+Here the compiler (cl.exe) automatically invokes the C++ preprocessor and the linker to produce the final output file. For more information, see [Building on the command line](building-on-the-command-line.md).
 
 ## Build systems and projects
 
-Most real-world programs use some kind of *build system* to manage complexities of compiling multiple source files for multiple configurations (i.e. debug vs. release), multiple platforms (x86, x64, ARM, and so on), custom build steps, and even multiple executables that must be compiled in a certain order. You make settings in a build configuration file(s), and the build system accepts that file as input before it invoke the compiler. The set of source code files and build configuration files needed to build an executable file is called a *project*.
+Most real-world programs use some kind of *build system* to manage complexities of compiling multiple source files for multiple configurations (debug vs. release), multiple platforms (x86, x64, ARM, and so on), custom build steps, and even multiple executables that must be compiled in a certain order. You make settings in a build configuration file(s), and the build system accepts that file as input before it invoke the compiler. The set of source code files and build configuration files needed to build an executable file is called a *project*.
 
 The following list shows various options for Visual Studio Projects - C++:
 
 - create a Visual Studio project by using the Visual Studio IDE and configure it by using property pages. Visual Studio projects produce programs that run on Windows. For an overview, see [Compiling and Building](/visualstudio/ide/compiling-and-building-in-visual-studio) in the Visual Studio documentation.
 
-- open a folder that contains a CMakeLists.txt file. CMake support is integrated into Visual Studio. You can use the IDE to edit, test and debug without modifying the CMake files in any way. This enables you to work in the same CMake project as others who might be using different editors. CMake is the recommended approach for cross-platform development. For more information, see [CMake projects](cmake-projects-in-visual-studio.md).
+- open a folder that contains a CMakeLists.txt file. CMake support is integrated into Visual Studio. You can use the IDE to edit, test, and debug without modifying the CMake files in any way. This enables you to work in the same CMake project as others who might be using different editors. CMake is the recommended approach for cross-platform development. For more information, see [CMake projects](cmake-projects-in-visual-studio.md).
 
 - open a loose folder of source files with no project file. Visual Studio will use heuristics to build the files. This is an easy way to compile and run small console applications. For more information, see [Open Folder projects](open-folder-projects-cpp.md).
 
@@ -50,45 +50,45 @@ The following list shows various options for Visual Studio Projects - C++:
 
 ## MSBuild from the command line
 
-You can invoke MSBuild from the command line by passing it a .vcxproj file along with command-line options. This approach requires a good understanding of MSBuild, and is recommended only when absolutely necessary. For more information, see [MSBuild](msbuild-visual-cpp.md).
+You can invoke MSBuild from the command line by passing it a .vcxproj file along with command-line options. This approach requires a good understanding of MSBuild, and is recommended only when necessary. For more information, see [MSBuild](msbuild-visual-cpp.md).
 
 ## In This Section
 
-[Visual Studio projects](creating-and-managing-visual-cpp-projects.md)
+[Visual Studio projects](creating-and-managing-visual-cpp-projects.md)\
 How to create, configure, and build C++ projects in Visual Studio using its native build system (MSBuild).
 
-[CMake projects](cmake-projects-in-visual-studio.md)
+[CMake projects](cmake-projects-in-visual-studio.md)\
 How to code, build, and deploy CMake projects in Visual Studio.
 
-[Open Folder projects](open-folder-projects-cpp.md)
-How to use Visual Studio to code, build and deploy C++ projects based on any arbitrary build system, or no build system. at all.
+[Open Folder projects](open-folder-projects-cpp.md)\
+How to use Visual Studio to code, build, and deploy C++ projects based on any arbitrary build system, or no build system at all.
 
-[Release builds](release-builds.md)
+[Release builds](release-builds.md)\
 How to create and troubleshoot optimized release builds for deployment to end users.
 
-[Use the MSVC toolset from the command line](building-on-the-command-line.md)<br/>
+[Use the MSVC toolset from the command line](building-on-the-command-line.md)\
 Discusses how to use the C/C++ compiler and build tools directly from the command line rather than using the Visual Studio IDE.
 
-[Building DLLs in Visual Studio](dlls-in-visual-cpp.md)
-How to create, debug and deploy C/C++ DLLs (shared libraries) in Visual Studio.
+[Building DLLs in Visual Studio](dlls-in-visual-cpp.md)\
+How to create, debug, and deploy C/C++ DLLs (shared libraries) in Visual Studio.
 
-[Walkthrough: Creating and Using a Static Library](walkthrough-creating-and-using-a-static-library-cpp.md)
-How to create a .lib binary file.
+[Walkthrough: Creating and Using a Static Library](walkthrough-creating-and-using-a-static-library-cpp.md)\
+How to create a **.lib** binary file.
 
-[Building C/C++ Isolated Applications and Side-by-side Assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md)
+[Building C/C++ Isolated Applications and Side-by-side Assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md)\
 Describes the deployment model for Windows Desktop applications, based on the idea of isolated applications and side-by-side assemblies.
 
-[Configure C++ projects for 64-bit, x64 targets](configuring-programs-for-64-bit-visual-cpp.md)
+[Configure C++ projects for 64-bit, x64 targets](configuring-programs-for-64-bit-visual-cpp.md)\
 How to target 64-bit x64 hardware with the MSVC build tools.
 
-[Configure C++ projects for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md)
+[Configure C++ projects for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md)\
 How to use the MSVC build tools to target ARM hardware.
 
-[Optimizing Your Code](optimizing-your-code.md)
+[Optimizing Your Code](optimizing-your-code.md)\
 How to optimize your code in various ways including program guided optimizations.
 
-[Configuring Programs for Windows XP](configuring-programs-for-windows-xp.md)
+[Configuring Programs for Windows XP](configuring-programs-for-windows-xp.md)\
 How to target Windows XP with the MSVC build tools.
 
-[C/C++ Building Reference](reference/c-cpp-building-reference.md)<br/>
+[C/C++ Building Reference](reference/c-cpp-building-reference.md)\
 Provides links to reference articles about program building in C++, compiler and linker options, and various build tools.

docs/c-language/c-keywords.md

@@ -1,7 +1,7 @@
 ---
 title: "C Keywords"
 description: "Keywords in Standard C and Microsoft C compiler extensions."
-ms.date: 10/12/2020
+ms.date: 10/15/2020
 helpviewer_keywords: ["keywords [C]", "redefining keywords", "Microsoft-specific keywords"]
 ms.assetid: 2d932335-97bf-45cd-b367-4ae00db0ff42
 ---
@@ -121,7 +121,7 @@ The following keywords and special identifiers are recognized by the Microsoft C
 
 <sup>5</sup> For compatibility with previous versions, these keywords are available both with two leading underscores and a single leading underscore when Microsoft extensions are enabled.
 
-<sup>6</sup> When <assert.h> is not included, the Microsoft Visual C compiler maps **`static_assert`** to the C11 **`_Static_assert`** keyword.
+<sup>6</sup> If you don't include <assert.h>, the Microsoft Visual C compiler maps **`static_assert`** to the C11 **`_Static_assert`** keyword.
 
 Microsoft extensions are enabled by default. To assist in creating portable code, you can disable Microsoft extensions by specifying the [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) option during compilation. When you use this option, some Microsoft-specific keywords are disabled.
 

docs/c-language/noreturn.md

@@ -0,0 +1,65 @@
+---
+title: "_Noreturn keyword and noreturn macro (C11)"
+description: "Describes the `_Noreturn` keyword and `noreturn` macro."
+ms.date: 10/16/2020
+f1_keywords: ["_Noreturn_c", "noreturn"]
+helpviewer_keywords: ["keywords [C]"]
+---
+
+# `_Noreturn` keyword and `noreturn` macro (C11)
+
+The `_Noreturn` keyword was introduced in C11. It tells the compiler that the function it's applied to doesn't return. The compiler knows that the code following a call to a `_Noreturn` function is unreachable.
+
+A convenience macro, `noreturn`, provided in <stdnoreturn.h>, maps to the `_Noreturn` keyword.
+
+The primary benefits for using `_Noreturn` (or the equivalent `noreturn`) are making the intention of the function clear in the code for future readers, and detecting unintentionally unreachable code.
+
+## Example using `noreturn` macro and `_Noreturn `keyword
+
+The following example demonstrates the `_Noreturn` keyword and the equivalent `noreturn` macro.
+
+IntelliSense may generate a spurious error, `E0065`, if you use the macro `noreturn` that you can ignore. It doesn't prevent you from running the sample.
+
+```C
+// Compile with Warning Level4 (/W4) and /std:c11
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdnoreturn.h>
+
+noreturn void fatal_error(void)
+{
+    exit(3);
+}
+
+_Noreturn void not_coming_back(void)
+{
+    puts("There's no coming back");
+    fatal_error();
+    return; // warning C4645 - function declared with noreturn has a return statement
+}
+
+void done(void)
+{
+    puts("We'll never get here");
+}
+
+int main(void)
+{
+    not_coming_back();
+    done(); // warning c4702 - unreachable code
+
+    return 0;
+}
+```
+
+## Requirements
+
+|Macro|Required header|
+|-------------|---------------------|
+|**`noreturn`**|\<stdnoreturn.h>|
+
+## See also
+
+[/std (Specify language standard version)](../build/reference/std-specify-language-standard-version.md)\
+[/W4 (Specify warning level)](../build/reference/compiler-option-warning-level.md)
+[C4702 warning](../error-messages\compiler-warnings\compiler-warning-level-4-c4702.md)

docs/c-language/toc.yml

@@ -434,6 +434,8 @@
                 href: ../c-language/inline-functions.md
               - name: Inline assembler (C)
                 href: ../c-language/inline-assembler-c.md
+              - name: _Noreturn (C)
+                href: ../c-language/noreturn.md                
           - name: DLL import and export functions
             items: 
               - name: DLL import and export functions

docs/error-messages/compiler-warnings/c4388.md

@@ -0,0 +1,48 @@
+---
+title: "Compiler Warning (level 4) C4388"
+description: "Microsoft C/C++ compiler warning C4388, its causes and resolution."
+ms.date: 10/16/2020
+f1_keywords: ["C4388"]
+helpviewer_keywords: ["C4388"]
+---
+# Compiler Warning (level 4) C4388
+
+> '*token*' : signed/unsigned mismatch
+
+Using the *token* operator to compare a **`signed`** and a larger **`unsigned`** number required the compiler to convert the **`signed`** value to the larger **`unsigned`** type.
+
+## Remarks
+
+One way to fix this warning is if you cast one of the two types when you compare **`signed`** and larger **`unsigned`** types.
+
+This warning is off by default. You can use [/Wall](../../build/reference/compiler-option-warning-level.md) or **`/w44388`** to enable it on the command line as a level 4 warning. Or, use [`#pragma warning(default:4388)`](../../preprocessor/warning.md) in your source file. For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md).
+
+## Example
+
+This sample generates C4388 and shows how to fix it:
+
+```cpp
+// C4388.cpp
+// compile with: cl /EHsc /W4 C4388.cpp
+#pragma warning(default: 4388)
+
+int main() {
+    unsigned long long uc = 0;
+    int c = 0;
+    unsigned long long c2 = c; // implicit conversion
+
+    if (uc < c)                       // C4388
+        uc = 0;
+
+    if (uc < (unsigned long long)(c)) // OK
+        uc = 0;
+
+    if (uc < c2)                      // Also OK
+        uc = 0;
+}
+```
+
+## See also
+
+[Compiler Warning (Level 3) C4018](compiler-warning-level-3-c4018.md)\
+[Compiler Warning (Level 4) C4389](compiler-warning-level-4-c4389.md)

docs/error-messages/compiler-warnings/compiler-warning-level-3-c4018.md

@@ -1,31 +1,44 @@
 ---
 title: "Compiler Warning (level 3) C4018"
-ms.date: "11/04/2016"
+description: "Microsoft C/C++ compiler warning C4018, its causes and resolution."
+ms.date: 10/16/2020
 f1_keywords: ["C4018"]
 helpviewer_keywords: ["C4018"]
-ms.assetid: 6e8cbb04-d914-4319-b431-cbc2fbe40eb1
 ---
 # Compiler Warning (level 3) C4018
 
-'expression' : signed/unsigned mismatch
+> '*token*' : signed/unsigned mismatch
 
-Comparing a signed and unsigned number required the compiler to convert the signed value to unsigned.
+Using the *token* operator to compare **`signed`** and **`unsigned`** numbers required the compiler to convert the **`signed`** value to **`unsigned`**.
 
-This warning may be fixed if you cast one of the two types when testing signed and unsigned types.
+## Remarks
 
-The following sample generates C4018:
+One way to fix this warning is if you cast one of the two types when you compare **`signed`** and **`unsigned`** types.
+
+## Example
+
+This sample generates C4018 and shows how to fix it:
 
 ```cpp
 // C4018.cpp
-// compile with: /W3
+// compile with: cl /EHsc /W4 C4018.cpp
 int main() {
-   unsigned int uc = 0;
-   int c = 0;
-   unsigned int c2 = 0;
+    unsigned int uc = 0;
+    int c = 0;
+    unsigned int c2 = c; // implicit conversion
+
+    if (uc < c)           // C4018
+        uc = 0;
 
-   if (uc < c) uc = 0;   // C4018
+    if (uc < unsigned(c)) // OK
+        uc = 0;
 
-   // OK
-   if (uc == c2) uc = 0;
+    if (uc < c2)          // Also OK
+       uc = 0;
 }
 ```
+
+## See also
+
+[Compiler Warning (Level 4) C4388](c4388.md)\
+[Compiler Warning (Level 4) C4389](compiler-warning-level-4-c4389.md)

docs/error-messages/compiler-warnings/compiler-warning-level-4-c4389.md

@@ -1,30 +1,49 @@
 ---
 title: "Compiler Warning (level 4) C4389"
-ms.date: "11/04/2016"
+description: "Microsoft C/C++ compiler warning C4389, its causes and resolution."
+ms.date: 10/16/2020
 f1_keywords: ["c4389"]
 helpviewer_keywords: ["C4389"]
-ms.assetid: fc0e3a8e-f766-437c-b7f1-e61abb2a8765
 ---
 # Compiler Warning (level 4) C4389
 
-'operator' : signed/unsigned mismatch
+> '*equality-operator*' : signed/unsigned mismatch
 
-An operation involved signed and unsigned variables. This could result in a loss of data.
+An **`==`** or **`!=`** operation involved **`signed`** and **`unsigned`** variables. This could result in a loss of data.
+
+## Remarks
+
+One way to fix this warning is if you cast one of the two types when you compare **`signed`** and **`unsigned`** types.
+
+## Example
 
 The following sample generates C4389:
 
 ```cpp
 // C4389.cpp
-// compile with: /W4
-#pragma warning(default: 4389)
+// compile with: cl /EHsc /W4 C4389.cpp
 
 int main()
 {
    int a = 9;
    unsigned int b = 10;
+   int result = 0;
+
    if (a == b)   // C4389
-      return 0;
+      result = 1;
    else
-      return 0;
-};
+      result = 2;
+
+   if (unsigned(a) == b) // OK
+      result = 3;
+   else
+      result = 4;
+
+   return result;
+}
 ```
+
+## See also
+
+[Compiler Warning C4018](compiler-warning-level-3-c4018.md)\
+[Compiler Warning (Level 4) C4388](c4388.md)