Merge pull request #3060 from MicrosoftDocs/FromPublicMasterBranch

Colin Robertson · web-flow · commit eea02f792290 · 2020-08-20T23:53:05.000-07:00
Confirm merge from FromPublicMasterBranch to master to sync with https://github.com/MicrosoftDocs/cpp-docs (branch master)
diff --git a/docs/code-quality/c26402.md b/docs/code-quality/c26402.md
@@ -1,11 +1,44 @@
 ---
 title: C26402
-ms.date: 09/04/2019
+ms.date: 08/20/2020
 ms.topic: "conceptual"
 f1_keywords: ["C26402"]
 helpviewer_keywords: ["C26402"]
 ms.assetid: b9d3d398-697a-4a5d-8bfe-9c667dffb90b
 ---
 # C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT
 
-To avoid confusion about whether a pointer owns an object, a function that returns a movable object should allocate it on the stack and return it by value instead of returning a heap-allocated object. If pointer semantics are required, then return a smart pointer instead of a raw pointer. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr): *Warn if a function returns an object that was allocated within the function but has a move constructor. Suggest considering returning it by value instead.*
+> `Return a scoped object instead of a heap-allocated if it has a move constructor (r.3).`
+
+## Remarks
+
+To avoid confusion about whether a pointer owns an object, a function that returns a movable object should allocate it on the stack. It should then return the object by value instead of returning a heap-allocated object. If pointer semantics are required, return a smart pointer instead of a raw pointer. For more information, see [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr): *Warn if a function returns an object that was allocated within the function but has a move constructor. Suggest considering returning it by value instead.*
+
+## Example
+
+This example shows a function, `bad_example`, that raises warning C26409. It also shows how function `good_example` doesn't cause this issue.
+
+```cpp
+// C26402.cpp
+
+struct S
+{
+    S() = default;
+    S(S&& s) = default;
+};
+
+S* bad_example()
+{
+    S* s = new S(); // C26409, avoid explicitly calling new.
+    // ... 
+    return s; // C26402
+}
+
+// Prefer returning objects with move contructors by value instead of unnecessarily heap-allocating the object.
+S good_example() noexcept
+{
+    S s;
+    // ...
+    return s;
+}
+```
diff --git a/docs/code-quality/c26409.md b/docs/code-quality/c26409.md
@@ -1,20 +1,36 @@
 ---
 title: C26409
-ms.date: 07/21/2017
+ms.date: 08/20/2020
 ms.topic: "conceptual"
 f1_keywords: ["C26409"]
 helpviewer_keywords: ["C26409"]
 ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37
 ---
 # C26409 NO_NEW_DELETE
 
-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/cpp/new-and-delete-operators).
+> `Avoid calling new and delete explicitly, use std::make_unique<T> instead (r.11).`
 
-  **C++ Core Guidelines**:
+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/cpp/new-and-delete-operators).
+
+**C++ Core Guidelines**:\
 [R.11: Avoid calling new and delete explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r11-avoid-calling-new-and-delete-explicitly)
 
-The ultimate fix is to start using smart pointers with appropriate factory functions, such as [std::make_unique](/cpp/standard-library/memory-functions#make_unique).
+The ultimate fix is to use smart pointers and appropriate factory functions, such as [`std::make_unique`](/cpp/standard-library/memory-functions#make_unique).
 
 ## Remarks
 
-- The checker warns on calls to any kind of operator **`new`** or **`delete`**: scalar, vector, overloaded versions (global and class-specific), as well as on placement versions. The latter case may require some clarifications on the Core Guidelines in terms of suggested fixes and may be omitted in the future.
+- 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
+
+This example shows C26409 is raised for explicit **`new`** and **`delete`**. Consider using smart pointer factory functions such as `std::make_unique` instead.
+
+```cpp
+void f(int i)
+{
+    int* arr = new int[i]{}; // C26409, warning is issued for all new calls
+    delete[] arr;            // C26409, warning is issued for all delete calls
+
+    auto unique = std::make_unique<int[]>(i); // prefer using smart pointers over new and delete
+} 
+```
diff --git a/docs/code-quality/c26410.md b/docs/code-quality/c26410.md
@@ -8,11 +8,11 @@ ms.assetid: d1547faf-96c6-48da-90f5-841154d0e878
 ---
 # C26410  NO_REF_TO_CONST_UNIQUE_PTR
 
-Generally, references to const unique pointer are meaningless. They can safely be replaced by a raw reference or a pointer.
+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
 
-- Unique pointer checks have rather broad criteria to identify smart pointers. The rule R.31: *If you have non-std smart pointers, follow the basic pattern from std describes the unique pointer and shared pointer concepts*. The heuristic is simple, but may lead to surprises: a smart pointer type is any type which defines either operator-> or operator\*; a copy-able type (shared pointer) must have either public copy constructor or overloaded assignment operator which deals with a non-R-value reference parameter.
+- Unique pointer checks have rather broad criteria to identify smart pointers. The [C++ Core Guidelines rule R.31](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r31-if-you-have-non-std-smart-pointers-follow-the-basic-pattern-from-std): *If you have non-std smart pointers, follow the basic pattern from std describes the unique pointer and shared pointer concepts*. The heuristic is simple, but may lead to surprises: a smart pointer type is any type which defines either operator-> or operator\*; a copy-able type (shared pointer) must have either public copy constructor or overloaded assignment operator which deals with a non-R-value reference parameter.
 
 - Template code may produce a lot of noise. 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.
 
diff --git a/docs/code-quality/c26411.md b/docs/code-quality/c26411.md
@@ -1,24 +1,24 @@
 ---
 title: C26411
-ms.date: 11/15/2017
+ms.date: 08/19/2020
 ms.topic: "conceptual"
 f1_keywords: ["C26411"]
 helpviewer_keywords: ["C26411"]
 ms.assetid: 5134e51e-8b92-4ee7-94c3-022e318a0e24
 ---
 # C26411  NO_REF_TO_UNIQUE_PTR
 
-Passing a unique pointer by reference assumes that its resource may be released or transferred inside of a target function. If function uses its parameter only to access the resource, it is safe to pass a raw pointer or a reference.
+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 additional 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
 
-- The limitations from the warning [C26410](C26410.md) are applicable here as well.
+- The limitations from the warning [C26410](C26410.md) are also applicable here.
 
-- The heuristic to detect "release" or "reset" access to the unique pointer is rather naive: we only detect calls to assignment operators and functions named "reset" (case-insensitive). Obviously, this detection doesn’t cover all possible cases of smart pointer modifications (for example, std::swap, or any special non-const function in a custom smart pointer). It is expected that this warning will produce many false positives on custom types, as well as in some scenarios dealing with standard unique pointers. The heuristic will be improved as we implement more checks focused on smart pointers.
+- The heuristic to detect `release` or `reset` access to the unique pointer is naive. We only detect calls to assignment operators and to functions named `reset` (case-insensitive). Obviously, this detection doesn't cover all possible cases of smart pointer modifications. (For example, it doesn't detect `std::swap`, or any special non-**`const`** function in a custom smart pointer). We expect this warning may produce many false positives on custom types, and in some scenarios dealing with standard unique pointers. We expect to improve the heuristic as we implement more checks focused on smart pointers.
 
-- The fact that smart pointers are often templates brings an interesting limitation related to the fact that the compiler is not required to process template code in templates if it's not used. In some minimal code bases that have limited use of smart pointer interfaces, the checker may produce unexpected results due to its inability to properly identify semantics of the template type (because some important functions may never be used). For the standard `unique_pointer`, this limitation is mitigated by recognizing the type’s name. This may be extended in future to cover more well-known smart pointers.
+- The fact that smart pointers are often templates brings an interesting limitation. The compiler isn't required to process template code in templates if it's not used. In code that makes limited use of smart pointer interfaces, the checker may produce unexpected results. The checker can't properly identify semantics of the template type, because some functions may never get used. For the standard `std::unique_ptr`, this limitation is mitigated by recognizing the type's name. This may be extended in future to cover more well-known smart pointers.
 
-- Lambda expressions with 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 are reset or not. The heuristic here will be extended to correlate lambda fields with lambda parameters in a future release.
+- 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.
 
 ## Example: Unnecessary reference
 
