PRE31-C: Improve docs

Author: lcartey

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

@@ -23,10 +23,11 @@ import semmle.code.cpp.valuenumbering.HashCons
 class FunctionCallEffect extends GlobalSideEffect::Range {
   FunctionCallEffect() {
     exists(Function f |
+      // Capture function calls as side-effects
       f = this.(FunctionCall).getTarget() and
-      // Not a side-effecting function
+      // Excluding __builtin_expect, which is not a side-effecting function
       not f.(BuiltInFunction).getName() = "__builtin_expect" and
-      // Not side-effecting functions
+      // Excluding common math functions
       not exists(string name |
         name =
           [
@@ -80,13 +81,20 @@ class UnsafeMacroInvocation extends MacroInvocation {
   SideEffect getSideEffectForUnsafeArg(int index) {
     index = this.getMacro().(UnsafeMacro).getAnUnsafeArgumentIndex() and
     exists(Expr e, string arg |
-      arg = this.getExpandedArgument(index) and
       e = this.getAnExpandedElement() and
       result = getASideEffect(e) and
+      // Unfortunately, there's no semantic way to check whether a particular expression or
+      // side-effect generated by a macro came from a particular macro argument. The only
+      // information we get is the string of the expanded argument. We therefore do some basic
+      // string matching to check whether it looks like this side-effect comes from the given
+      // argument
+      arg = this.getExpandedArgument(index) and
       (
+        // If this is a crement effect, then check that the text of the macro argument includes -- or ++
         result instanceof CrementEffect and
         exists(arg.indexOf(result.(CrementOperation).getOperator()))
         or
+        // If this is a functional call effect, then check that the text of the macro argument includes a call to that function
         result instanceof FunctionCallEffect and
         exists(arg.indexOf(result.(FunctionCall).getTarget().getName() + "("))
       )