Merge pull request #4559 from MicrosoftDocs/main

10/4 AM Publishing

Author: v-alje

docs/code-quality/c28112.md

@@ -1,34 +1,43 @@
 ---
 description: "Learn more about: C28112"
 title: C28112
-ms.date: 11/04/2016
+ms.date: 08/25/2022
 ms.topic: reference
-f1_keywords: ["C28112"]
+f1_keywords: ["C28112", "INTERLOCKED_ACCESS", "__WARNING_INTERLOCKED_ACCESS"]
 helpviewer_keywords: ["C28112"]
 ms.assetid: 2720a5dc-84e9-4f78-a8c7-a320c9f9216b
 ---
-# C28112
+# Warning C28112
 
-> warning C28112: A variable which is accessed via an Interlocked function must always be accessed via an Interlocked function
+> A variable (*parameter-name*) which is accessed via an Interlocked function must always be accessed via an Interlocked function. See line *line-number*: It is not always safe to access a variable which is accessed via the Interlocked\* family of functions in any other way.
 
-See line *[number]*: It is not always safe to access a variable which is accessed via the Interlocked\* family of functions in any other way.
+A variable that is accessed by using the Interlocked executive support routines, such as InterlockedCompareExchangeAcquire, is later accessed by using a different function. 
 
-A variable that is accessed by using the Interlocked executive support routines, such as InterlockedCompareExchangeAcquire, is later accessed by using a different function. Although certain ordinary assignments, accesses, and comparisons to variables that are used by the Interlocked\* routines can be safely accessed by using a different function, the risk is great enough to justify examining each instance.
+## Remarks
+
+`InterlockedXxx` functions are intended to provide atomic operations, but are only atomic with respect to other `InterlockedXxx` functions. Although certain ordinary assignments, accesses, and comparisons to variables that are used by the Interlocked\* routines can be safely accessed by using a different function, the risk is great enough to justify examining each instance.
+
+Code analysis name: INTERLOCKED_ACCESS
 
 ## Example
 
-The following code example generates this warning:
+The following code generates this warning:
 
 ```cpp
-inter_var --;
-...
+inter_var--;
+//code
 InterlockedIncrement(&inter_var);
 ```
 
-The following code example avoids this warning:
+The following code corrects this warning by strictly accessing `inter_var` through `InterlockedXxx` functions:
 
 ```cpp
 InterlockedDecrement(&inter_var);
-...
+//code
 InterlockedIncrement(&inter_var);
 ```
+
+## See Also
+
+[InterlockedIncrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockedincrement)
+[InterlockedDecrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockeddecrement)

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/c28208.md

@@ -1,14 +1,41 @@
 ---
 description: "Learn more about: C28208"
 title: C28208
-ms.date: 11/04/2016
+ms.date: 10/03/2022
 ms.topic: reference
-f1_keywords: ["C28208"]
+f1_keywords: ["C28208", "FUNCTION_TYPE_REDECLARATION", "__WARNING_FUNCTION_TYPE_REDECLARATION"]
 helpviewer_keywords: ["C28208"]
 ms.assetid: e9a8ce37-3b05-4202-b078-5570ae496d1d
 ---
-# C28208
+# Warning C28208
 
-> warning C28208: Function \<function> was previously defined with a different parameter list at \<file>(\<line>). Some analysis tools will yield incorrect results
+> Function *function_name* was previously defined with a different parameter list at *file_name*(*line_number*). Some analysis tools will yield incorrect results
 
-This warning is reported when a function's known definition doesn't match another occurrence.
+## Remarks
+
+This warning almost always accompanies [Compiler Warning (level 1) C4028](../error-messages/compiler-warnings/compiler-warning-level-1-c4028.md). Both warn of a mismatch between the parameters of a function's declaration and its definition. However, this specific error indicates a more niche case than C4028. C28208 indicates not only that a mismatch exists, but that it also can cause issues with analysis tools. This warning most notably occurs when the mismatch exists between a `typedef` function pointer and the definition of that function. This warning is demonstrated in the example below.
+
+Code analysis name: `FUNCTION_TYPE_REDECLARATION`
+
+## Example
+
+The following code generates C28208. `test_type` declares `my_test1` and `my_test2` to take a `void*` parameter, but the definition of `my_test1` takes an `int*` parameter instead. `my_test2` avoids this issue because the definition parameters match the declaration parameters.
+
+```cpp
+// c28208_example.h
+typedef void test_type(void*);
+```
+
+```cpp
+// c28208_example.cpp
+#include "c28208_example.h"
+test_type my_test1;
+test_type my_test2;
+void my_test1(int* x){};  // Generates C28208
+void my_test2(void* x){};  // Doesn't generate C28208
+
+int main()
+{
+    // Code
+}
+```

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/c28285.md

@@ -1,35 +1,37 @@
 ---
 description: "Learn more about: C28285"
 title: C28285
-ms.date: 12/17/2019
+ms.date: 09/22/2022
 ms.topic: reference
-f1_keywords: ["C28285"]
+f1_keywords: ["C28285", "SPEC_INVALID_SYNTAX2", "__WARNING_SPEC_INVALID_SYNTAX2"]
 helpviewer_keywords: ["C28285"]
 ms.assetid: 6197eb0f-7e1e-4c3e-b097-1f6481405994
 ---
-# C28285
+# Warning C28285
 
-> warning C28285: For function 'function_name', syntax error in 'annotation'
+> For function '*function-name*', syntax error in '*annotation*'
 
-The Code Analysis tool reports this warning for syntax errors in the SAL annotation.  The SAL parser will recover by discarding the malformed annotation.
+## Remarks
+
+The Code Analysis tool reports this warning for syntax errors in the SAL annotation. The SAL parser will recover by discarding the malformed annotation. Double check the documentation for the SAL annotations being used and try to simplify the annotation. You shouldn't use implementation layer annotations such as `__declspec("SAL_begin")` directly. If you're using that layer, then change them into higher layers such as `_In_`/`_Out_`/`_Ret_`. For more information, see [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md).
 
 ## Example
 
+The following code generates this warning. The argument `(2,n)` is malformed and will cause a C28285 warning after the `_Out_writes_z_` macro is expanded.
+
 ```cpp
-// The argument '(n,2)' is malformed and will cause a C28285 warning after the _Out_writes_z_ macro is expanded.
 void example_func(_Out_writes_z_((2,n)) char* buffer, int n)
 {
-  // ...
-  buffer[n] = '\0';
+    buffer[n] = '\0';
 }
 ```
 
-Double check the documentation to the SAL annotations being used and try to simplify the annotation.  You should not use implementation layer annotations such as `__declspec("SAL_begin")` directly. If you are using that layer then change them into higher layers such as `_In_`/`_Out_`/`_Ret_`.  See [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md) for more information.
+The following code remediates this warning by correcting the malformed annotation
 
 ```cpp
 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)();
-    // ......
 }
 ```