Merge pull request MicrosoftDocs#5055 from Xazax-hun/doc-updates

 Various documentation updates

Author: denrea

docs/code-quality/c26478.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: Warning C26478: Don't use std::move on constant variables. (es.56)"
 title: Warning C26478
-ms.date: 07/15/2019
+ms.date: 10/12/2023
 f1_keywords: ["C26478", "NO_MOVE_OP_ON_CONST"]
 helpviewer_keywords: ["C26478"]
 ---
@@ -13,11 +13,11 @@ helpviewer_keywords: ["C26478"]
 
 This warning is to indicate that the use of `std::move` not consistent with how `std::move` is intended to be used.
 
-When called on a `const` object, `std::move` returns a copy of the object, which is likely not the developer's intent.
+Because `const` objects can't be moved, calling `std::move` on them has no effect. This pattern can result in unintended copies.
 
 Code analysis name: `NO_MOVE_OP_ON_CONST`
 
-## Example 1
+## Example
 
 ```cpp
 struct node
@@ -33,23 +33,8 @@ void foo(const node& n)
 }
 ```
 
-An assignment operator or using the passed in parameter will prevent this warning from being issued and will adequately serve the developer's use case.
-
-## Example 2
-
-```cpp
-struct s;
-
-template <typename T>
-void bar(T t){};
-
-void foo()
-{
-    const s s1;
-    bar(std::move(s1)); // C26478 reported here
-}
-```
+To fix the issue, remove the redundant `std::move`.
 
 ## See also
 
-[ES.56 - Write std::move() only when you need to explicitly move an object to another scope](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es56-write-stdmove-only-when-you-need-to-explicitly-move-an-object-to-another-scope)
+[ES.56 - Write `std::move()` only when you need to explicitly move an object to another scope](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-move)

docs/code-quality/c26479.md

@@ -0,0 +1,42 @@
+---
+description: "Learn more about: Warning C26479: Don't use std::move to return a local variable. (f.48)"
+title: Warning C26479
+ms.date: 10/12/2023
+f1_keywords: ["C26479", "NO_MOVE_RET_ON_LOCALS"]
+helpviewer_keywords: ["C26479"]
+---
+# Warning C26479
+
+> Don't use std::move to return a local variable. (f.48)
+
+## Remarks
+
+The `return` statement is the last use of a local variable, so the compiler uses move semantics to return it whenever possible.
+Adding a `std::move` is redundant in this scenario. Moreover, redundant `std::move`s can prevent copy elision.
+
+Code analysis name: `NO_MOVE_RET_ON_LOCALS`
+
+## Example 1
+
+```cpp
+S foo()
+{
+    S local1{};
+    return std::move(local1); // Warning: C26479
+}
+```
+
+To fix this issue, remove the redundant `std::move`:
+
+```cpp
+S foo()
+{
+    S local1{};
+    return local1; // No warning
+}
+```
+
+## See also
+
+[F.48 - Don't return `std::move(local)`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-return-move-local)
+[ES.56 - Write `std::move()` only when you need to explicitly move an object to another scope](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-move)

docs/code-quality/c26817.md

@@ -1,15 +1,15 @@
 ---
 title: Warning C26817
 description: "Reference for Microsoft C++ Code Analysis warning C26817 in Visual Studio."
-ms.date: 02/24/2020
+ms.date: 10/12/2023
 f1_keywords: ["C26817"]
 helpviewer_keywords: ["C26817"]
 ---
 # Warning C26817
 
 > Potentially expensive copy of variable *name* in range-for loop. Consider making it a const reference (es.71).
 
-For more information, see [ES.71 notes](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#note-214) in the C++ Core Guidelines.
+For more information, see [ES.71 notes](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-for-range) in the C++ Core Guidelines.
 
 ## Example
 
@@ -25,7 +25,7 @@ class MyComplexType {
 
 void expensive_function(std::vector<MyComplexType>& complex_vector_ref)
 {
-    for (auto item: complex_vector_ref)
+    for (auto item: complex_vector_ref) // Warning: C26817
     {
         // At each iteration, item gets a copy of the next element
         // ...
@@ -38,9 +38,7 @@ void expensive_function(std::vector<MyComplexType>& complex_vector_ref)
 }
 ```
 
-This behavior is fine for scalars (pointers, arithmetic types, and so on), but for larger types, the copying may become expensive.
-
-## Solution
+The warning is ignoring some types that are cheap to copy like for scalars (pointers, arithmetic types, and so on).
 
 To fix this issue, if the loop variable isn't mutated anywhere in the loop, make it a const reference:
 
@@ -67,4 +65,4 @@ void less_expensive_function(std::vector<MyComplexType>& complex_vector_ref)
 }
 ```
 
-The **`const`** keyword makes the loop variable immutable. Use of a non-const reference may cause potentially unwanted side effects in the original container elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable.
+The **`const`** keyword makes the loop variable immutable. Use of a non-const reference makes it possible to inadvertently use the reference to modify the container's elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable.

docs/code-quality/c26820.md

@@ -1,17 +1,17 @@
 ---
 title: Warning C26820
 description: "Reference for Microsoft C++ Code Analysis warning C26820 in Visual Studio."
-ms.date: 04/07/2020
+ms.date: 10/12/2023
 f1_keywords: ["C26820"]
 helpviewer_keywords: ["C26820"]
 ---
 # Warning C26820
 
-> Assigning by value when a const-reference would suffice, use const auto& instead (p.9).
+> This is a potentially expensive copy operation. Consider using a reference unless a copy is required (p.9)
 
-For more information, see [P.9: Don't waste time or space](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#p9-dont-waste-time-or-space) in the C++ Core Guidelines.
+For more information, see [P.9: Don't waste time or space](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rp-waste) in the C++ Core Guidelines.
 
-This check covers non-obvious and easy-to-miss behavior when assigning a reference to a variable marked **`auto`**. The type of the **`auto`** variable is resolved to a value rather than a reference, and an implicit copy is made.
+This check covers nonobvious and easy-to-miss behavior when assigning a reference to a variable marked **`auto`**. The type of the **`auto`** variable is resolved to a value rather than a reference, and an implicit copy is made.
 
 ## Remarks
 

docs/code-quality/c6395.md

@@ -0,0 +1,35 @@
+---
+title: Warning C6395
+description: "Describes the Microsoft C/C++ code analysis warning C6395, its causes, and how to address it."
+ms.date: 10/12/2023
+f1_keywords: ["C6395", "EVAL_ORDER_CHANGE"]
+helpviewer_keywords: ["C6395"]
+---
+# Warning C6395
+
+> %variable% has unsequenced reads and/or writes before C++17; changing the language standard might change the behavior of the code.
+
+## Remarks
+
+C++17 made the evaluation order of certain expressions stricter. MSVC complied, which changed the evaluation order for some expressions. Thus, changing the language version might change the observable behavior of the program. This check diagnoses some of the cases where the meaning of the code changes due to switching language versions.
+
+Code analysis name: `EVAL_ORDER_CHANGE`
+
+## Example
+
+```cpp
+void foo(int* a, int i)
+{
+    a[++i] = i; // Warning: 'i' has unsequenced reads and/or writes before C++17; changing the language standard might change the behavior of the code
+}
+```
+
+To solve this problem, separate the side effects from the rest of the expression to make the evaluation order well defined:
+
+```cpp
+void foo(int* a, int i)
+{
+    ++i;
+    a[i] = i; // No warning.
+}
+```

docs/code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md

@@ -10,7 +10,7 @@ helpviewer_keywords:
 ---
 # How to specify additional code information by using `_Analysis_assume_`
 
-You can provide hints to the code analysis tool for C/C++ code that will help the analysis process and reduce warnings. To provide additional information, use the following function macro:
+You can provide hints to the code analysis tool for C/C++ code that help the analysis process and reduce warnings. To provide additional information, use the following function macro:
 
 `_Analysis_assume_( expr )`
 
@@ -27,25 +27,44 @@ The following code uses `_Analysis_assume_` to correct the code analysis warning
 
 ```cpp
 #include <windows.h>
-#include <codeanalysis\sourceannotations.h>
+#include <sal.h>
 
-using namespace vc_attributes;
+// Requires pc to be null.
+void f(_Pre_null_ char* pc);
 
-//requires pc to be null
-void f([Pre(Null=Yes)] char* pc);
-
-// calls free and sets ch to null
+// Calls free and sets ch to null.
 void FreeAndNull(char** ch);
 
 void test()
 {
-    char pc = (char)malloc(5);
+    char* pc = (char*)malloc(5);
     FreeAndNull(&pc);
     _Analysis_assume_(pc == NULL);
     f(pc);
 }
 ```
 
+`_Analysis_assume_` should be used as a last resort. We should first try to make the contracts of the functions more precise. In this case we could improve the contract of `FreeAndNull` instead of using `_Analysis_assume_`:
+
+```cpp
+#include <windows.h>
+#include <sal.h>
+
+// Requires pc to be null.
+void f(_Pre_null_ char* pc);
+
+// Calls free and sets ch to null.
+_At_(*ch, _Post_null_)
+void FreeAndNull(char** ch);
+
+void test()
+{
+    char* pc = (char*)malloc(5);
+    FreeAndNull(&pc);
+    f(pc);
+}
+```
+
 ## See also
 
 - [__assume](../intrinsics/assume.md)

docs/code-quality/toc.yml

@@ -172,6 +172,8 @@ items:
     href: ../code-quality/c26477.md
   - name: Warning C26478
     href: ../code-quality/c26478.md
+  - name: Warning C26479
+    href: ../code-quality/c26479.md
   - name: Warning C26481
     href: ../code-quality/c26481.md
   - name: Warning C26482
@@ -479,6 +481,8 @@ items:
     href: ../code-quality/c6389.md
   - name: Warning C6390
     href: ../code-quality/c6390.md
+  - name: Warning C6395
+    href: ../code-quality/c6395.md
   - name: Warning C6400
     href: ../code-quality/c6400.md
   - name: Warning C6401