Merge pull request MicrosoftDocs#3104 from MicrosoftDocs/master

Saisang · web-flow · commit e58918c45316 · 2020-09-01T17:33:33.000Z
9/1 AM Publishing
diff --git a/docs/build/reference/cetcompat.md b/docs/build/reference/cetcompat.md
@@ -1,6 +1,6 @@
 ---
 title: "/CETCOMPAT (CET Shadow Stack compatible)"
-ms.date: "06/30/2020"
+ms.date: "09/01/2020"
 f1_keywords: ["/CETCOMPAT"]
 helpviewer_keywords: ["/CETCOMPAT linker option", "/CETCOMPAT"]
 ---
@@ -36,15 +36,15 @@ Starting in Visual Studio 2019 version 16.7:
 
 1. Select the **CET Shadow Stack Compatible** property.
 
-1. In the dropdown control, choose **`Yes (/CETCOMPAT)`** to enable EH continuation metadata, or **`No (/CETCOMPAT:NO)`** to disable it.
+1. In the dropdown control, choose **`Yes (/CETCOMPAT)`** to mark the binary as CET Shadow Stack compatible , or **`No (/CETCOMPAT:NO)`** to mark it as non-compatible.
 
 In previous versions of Visual Studio 2019:
 
 1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md).
 
 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page.
 
-1. In the **Additional Options** edit control, add *`/CETCOMPAT`* to enable EH continuation metadata, or *`/CETCOMPAT:NO`* to explicitly disable it.
+1. In the **Additional Options** edit control, add *`/CETCOMPAT`* to mark the binary as CET Shadow Stack compatible, or *`/CETCOMPAT:NO`* to explicitly mark it as non-compatible.
 
 ### To set this linker option programmatically
 
diff --git a/docs/build/reference/linker-options.md b/docs/build/reference/linker-options.md
@@ -1,7 +1,7 @@
 ---
 title: "MSVC Linker options"
 description: "A list of the options supported by the Microsoft LINK linker."
-ms.date: "02/09/2020"
+ms.date: "09/01/2020"
 f1_keywords: ["link"]
 helpviewer_keywords: ["linker [C++]", "linker [C++], options listed", "libraries [C++], linking to COFF", "LINK tool [C++], linker options"]
 ms.assetid: c1d51b8a-bd23-416d-81e4-900e02b2c129
@@ -38,6 +38,7 @@ You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify
 |[/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md)|Specifies that a Microsoft intermediate language (MSIL) module should be imported into the assembly.|
 |[/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md)|Embeds a managed resource file in an assembly.|
 |[/BASE](base-base-address.md)|Sets a base address for the program.|
+|[/CETCOMPAT](cetcompat.md)|Marks the binary as CET Shadow Stack compatible.|
 |[/CGTHREADS](cgthreads-compiler-threads.md)|Sets number of cl.exe threads to use for optimization and code generation when link-time code generation is specified.|
 |[/CLRIMAGETYPE](clrimagetype-specify-type-of-clr-image.md)|Sets the type (IJW, pure, or safe) of a CLR image.|
 |[/CLRSUPPORTLASTERROR](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md)|Preserves the last error code of functions that are called through the P/Invoke mechanism.|
diff --git a/docs/code-quality/c26401.md b/docs/code-quality/c26401.md
@@ -5,9 +5,40 @@ ms.topic: "conceptual"
 f1_keywords: ["C26401"]
 helpviewer_keywords: ["C26401"]
 ms.assetid: b9d3d398-697a-4a5d-8bfe-9c667dffb90b
+description: CppCoreCheck rule that enforces C++ Core Guidelines I.11
 ---
 # C26401 DONT_DELETE_NON_OWNER
 
 This check detects places where moving to `owner<T>` can be a good option for the first stage of refactoring. Like C26400 it enforces rules I.11 and R.3, but focuses on the "release" portion of the pointer lifetime. It warns on any call to operator **`delete`** if its target is neither an `owner<T>` nor an implicitly assumed owner. For more information, see [C26400](c26400.md) regarding the **`auto`** declarations. This does include expressions that refer to global variables, formals, and so on.
 
 Warnings C26400 and C26401 always occur with [C26409](c26409.md), but they are more appropriate for scenarios where immediate migration to smart pointers is not feasible. In such cases the `owner<T>` concept can be adopted first and C26409 may be temporarily suppressed.
+
+## See also
+[C++ Core Guidelines I.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i11-never-transfer-ownership-by-a-raw-pointer-t-or-reference-t)
+
+## Example
+```cpp
+struct myStruct {};
+
+myStruct* createMyStruct();
+void function()
+{
+    myStruct* pMyStruct = createMyStruct();
+    // ... 
+    delete pMyStruct; // C26401. Do not delete a raw pointer that is not an owner<T>
+}
+```
+
+See that C26401 is removed if ownership of the pointer is indicated by gsl::owner.
+```cpp
+#include <gsl/pointers>
+struct myStruct {};
+
+gsl::owner<myStruct*> createMyStruct();
+void function()
+{
+    gsl::owner<myStruct*> pMyStruct = createMyStruct();
+    // ... 
+    delete pMyStruct; // no warning.
+}
+```
diff --git a/docs/code-quality/c26408.md b/docs/code-quality/c26408.md
@@ -5,6 +5,7 @@ ms.topic: "conceptual"
 f1_keywords: ["C26408"]
 helpviewer_keywords: ["C26408"]
 ms.assetid: 55b0706f-1107-41c1-8ad0-c9e1e86a3b8c
+description: CppCoreCheck rule that enforces C++ Core Guidelines R.10
 ---
 # C26408 NO_MALLOC_FREE
 
@@ -15,3 +16,23 @@ This warning flags places where `malloc` or `free` is invoked explicitly in acco
 - To detect malloc() we check if a call invokes a global function with name "malloc" or "std::malloc". The function must return a pointer to **`void`** and accept one parameter of unsigned integral type.
 
 - To detect free() we check global functions with names "free" or "std::free" which return no result and accept one parameter, which is a pointer to **`void`**.
+
+## See also
+[C++ Core Guidelines R.10](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r10-avoid-malloc-and-free)
+
+## Example
+```cpp
+#include <new>
+
+struct myStruct {};
+
+void function_malloc_free() {
+    myStruct* ms = static_cast<myStruct*>(malloc(sizeof(myStruct))); // C26408
+    free(ms); // C26408
+}
+
+void function_nothrow_new_delete() {
+    myStruct* ms = new(std::nothrow) myStruct;
+    operator delete (ms, std::nothrow);
+}
+```
diff --git a/docs/code-quality/c26436.md b/docs/code-quality/c26436.md
@@ -5,17 +5,46 @@ ms.topic: "conceptual"
 f1_keywords: ["C26436"]
 helpviewer_keywords: ["C26436"]
 ms.assetid: 82d14d5d-5c5d-4e27-bdc8-268f9973a312
+description: CppCoreCheck rule that enforces C++ Core Guidelines C.35
 ---
 # C26436 NEED_VIRTUAL_DTOR
 
 "The type with a virtual function needs either public virtual or protected nonvirtual destructor."
 
-**C++ Core Guidelines**:
-C.35: A base class destructor should be either public and virtual, or protected and nonvirtual
+[**C++ Core Guidelines**: C.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c35-a-base-class-destructor-should-be-either-public-and-virtual-or-protected-and-non-virtual): A base class destructor should be either public and virtual, or protected and nonvirtual
 
 If a class defines a virtual function it becomes polymorphic, which implies that derived classes can change its behavior including resource management and destruction logic. Because client code may call polymorphic types via pointers to base classes, there is no way a client can explicitly choose which behavior is appropriate without downcasting. To make sure that resources are managed consistently and destruction occurs according to the actual type's rules it is recommended to define a public virtual destructor. If the type hierarchy is designed to disallow client code to destroy objects directly, destructors should be defined as protected non-virtual.
 
 ## Remarks
 
 - The warning shows up on the first virtual function definition of a type (it can be a virtual destructor if it is not public), once per type.
   - Since definition can be placed separately from declaration, it may not always have any of the virtual specifiers. But the warning is still valid – it checks the actual 'virtuality' of a function.
+
+## Example
+```cpp
+namespace no_destructor
+{
+    struct base {
+        virtual void foo() {} // C26436, see remarks to understand the placement of the warning.
+    };
+}
+```
+
+The warning does not appear when the base class has either a virtual public destructor or a protected non-virtual destructor.
+```cpp
+namespace virtual_destructor
+{
+    struct base {
+        virtual ~base();
+        virtual void foo() {}
+    };
+}
+namespace protected_destructor
+{
+    struct base {
+        virtual void foo() {}
+    protected:
+        ~base() {}
+    };
+}
+```
diff --git a/docs/code-quality/c26439.md b/docs/code-quality/c26439.md
@@ -5,13 +5,13 @@ ms.topic: "conceptual"
 f1_keywords: ["C26439"]
 helpviewer_keywords: ["C26439"]
 ms.assetid: 9df2a1b0-ea94-4884-9d28-c1522ec33a1b
+description: CppCoreCheck rule that enforces C++ Core Guidelines F.6
 ---
 # C26439 SPECIAL_NOEXCEPT
 
 "This kind of function may not throw. Declare it 'noexcept'."
 
-**C++ Core Guidelines**:
-F.6: If your function may not throw, declare it noexcept
+[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it noexcept
 
 Some kinds of operations should never cause exceptions. Their implementations should be reliable and should handle possible errors conditions gracefully. They should never use exceptions to indicate failure. This rule flags cases where such operations are not explicitly marked as 'noexcept' which means that they may throw exceptions and cannot convey assumptions about their reliability.
 
@@ -25,3 +25,33 @@ Some kinds of operations should never cause exceptions. Their implementations sh
 - Non-standard and outdated specifiers like throw() or declspec(nothrow) are not equivalent to 'noexcept'.
 - Explicit specifiers noexcept(false) and noexcept(true) are respected appropriately.
 - The warning may still appear for operations that are marked as constexpr. This may change in future releases.
+
+## Example
+All functions except the destructor will warn because they are missing noexcept. 
+```cpp
+struct S 
+{
+    S() {} // C26455, Default constructor may not throw. Declare it 'noexcept' 
+    ~S() {}
+    
+    S(S&& s) {/*impl*/} // C26439, This kind of function may not throw. Declare it 'noexcept' (f.6)
+    S& operator=(S&& s) {/*impl*/} // C26439, This kind of function may not throw. Declare it 'noexcept' (f.6)
+
+    S(const S& s) {/*impl*/} // C26440, This function can be declared 'noexcept'
+    S& operator=(const S& s) {/*impl*/} // C26440, This function can be declared 'noexcept'
+};
+```
+With noexcept decorating the same structure, all warnings are removed.
+```cpp
+struct S 
+{
+    S() noexcept {}
+    ~S() {}
+    
+    S(S&& s) noexcept {/*impl*/}
+    S& operator=(S&& s) noexcept {/*impl*/}
+
+    S(const S& s) noexcept {/*impl*/}
+    S& operator=(const S& s) noexcept {/*impl*/}
+};
+```
diff --git a/docs/code-quality/c26440.md b/docs/code-quality/c26440.md
@@ -5,13 +5,13 @@ ms.topic: "conceptual"
 f1_keywords: ["C26440"]
 helpviewer_keywords: ["C26440"]
 ms.assetid: b6d2b188-35cc-4de2-878c-6f97d5a2444a
+description: CppCoreCheck rule that enforces C++ Core Guidelines F.6
 ---
 # C26440 DECLARE_NOEXCEPT
 
 "Function can be declared 'noexcept'."
 
-**C++ Core Guidelines**:
-F.6: If your function may not throw, declare it noexcept
+[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it noexcept
 
 If code is not supposed to cause any exceptions, it should be marked as such by using the 'noexcept' specifier. This would help to simplify error handling on the client code side, as well as enable compiler to do additional optimizations.
 
@@ -25,3 +25,33 @@ If code is not supposed to cause any exceptions, it should be marked as such by
 - Functions marked as constexpr are not supposed to cause exceptions and are not analyzed.
 - The rule also applies to lambda expressions.
 - The logic doesn't consider recursive calls as potentially non-throwing. This may change in the future.
+
+## Example
+All functions except the destructor will warn because they are missing noexcept. 
+```cpp
+struct S 
+{
+    S() {} // C26455, Default constructor may not throw. Declare it 'noexcept' 
+    ~S() {}
+    
+    S(S&& s) {/*impl*/} // C26439, This kind of function may not throw. Declare it 'noexcept' (f.6)
+    S& operator=(S&& s) {/*impl*/} // C26439, This kind of function may not throw. Declare it 'noexcept' (f.6)
+    
+    S(const S& s) {/*impl*/} // C26440, This function can be declared 'noexcept'
+    S& operator=(const S& s) {/*impl*/} // C26440, This function can be declared 'noexcept'
+};
+```
+With noexcept decorating the same structure, all warnings are removed.
+```cpp
+struct S 
+{
+    S() noexcept {}
+    ~S() {}
+    
+    S(S&& s) noexcept {/*impl*/}
+    S& operator=(S&& s) noexcept {/*impl*/}
+    
+    S(const S& s) noexcept {/*impl*/}
+    S& operator=(const S& s) noexcept {/*impl*/}
+};
+```
diff --git a/docs/code-quality/c26482.md b/docs/code-quality/c26482.md
@@ -4,7 +4,21 @@ ms.date: 03/22/2018
 ms.topic: reference
 f1_keywords: ["C26482"]
 helpviewer_keywords: ["C26482"]
+description: CppCoreCheck rule that enforces C++ Core Guidelines Bounds.2
 ---
 # C26482 NO_DYNAMIC_ARRAY_INDEXING
 
-Only index into arrays using constant expressions. See [C++ Core Guidelines Bounds.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds)
+Only index into arrays using constant expressions. 
+## See also
+[C++ Core Guidelines Bounds.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds)
+
+## Example
+
+```cpp
+int getSomeIndex();
+
+void function(int* p, int count)
+{
+    p[getSomeIndex()] = 0; // C26482, Only index into arrays using constant expressions
+}
+```
diff --git a/docs/code-quality/c26490.md b/docs/code-quality/c26490.md
@@ -4,7 +4,18 @@ ms.date: 03/22/2018
 ms.topic: reference
 f1_keywords: ["C26490"]
 helpviewer_keywords: ["C26490"]
+description: CppCoreCheck rule that enforces C++ Core Guidelines Type.1
 ---
 # C26490 NO_REINTERPRET_CAST
 
-Don't use `reinterpret_cast`. See [C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+Don't use `reinterpret_cast`. 
+## See also 
+[C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+
+## Example
+```cpp
+void function(void* ptr)
+{
+    std::size_t val = reinterpret_cast<std::size_t>(ptr); // C26490, Don't use reinterpret_cast
+}
+```
diff --git a/docs/code-quality/c26492.md b/docs/code-quality/c26492.md
@@ -4,7 +4,20 @@ ms.date: 03/22/2018
 ms.topic: reference
 f1_keywords: ["C26492"]
 helpviewer_keywords: ["C26492"]
+description: CppCoreCheck rule that enforces C++ Core Guidelines Type.3
 ---
 # C26492 NO_CONST_CAST
 
-Don't use `const_cast` to cast away `const`. See [C++ Core Guidelines Type.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+Don't use `const_cast` to cast away `const`. 
+
+## See also
+[C++ Core Guidelines Type.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+
+## Example
+
+```cpp
+void function(const int* constIntPtr)
+{
+    int* intPtr = const_cast<int*>(constIntPtr); // C26492, Do not use const_cast to cast away const
+}
+```
diff --git a/docs/code-quality/c26493.md b/docs/code-quality/c26493.md
@@ -4,7 +4,20 @@ ms.date: 03/22/2018
 ms.topic: reference
 f1_keywords: ["C26493"]
 helpviewer_keywords: ["C26493"]
+description: CppCoreCheck rule that enforces C++ Core Guidelines Type.4
 ---
 # C26493 NO_CSTYLE_CAST
 
-Don't use C-style casts. See [C++ Core Guidelines Type.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+Don't use C-style casts. 
+
+## See also
+[C++ Core Guidelines Type.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+
+## Example
+```cpp
+void function(const int* const_i)
+{
+    int* nonconst_i = (int*)const_i; // C26493 Don't use C-style casts
+    int i = (int)*const_i; // C26493 Don't use C-style casts
+}
+```
diff --git a/docs/code-quality/c26494.md b/docs/code-quality/c26494.md
@@ -7,4 +7,16 @@ helpviewer_keywords: ["C26494"]
 ---
 # C26494 VAR_USE_BEFORE_INIT
 
-Variable '%variable%' is uninitialized. Always initialize an object. See [C++ Core Guidelines Type.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+Variable '%variable%' is uninitialized. Always initialize an object. 
+## See also
+[C++ Core Guidelines Type.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type).
+
+## Example
+```cpp
+#include <iostream>
+void function()
+{
+    int myVal; // C26494, Variable is uninitialized
+    std::cout << myVal; // C6001
+}
+```
diff --git a/docs/standard-library/bit-functions.md b/docs/standard-library/bit-functions.md
diff --git a/docs/standard-library/cpp-standard-library-header-files.md b/docs/standard-library/cpp-standard-library-header-files.md
