sal documentation additions

learn-build-service-prod · Mar 23, 2023 · Feb 22, 2023 · Mar 2, 2023 · Mar 8, 2023 · Mar 9, 2023
commit 6739bf5bd861e5c94092324b9118d919adc1b9de
diff --git a/docs/code-quality/c28308.md b/docs/code-quality/c28308.md
@@ -1,21 +1,50 @@
 ---
 description: "Learn more about: Warning C28308"
 title: Warning C28308
-ms.date: 11/04/2016
-f1_keywords: ["C28308"]
+ms.date: 03/07/2023
+f1_keywords: ["C28308", ", "BAD_FORMAT_ARGUMENT_POSITION", "__WARNING_BAD_FORMAT_ARGUMENT_POSITION"]
 helpviewer_keywords: ["C28308"]
-ms.assetid: 2be46de3-844e-4cd6-a97f-d5c12ac9dc31
 ---
 # Warning C28308
 
 > The format list argument position specified by the annotation is incorrect.
 
-The format list argument position must be either a parameter name, or an integer offset that's in the parameter list, or zero.
+## Remarks
 
-The second parameter to `IsFormatString2` (`where`) can be in one of two forms:
+This warning indicates a `_*_format_strings_param(position)` sal annotation is specifying an invalid position for the first parameter to the format string. The annotation helps the checker verify `printf` style formatting strings passed to the function. This issue will result in other validity checks on the format specifier parameters to fail.
 
-- A parameter name, which is taken as the first argument to the format string.
+The `_*_format_strings_param(position)` sal annotation is attached to the formatting string argument. `position` must be in one of these forms:
 
-- An offset (`n`) relative to the format-string parameter.
+- An identifier, which is taken as the first argument to the format string. If the identifier is not the name of a parameter to the function a warning is emitted.
+- A positive integer offset relative to the format-string parameter where `1` is the next parameter. If the offset is out of bounds for the parameters, a warning is emitted.
+- The value `0`, which is interpreted as the `...` parameter. If the function is not variadic then this warning is emitted.
 
-  In the second form, the first format-string parameter is the `n`-th argument after the format string. If `n` is zero, an ellipsis is specified as the parameter. Specifying an offset of zero without specifying the ellipsis as the first format-string parameter will cause an error.
+One limitation of this check, is that it is run at the function call site and not at the declaration. This is a side effect of the lazy evaluation of SAL annotations.
+
+## Examples
+
+In this example there is a specialized function for logging coordinates. The params annotation specifies the `...` parameter which does not exist.
+
+```cpp
+void LogCoordinate(_Printf_format_string_params_(0) _In_ char *format, int x, int y);
+
+void func(int x, int y)
+{
+    LogCoordinate("(%d, %d)", x, y);
+}
+```
+
+This issue is fixed by changing the annotated position to `x` or `1`. To determine the correct value for your code, check the behavior of the called function.
+
+```cpp
+void LogCoordinate(_Printf_format_string_params_(1) _In_ char *format, int x, int y);
+
+void func(int x, int y)
+{
+    LogCoordinate("(%d, %d)", x, y);
+}
+```
+
+## See also
+
+[Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md)