Merge pull request MicrosoftDocs#4505 from MugBergerFries/patch-10

Updated C6383, C28159, C28160, C28213, C33010

Author: colin-home

docs/code-quality/c28159.md

@@ -1,34 +1,36 @@
 ---
 description: "Learn more about: C28159"
 title: C28159
-ms.date: 11/04/2016
+ms.date: 09/08/2022
 ms.topic: reference
-f1_keywords: ["C28159"]
+f1_keywords: ["C28159", "USE_OTHER_FUNCTION", "__WARNING_USE_OTHER_FUNCTION"]
 helpviewer_keywords: ["C28159"]
 ms.assetid: fab6cd58-0985-4ef6-89a2-64ed04297437
 ---
-# C28159
+# Warning C28159
 
-> warning C28159: Consider using another function instead.
+> Consider using `*function_name_1*` instead of `*function_name_2*`. Reason: *reason*
 
-This warning is reported for Drivers is suggesting that you use a preferred function call that is semantically equivalent to the function that the driver is calling. This is a general warning message; the annotation `__drv_preferredFunction` was used (possibly with a conditional a `__drv_when`() annotation) to flag a bad coding practice.
+This warning occurs when you use a function that is semantically equivalent to an alternative, preferred function call. 
+
+## Remarks
+
+C28159 is a general warning message; the annotation `__drv_preferredFunction` was used (possibly with a conditional `__drv_when`() annotation) to flag a bad coding practice.
+
+Code analysis name: USE_OTHER_FUNCTION
 
 ## Example
 
-The following code example generates this warning:
+The following code example generates this warning. This issue is due to the use of `OemToChar`, which doesn't validate the buffer size:
 
 ```cpp
 char buff[MAX_PATH];
-
-// if strlen(input) > MAX_PATH
-// leads to buffer overrun
-OemToChar(buff, input);
+OemToChar(buff, input);  // If strlen(input) > MAX_PATH, this call leads to buffer overrun
 ```
 
-The following code example avoids this warning:
+The following code example avoids this warning by using the recommended alternative `OemToCharBuff`, which takes in the destination buffer size and limits the copy appropriately:
 
 ```cpp
 char buff[MAX_PATH];
-
 OemToCharBuff(buff, input, MAX_PATH);
 ```

docs/code-quality/c28160.md

@@ -1,14 +1,20 @@
 ---
 description: "Learn more about: C28160"
 title: C28160
-ms.date: 11/04/2016
+ms.date: 09/08/2022
 ms.topic: reference
-f1_keywords: ["C28160"]
+f1_keywords: ["C28160", "ERROR", "__WARNING_ERROR"]
 helpviewer_keywords: ["C28160"]
 ms.assetid: cab15f6b-909c-4cc8-81a0-c24ac7c91c7c
 ---
-# C28160
+# Warning C28160
 
-> warning C28160: Error annotation
+> Error annotation: *reason*
 
-This warning is reported when a `__drv_error` annotation has been encountered. This annotation is used to flag coding practices that should be fixed, and can be used with a `__drv_when` annotation to indicate specific combinations of parameters.
+This warning is reported when a `__drv_error` annotation has been encountered.
+
+## Remarks
+
+This annotation is used to flag coding practices that should be fixed, and can be used with a `__drv_when` annotation to indicate specific combinations of parameters.
+
+Code analysis name: ERROR

docs/code-quality/c28213.md

@@ -1,45 +1,56 @@
 ---
 description: "Learn more about: C28213"
 title: C28213
-ms.date: 11/04/2016
+ms.date: 09/08/2022
 ms.topic: reference
-f1_keywords: ["C28213"]
+f1_keywords: ["C28213", "BAD_USEHEADER", "__WARNING_BAD_USEHEADER"]
 helpviewer_keywords: ["C28213"]
 ms.assetid: e141a12a-4c46-47eb-aa9d-a6444472cfaa
 ---
-# C28213
+# Warning C28213
 
-> warning C28213: The `_Use_decl_annotations_` annotation must be used to reference, without modification, a prior declaration.
+> The `_Use_decl_annotations_` annotation must be used to reference, without modification, a prior declaration.
 
-`_Use_decl_annotations_` tells the compiler to use the annotations from an earlier declaration of the function.  If no earlier declaration can be found, or if the current declaration makes changes to the annotations than this warning is emitted.
+## Remarks
+
+`_Use_decl_annotations_` tells the compiler to use the annotations from an earlier declaration of the function. If no earlier declaration can be found, or if the current declaration makes changes to the annotations, then this warning is emitted.
+
+Code analysis name: BAD_USEHEADER
 
 ## Example
 
+The following code generates C28160. The `buffer` parameter annotation doesn't match between the two files.
+
+*From example.h:*
+
 ```cpp
-// from example.h
 void example_func(_Out_writes_(n) char* buffer, int n);
+```
+
+*From example.cpp:*
 
-// from example.cpp
+```cpp
 _Use_decl_annotations_
 void example_func(_Out_writes_z_(n) char* buffer, int n)
 {
-  // ...
-  buffer[n] = '\0';
+    buffer[n] = '\0';
 }
 ```
 
-The `buffer` parameter annotation does not match between the two files.  This can be fixed by either changing the annotation so they match at all locations, or by removing all annotations except `_Use_decl_annotations_` from the function definition.  In this example `_Out_writes_z_` appears to be correct so we will move that to the function declaration in the header file.
+This issue can be fixed by either changing the annotation so they match at all locations, or by removing all annotations except `_Use_decl_annotations_` from the function definition. In this example, `_Out_writes_z_` appears to be correct so we'll move that to the function declaration in the header file. The following code resolves this warning:
 
-```cpp
+*From example.h:*
 
-// from example.h
+```cpp
 void example_func(_Out_writes_z_(n) char* buffer, int n);
+```
 
-// from example.cpp
+*From example.cpp:*
+
+```cpp
 _Use_decl_annotations_
-void example_func(char* buffer, int n)
+void example_func(_Out_writes_z_(n) char* buffer, int n)
 {
-  // ...
-  buffer[n] = '\0';
+    buffer[n] = '\0';
 }
 ```

docs/code-quality/c33010.md

@@ -4,25 +4,27 @@ description: C33010 warning for enums
 keywords: c33010
 author: hwisungi
 ms.author: hwisungi
-ms.date: 06/20/2020
+ms.date: 09/08/2022
 ms.topic: reference
-f1_keywords: ["C33010"]
+f1_keywords: ["C33010", "UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX", "__WARNING_UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX"]
 helpviewer_keywords: ["C33010"]
 dev_langs: ["C++"]
 ---
-# C33010
+# Warning C33010
 
-> Warning C33010: Unchecked lower bound for enum 'enum' used as index.
+> Unchecked lower bound for enum *enum_name* used as index.
 
-This warning is triggered for an enum that is used as an index into an array,
-if the upper bound is checked for its value, but not the lower bound.
+This warning is triggered if an enum is both used as an index into an array and isn't checked on the lower bound.
+
+## Remarks
+
+Code using enumerated types as indexes for arrays will often check for the upper bound in order to ensure the index isn't out of range. Because an enum variable is signed by default, it can have a negative value. A negative array index can allow arbitrary memory to be read, used, or even executed.
+
+Code analysis name: UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX
 
 ## Example
 
-Code using enumerated types as indexes for arrays will often check for the upper bound
-in order to ensure the index is not out of range. Because an enum variable is signed by default,
-it can have a negative value. If it is used as an index into an array of values or an array of function pointers,
-a negative value can allow arbitrary memory to be read, used, or even executed.
+The following code generates this warning. `idx` is used as an index to access `functions`, but the lower bound is never checked.
 
 ```cpp
 typedef void (*PFN)();
@@ -41,14 +43,13 @@ void foo(Index idx, PFN(&functions)[5])
     if (idx > Index::Max)
         return;
 
-    auto pfn = functions[static_cast<int>(idx)];    // C33010
+    auto pfn = functions[static_cast<int>(idx)];
     if (pfn != nullptr)
         (*pfn)();
-    // ......
 }
 ```
 
-These warnings are corrected by checking the index value for lower bound as well:
+The following code remediates this warning by checking the lower bound as well to ensure `idx` isn't negative:
 
 ```cpp
 typedef void (*PFN)();
@@ -67,10 +68,9 @@ void foo(Index idx, PFN(&functions)[5])
     if (idx < Index::Zero || idx > Index::Max)
         return;
 
-    auto pfn = functions[static_cast<int>(idx)];    // OK
+    auto pfn = functions[static_cast<int>(idx)];
     if (pfn != nullptr)
         (*pfn)();
-    // ......
 }
 ```
 

docs/code-quality/c6383.md

@@ -1,52 +1,41 @@
 ---
 description: "Learn more about: C6383"
 title: C6383
-ms.date: 11/04/2016
+ms.date: 09/07/2022
 ms.topic: reference
-f1_keywords: ["C6383"]
+f1_keywords: ["C6383", "ELEMENTS_TO_BYTES", "__WARNING_ELEMENTS_TO_BYTES"]
 helpviewer_keywords: ["C6383"]
 ms.assetid: f5ff7938-0fbe-4b71-b98f-098fe887799d
 ---
-# C6383
+# Warning C6383
 
-> warning C6383: buffer overrun due to conversion of an element count into a byte count: an element count is expected for parameter \<number> in call to \<function>
+> Buffer overrun due to conversion of an element count into a byte count: an element count is expected for parameter `*parameter_name*` in call to `*function_name*`
 
-This warning indicates that a non-constant byte count is being passed when an element count is required. Typically, this occurs when a variable is multiplied by the **`sizeof`** a type, but code analysis suggests that an element count is required.
+This warning indicates that a non-constant byte count is being passed when an element count is instead required.
 
-## Example
+## Remarks
 
-The following code generates this warning:
+Typically, this warning occurs when a variable is multiplied by the `sizeof` a type. This issue will likely result in more bytes being copied to the buffer than it can hold.
 
-```cpp
-#include <string.h>
+Code analysis name: ELEMENTS_TO_BYTES
 
-void f( wchar_t* t, wchar_t* s, int n )
-{
-  // code ...
-  wcsncpy (t, s, n*sizeof(wchar_t)); // warning C6383
-  // code ...
-}
-```
+## Example
 
-To correct this warning, do not multiply the variable with the **`sizeof`** a type as shown in the following code:
+The following code generates this warning. `wcsncpy` will allow n \* sizeof(wchar_t) characters to be copied, but the buffer can only hold n characters. It should be noted that `wcsncpy` is an unsafe function, and shouldn't be used per [C28719](/windows-hardware/drivers/devtest/28719-banned-api-usage-use-updated-function-replacement). The unsafe variant is used here only for the purposes of demonstrating this warning:
 
 ```cpp
-void f( wchar_t* t, wchar_t* s, int n )
+void f(wchar_t* t, wchar_t* s, int n)
 {
-  // code ...
-  wcsncpy (t, s, n);
-  // code ...
+    wcsncpy (t, s, n*sizeof(wchar_t));
 }
 ```
 
-The following code corrects this warning by using the safe string manipulation function:
+The following code corrects this warning by sending element count instead of the byte count:
 
 ```cpp
-void f(wchar_t* t, wchar_t* s, size_t n)
+void f( wchar_t* t, wchar_t* s, int n )
 {
-  // code ...
-  wcsncpy_s( t, sizeof(s), s, n );
-  // code ...
+    wcsncpy (t, s, n);
 }
 ```