PRE31-C: Update metadata and docs

 * Add an implementation scope
 * Add qldocs
 * Update description.

Author: lcartey

c/cert/src/rules/PRE31-C/SideEffectsInArgumentsToUnsafeMacros.md

@@ -202,7 +202,7 @@ Search for [vulnerabilities](https://wiki.sei.cmu.edu/confluence/display/c/BB.+D
 
 ## Implementation notes
 
-None
+This implementation only considers ++ and function call side effects. Due to the textual nature of macro expansion it is not always possible to determine accurately whether a side-effect was produced by a particular argument, and this may cause both false positives and false negatives. The query does not consider the case where a macro argument including a side-effect is never evaluated.
 
 ## References
 

c/cert/src/rules/PRE31-C/SideEffectsInArgumentsToUnsafeMacros.ql

@@ -2,7 +2,7 @@
  * @id c/cert/side-effects-in-arguments-to-unsafe-macros
  * @name PRE31-C: Avoid side effects in arguments to unsafe macros
  * @description Macro arguments can be expanded multiple times which can cause side-effects to be
- *              evaluated multiple times.
+ *              evaluated multiple times leading to unexpected program behavior.
  * @kind problem
  * @precision low
  * @problem.severity error
@@ -20,6 +20,9 @@ import codingstandards.cpp.sideeffect.DefaultEffects
 import codingstandards.cpp.sideeffect.Customizations
 import semmle.code.cpp.valuenumbering.HashCons
 
+/**
+ * Add side-effecting functions to the default set of side-effects.
+ */
 class FunctionCallEffect extends GlobalSideEffect::Range {
   FunctionCallEffect() {
     exists(Function f |
@@ -44,6 +47,9 @@ class FunctionCallEffect extends GlobalSideEffect::Range {
   }
 }
 
+/**
+ * Add crement operations to the default set of side-effects.
+ */
 class CrementEffect extends LocalSideEffect::Range {
   CrementEffect() { this instanceof CrementOperation }
 }

rule_packages/c/SideEffects4.json

@@ -6,15 +6,18 @@
       },
       "queries": [
         {
-          "description": "Macro arguments can be expanded multiple times which can cause side-effects to be evaluated multiple times.",
+          "description": "Macro arguments can be expanded multiple times which can cause side-effects to be evaluated multiple times leading to unexpected program behavior.",
           "kind": "problem",
           "name": "Avoid side effects in arguments to unsafe macros",
           "precision": "low",
           "severity": "error",
           "short_name": "SideEffectsInArgumentsToUnsafeMacros",
           "tags": [
             "correctness"
-          ]
+          ],
+          "implementation_scope": {
+            "description": "This implementation only considers ++ and function call side effects. Due to the textual nature of macro expansion it is not always possible to determine accurately whether a side-effect was produced by a particular argument, and this may cause both false positives and false negatives. The query does not consider the case where a macro argument including a side-effect is never evaluated."
+          }
         }
       ],
       "title": "Avoid side effects in arguments to unsafe macros"