Add missing code analysis warning text (#4566)

Author: colin-home

docs/code-quality/c26400.md

@@ -7,16 +7,20 @@ helpviewer_keywords: ["C26400"]
 ---
 # Warning C26400
 
-This check helps to enforce the *rule I.11: Never transfer ownership by a raw pointer (T\*)*, which is a subset of the rule *R.3: A raw pointer (a T\*) is non-owning*. Specifically, it warns on any call to `operator new`, which saves its result in a variable of raw pointer type. It also warns on calls to functions that return `gsl::owner<T>` if their results are assigned to raw pointers. The idea is that you should clearly state ownership of memory resources. For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management).
+> Do not assign the result of an allocation or a function call with an `owner<T>` return value to a raw pointer, use `owner<T>` instead (i.11)
+
+## Remarks
+
+This check helps to enforce the *rule I.11: Never transfer ownership by a raw pointer (T\*), which is a subset of the rule *R.3: A raw pointer (a T\*) is non-owning*. Specifically, it warns on any call to `operator new`, which saves its result in a variable of raw pointer type. It also warns on calls to functions that return `gsl::owner<T>` if their results are assigned to raw pointers. The idea is that you should clearly state ownership of memory resources. For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management).
 
 The easiest way to fix this warning is to use **`auto`** declaration if the resource is assigned immediately at the variable declaration. If this fix isn't possible, then we suggest that you use the type `gsl::owner<T>`. The **`auto`** declarations initialized with operator **`new`** are "owners" because we assume that the result of any allocation is implicitly an owner pointer. We transfer this assumption to the **`auto`** variable and treat it as `owner<T>`.
 
 If this check flags a call to a function that returns `owner<T>`, it may be an indication of a legitimate bug in the code. Basically, it points to a place where the code leaks an explicit notion of ownership (and maybe the resource itself).
 
-## Remarks
-
 This rule currently checks only local variables. If you assign an allocation to a formal parameter, global variable, class member, and so on, it's not flagged. Appropriate coverage of such scenarios is planned for future work.
 
+Code analysis name: `NO_RAW_POINTER_ASSIGNMENT`
+
 ## Example 1: Simple allocation
 
 ```cpp

docs/code-quality/c26401.md

@@ -8,10 +8,16 @@ description: CppCoreCheck rule C26401 enforces C++ Core Guidelines I.11
 ---
 # Warning C26401
 
+> Do not delete a raw pointer that is not an `owner<T>` (i.11)
+
+## Remarks
+
 This check detects code 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 isn't an `owner<T>` or an implicitly assumed owner. For more information about **`auto`** declarations, see [C26400](c26400.md). This check includes expressions that refer to global variables, formal parameters, and so on.
 
 Warnings C26400 and C26401 always occur with [C26409](c26409.md), but they're more appropriate for scenarios where immediate migration to smart pointers isn't feasible. In such cases, the `owner<T>` concept can be adopted first, and C26409 may be temporarily suppressed.
 
+Code analysis name: `DONT_DELETE_NON_OWNER`
+
 ## 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)

docs/code-quality/c26403.md

@@ -8,6 +8,8 @@ ms.assetid: 7e14868d-df86-4df3-98d3-71b1e80ba14e
 ---
 # Warning C26403
 
+> Reset or explicitly delete an `owner<T>` pointer '*variable*' (r.3)
+
 Owner pointers are like unique pointers: they own a resource exclusively, and manage release of the resource, or its transfers to other owners. This check validates that a local owner pointer properly maintains its resource through all execution paths in a function. If the resource wasn't transferred to another owner, or wasn't explicitly release, the checker warns, and points to the declaration of the pointer variable.
 
 For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management).
@@ -20,7 +22,11 @@ For more information, see the [C++ Core Guidelines](https://github.com/isocpp/Cp
 
 - The warning may fire on clearly false positive cases where memory is deleted only after the null check of a pointer. These false positives are the result of a current limitation of the tool's API, but it may be improved in future.
 
-## Example 1: Missing cleanup during error handling
+Code analysis name: `RESET_OR_DELETE_OWNER`
+
+## Example
+
+Missing cleanup during error handling:
 
 ```cpp
 gsl::owner<int*> sequence = GetRandomSequence(); // C26403

docs/code-quality/c26404.md

@@ -8,10 +8,17 @@ ms.assetid: 94afb700-3f3b-40db-8afc-2481935360c2
 ---
 # Warning C26404
 
-Once owner pointer releases or transfers its resource, it gets into an "invalid" state.
-Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer.
+> Do not delete an `owner<T>` which may be in invalid state (r.3)
 
-## Example 1: Deleting an owner after transferring its value
+## Remarks
+
+Once an owner pointer releases or transfers its resource, it gets into an "invalid" state. Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer.
+
+Code analysis name: `DONT_DELETE_INVALID`
+
+## Example 1
+
+Deleting an owner after transferring its value:
 
 ```cpp
 gsl::owner<State*> validState = nullptr;
@@ -21,7 +28,9 @@ if (!IsValid(state))
     delete state;   // C26404
 ```
 
-## Example 2: Deleting an uninitialized owner
+## Example 2
+
+Deleting an uninitialized owner:
 
 ```cpp
 gsl::owner<Message*> message;

docs/code-quality/c26405.md

@@ -8,9 +8,17 @@ ms.assetid: 2034d961-3ec5-4184-bbef-aa792e4c03c0
 ---
 # Warning C26405
 
+> Do not assign to an `owner<T>` which may be in valid state (r.3)
+
+## Remarks
+
 If an owner pointer already points to a valid memory buffer, it must not be assigned to another value without releasing its current resource first. Such assignment may lead to a resource leak even if the resource address is copied into some raw pointer (because raw pointers shouldn't release resources). For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning).
 
-## Example 1: Overwriting an owner in a loop
+Code analysis name: `DONT_ASSIGN_TO_VALID`
+
+## Example 1
+
+Overwriting an owner in a loop:
 
 ```cpp
 gsl::owner<Shape*> shape = nullptr;

docs/code-quality/c26406.md

@@ -8,13 +8,19 @@ ms.assetid: 02fb8e23-1989-4e24-a5a5-e30f71d00325
 ---
 # Warning C26406
 
+> Do not assign a raw pointer to an `owner<T>` (r.3)
+
 This warning enforces R.3 from the C++ Core Guidelines. For more information, see [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning).
 
 ## Remarks
 
 Owners are initialized from allocations or from other owners. This warning occurs when you assign a value from a raw pointer to an owner pointer. Raw pointers don't guarantee ownership transfer; the original owner may still hold the resource and attempt to release it. It's okay to assign a value from an owner to a raw pointer. Raw pointers are valid clients to access resources, but not to manage them.
 
-## Example 1:  Using address of object
+Code analysis name: `DONT_ASSIGN_RAW_TO_OWNER`
+
+## Example
+
+Using address of object:
 
 This sample attempts to assign ownership of the address of `defaultSocket` to owner pointer `socket`:
 

docs/code-quality/c26407.md

@@ -8,6 +8,8 @@ ms.assetid: 5539907a-bfa0-40db-82a6-b860c97209e1
 ---
 # Warning C26407
 
+> Prefer scoped objects, don't heap-allocate unnecessarily (r.5)
+
 To avoid unnecessary use of pointers, we try to detect common patterns of local allocations. For example, we detect when the result of a call to operator **`new`** is stored in a local variable and later explicitly deleted. This check supports the [C++ Core Guidelines rule R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r5-prefer-scoped-objects-dont-heap-allocate-unnecessarily): *Prefer scoped objects, don't heap-allocate unnecessarily*. To fix the issue, use an RAII type instead of a raw pointer, and allow it to deal with resources. Obviously, it isn't necessary to create a wrapper type to allocate a single object. Instead, a local variable of the object's type would work better.
 
 ## Remarks
@@ -20,6 +22,8 @@ To avoid unnecessary use of pointers, we try to detect common patterns of local
 
 - The pattern is detected only for local variables. We don't warn in cases where an allocation is assigned to, say, a global variable and then deleted in the same function.
 
+Code analysis name: `DONT_HEAP_ALLOCATE_UNNECESSARILY`
+
 ## Example 1: Unnecessary object allocation on heap
 
 ```cpp

docs/code-quality/c26408.md

@@ -8,6 +8,8 @@ description: CppCoreCheck rule that enforces C++ Core Guidelines R.10
 ---
 # Warning C26408
 
+> Avoid `malloc()` and `free()`, prefer the `nothrow` version of `new` with `delete` (r.10)
+
 This warning flags places where `malloc` or `free` is invoked explicitly in accordance to R.10: Avoid `malloc` and `free`. One potential fix for such warnings would be to use [std::make_unique](../standard-library/memory-functions.md#make_unique) to avoid explicit creation and destruction of objects. If such a fix isn't acceptable, operator [new and delete](../cpp/new-and-delete-operators.md) should be preferred. In some cases, if exceptions aren't welcome, `malloc` and `free` can be replaced with the nothrow version of operators `new` and `delete`.
 
 ## Remarks
@@ -16,6 +18,8 @@ This warning flags places where `malloc` or `free` is invoked explicitly in acco
 
 - To detect `free()`, we check global functions named `free` or `std::free` that return no result and accept one parameter, which is a pointer to **`void`**.
 
+Code analysis name: `NO_MALLOC_FREE`
+
 ## See also
 
 [C++ Core Guidelines R.10](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r10-avoid-malloc-and-free)

docs/code-quality/c26409.md

@@ -8,7 +8,7 @@ ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37
 ---
 # Warning C26409
 
-> `Avoid calling new and delete explicitly, use std::make_unique<T> instead (r.11).`
+> Avoid calling `new` and `delete` explicitly, use `std::make_unique<T>` instead (r.11).
 
 Even if code is clean of calls to `malloc` and `free`, we still suggest that you consider better options than explicit use of operators [`new` and `delete`](../cpp/new-and-delete-operators.md).
 
@@ -21,6 +21,8 @@ The ultimate fix is to use smart pointers and appropriate factory functions, suc
 
 - The checker warns on calls to any kind of operator **`new`** or **`delete`**: scalar, vector, overloaded versions (global and class-specific), and placement versions. The placement **`new`** case may require some clarifications in the Core Guidelines for suggested fixes, and may be omitted in the future.
 
+Code analysis name: `NO_NEW_DELETE`
+
 ## Examples
 
 This example shows C26409 is raised for explicit **`new`** and **`delete`**. Consider using smart pointer factory functions such as `std::make_unique` instead.

docs/code-quality/c26410.md

@@ -8,6 +8,8 @@ ms.assetid: d1547faf-96c6-48da-90f5-841154d0e878
 ---
 # Warning C26410
 
+> The parameter '*parameter*' is a reference to const unique pointer, use `const T*` or `const T&` instead (r.32)
+
 Generally, references to const unique pointer are meaningless. They can safely be replaced by a raw reference or a pointer. This warning enforces [C++ Core Guidelines rule R.32](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r32-take-a-unique_ptrwidget-parameter-to-express-that-a-function-assumes-ownership-of-a-widget).
 
 ## Remarks
@@ -16,7 +18,11 @@ Generally, references to const unique pointer are meaningless. They can safely b
 
 - Template code may produce noisy warnings. Keep in mind that templates can be instantiated with various type parameters with different levels of indirection, including references. Some warnings may not be obvious and fixes may require some rework of templates (for example, explicit removal of reference indirection). If template code is intentionally generic, the warning can be suppressed.
 
-## Example 1: Unnecessary reference
+Code analysis name: `NO_REF_TO_CONST_UNIQUE_PTR`
+
+## Example
+
+Unnecessary reference:
 
 ```cpp
 std::vector<std::unique_ptr<Tree>> roots = GetRoots();

docs/code-quality/c26411.md

@@ -8,6 +8,8 @@ ms.assetid: 5134e51e-8b92-4ee7-94c3-022e318a0e24
 ---
 # Warning C26411
 
+> The parameter '*parameter*' is a reference to unique pointer and it is never reassigned or reset, use `T*` or `T&` instead (r.33)
+
 When you pass a unique pointer to a function by reference, it implies that its resource may be released or transferred inside the function. If the function uses its parameter only to access the resource, it's safe to pass a raw pointer or a reference. For more information, see [C++ Core Guidelines rule R.33](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r33-take-a-unique_ptrwidget-parameter-to-express-that-a-function-reseats-thewidget): *Take a unique_ptr\<widget\>& parameter to express that a function reseats the widget*.
 
 ## Remarks
@@ -20,6 +22,8 @@ When you pass a unique pointer to a function by reference, it implies that its r
 
 - Lambda expressions that do implicit capture-by-reference may lead to surprising warnings about references to unique pointers. Currently, all captured reference parameters in lambdas are reported, regardless of whether they're reset or not. A future release may extend the heuristic to correlate lambda fields and lambda parameters.
 
+Code analysis name: `NO_REF_TO_UNIQUE_PTR`
+
 ## Example: Unnecessary reference
 
 ```cpp

docs/code-quality/c26414.md

@@ -27,9 +27,11 @@ The type `Microsoft::WRL::ComPtr` behaves as a shared pointer, but it's often us
 
 This check looks for explicit local allocations assigned to smart pointers, to identify if scoped variables could work as an alternative. Both direct calls to operator `new`, and special functions like `std::make_unique` and `std::make_shared`, are interpreted as direct allocations.
 
+Code analysis name: `RESET_LOCAL_SMART_PTR`
+
 ## Example
 
-Dynamic buffer
+Dynamic buffer:
 
 ```cpp
 void unpack_and_send(const frame &f)
@@ -40,7 +42,7 @@ void unpack_and_send(const frame &f)
 }
 ```
 
-Dynamic buffer – replaced by container
+Dynamic buffer replaced by container:
 
 ```cpp
 void unpack_and_send(const frame &f)

docs/code-quality/c26426.md

@@ -8,9 +8,10 @@ ms.assetid: 6fb5f6d2-b097-47f8-8b49-f2fd4e9bef0e
 ---
 # Warning C26426
 
-"Global initializer calls a non-constexpr function."
+> Global initializer calls a non-constexpr function '*symbol*' (i.22)
+
+## C++ Core Guidelines
 
-**C++ Core Guidelines**:
 [I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects): Avoid complex initialization of global objects
 
 The order of execution of initializers for global objects may be inconsistent or undefined, which can lead to issues that are hard to reproduce and investigate. To avoid such problems, global initializers shouldn't depend on external code that's executed at run time, and that may depend on data that's not yet initialized. This rule flags cases where global objects call functions to obtain their initial values.
@@ -25,9 +26,11 @@ The order of execution of initializers for global objects may be inconsistent or
 
 - Static class members are considered global, so their initializers are also checked.
 
+Code analysis name: `NO_GLOBAL_INIT_CALLS`
+
 ## Examples
 
-external version check
+External version check:
 
 ```cpp
 // api.cpp
@@ -41,7 +44,7 @@ int get_api_version() noexcept;
 bool is_legacy_mode = get_api_version() <= API_LEGACY_VERSION; // C26426, also stale value
 ```
 
-external version check – made more reliable
+External version check made more reliable:
 
 ```cpp
 // api.cpp

docs/code-quality/c26427.md

@@ -8,7 +8,7 @@ ms.assetid: 8fb95a44-8704-45b1-bc55-eccd59b1db2f
 ---
 # Warning C26427
 
-"Global initializer accesses extern object."
+> Global initializer accesses extern object '*symbol*' (i.22)
 
 **C++ Core Guidelines**:
 [I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects): Avoid complex initialization of global objects
@@ -24,9 +24,11 @@ An object is deemed **`extern`** if it conforms to the following rules:
 - it's not marked as **`const`**;
 - Static class members are considered global, so their initializers are also checked.
 
+Code analysis name: `NO_GLOBAL_INIT_EXTERNS`
+
 ## Example
 
-external version check
+External version check:
 
 ```cpp
 // api.cpp
@@ -37,7 +39,7 @@ extern int api_version;
 bool is_legacy_mode = api_version <= API_LEGACY_VERSION; // C26427, also stale value
 ```
 
-external version check – made more reliable
+External version check made more reliable:
 
 ```cpp
 // api.cpp

docs/code-quality/c26429.md

@@ -29,9 +29,11 @@ A variable is marked as checked for null when it's used in the following context
 
 The rule doesn't have full dataflow tracking. It can produce incorrect results in cases where indirect checks are used (such as when an intermediate variable holds a null value and is later used in a comparison).
 
+Code analysis name: `USE_NOTNULL`
+
 ## Example
 
-hidden expectation
+Hidden expectation:
 
 ```cpp
 using client_collection = gsl::span<client*>;
@@ -48,7 +50,7 @@ void keep_alive(const connection *connection)   // C26429
 }
 ```
 
-hidden expectation – clarified by gsl::not_null
+Hidden expectation clarified by `gsl::not_null`:
 
 ```cpp
 using client_collection = gsl::span<gsl::not_null<client*>>;

docs/code-quality/c26431.md

@@ -8,7 +8,7 @@ ms.assetid: 40be6032-c8de-49ab-8e43-e8eedc0ca0ba
 ---
 # Warning C26431
 
-"The type of expression is already gsl::not_null. Do not test it for nullness."
+> The type of expression '*expr*' is already `gsl::not_null`. Do not test it for nullness (f.23)
 
 **C++ Core Guidelines**:
 [F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\<T> to indicate that "null" isn't a valid value
@@ -25,6 +25,8 @@ The current heuristic for null checks detects the following contexts:
 - non-bitwise logical operations;
 - comparison operations where one operand is a constant expression that evaluates to zero.
 
+Code analysis name: `DONT_TEST_NOTNULL`
+
 ## Example
 
 Unnecessary null checks reveal questionable logic:
@@ -58,7 +60,7 @@ public:
 };
 ```
 
-Unnecessary null checks reveal questionable logic - reworked:
+Unnecessary null checks reveal questionable logic, reworked:
 
 ```cpp
     //...

docs/code-quality/c26435.md

@@ -7,7 +7,7 @@ helpviewer_keywords: ["C26435"]
 ---
 # Warning C26435
 
-"Function should specify exactly one of 'virtual', 'override', or 'final'."
+> Function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final' (c.128)
 
 ## C++ Core Guidelines