Merge pull request #3336 from MicrosoftDocs/FromPublicMasterBranch

Colin Robertson · web-flow · commit f68fd5e1320a · 2020-12-16T20:01:07.000-08:00
Confirm merge from FromPublicMasterBranch to master to sync with https://github.com/MicrosoftDocs/cpp-docs (branch master)
diff --git a/docs/code-quality/c26401.md b/docs/code-quality/c26401.md
@@ -1,23 +1,23 @@
 ---
 title: C26401
-ms.date: 07/21/2017
+ms.date: 12/14/2020
 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
+description: CppCoreCheck rule C26401 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.
+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 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 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.
+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.
 
 ## 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
+## Examples
 
 ```cpp
 struct myStruct {};
@@ -45,3 +45,25 @@ void function()
     delete pMyStruct; // no warning.
 }
 ```
+
+There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example:
+
+```cpp
+class MyReferenceCountingObject final
+{
+public:
+    void AddRef();
+    void Release() noexcept
+    {
+        ref_count_--;
+        if (ref_count_ == 0)
+        {
+            [[gsl::suppress(i.11)]]
+            delete this; 
+        }
+    }
+private:
+    unsigned int ref_count_{1};
+};
+```
+
diff --git a/docs/code-quality/c26409.md b/docs/code-quality/c26409.md
@@ -1,7 +1,7 @@
 ---
-description: "Learn more about: C26409 NO_NEW_DELETE"
+description: "Learn more about CppCoreCheck rule C26409: avoid explicit new and delete."
 title: C26409
-ms.date: 08/20/2020
+ms.date: 12/14/2020
 ms.topic: "conceptual"
 f1_keywords: ["C26409"]
 helpviewer_keywords: ["C26409"]
@@ -11,7 +11,7 @@ ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37
 
 > `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).
+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).
 
 **C++ Core Guidelines**:\
 [R.11: Avoid calling new and delete explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r11-avoid-calling-new-and-delete-explicitly)
@@ -22,7 +22,7 @@ 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.
 
-## Example
+## Examples
 
 This example shows C26409 is raised for explicit **`new`** and **`delete`**. Consider using smart pointer factory functions such as `std::make_unique` instead.
 
@@ -35,3 +35,24 @@ void f(int i)
     auto unique = std::make_unique<int[]>(i); // prefer using smart pointers over new and delete
 }
 ```
+
+There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example:
+
+```cpp
+class MyReferenceCountingObject final
+{
+public:
+    void AddRef();
+    void Release() noexcept
+    {
+        ref_count_--;
+        if (ref_count_ == 0)
+        {
+            [[gsl::suppress(i.11)]]
+            delete this; 
+        }
+    }
+private:
+    unsigned int ref_count_{1};
+};
+```
diff --git a/docs/mfc/reference/clistctrl-class.md b/docs/mfc/reference/clistctrl-class.md
@@ -267,7 +267,7 @@ CSize ApproximateViewRect(
 The proposed dimensions of the control, in pixels. If dimensions are not specified, the framework uses the current width or height values of the control.
 
 *iCount*<br/>
-Number of items to be displayed in the control. If this parameter is -1, the framework uses the total number of items currently in the control.
+Number of items to be displayed in the control. Pass -1 to use the total number of items currently in the control.
 
 ### Return Value
 
@@ -3650,7 +3650,7 @@ BOOL SetItemState(
 ### Parameters
 
 *nItem*<br/>
-Index of the item whose state is to be set.
+Index of the item whose state is to be set. Pass -1 to apply the state change to all items.
 
 *pItem*<br/>
 Address of an [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure, as described in the Windows SDK. The structure's `stateMask` member specifies which state bits to change, and the structure's `state` member contains the new values for those bits. The other members are ignored.
