Merge pull request github#3766 from rdmarsh2/rdmarsh/cpp/add-qldoc-3

C++: Add QLDocs for Initializer.qll-Macro.qll and model classes

Author: geoffw0

cpp/ql/src/semmle/code/cpp/Initializer.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides the `Initializer` class, representing C/C++ declaration initializers.
+ */
+
 import semmle.code.cpp.controlflow.ControlFlowGraph
 
 /**

cpp/ql/src/semmle/code/cpp/Iteration.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes for loop iteration variables.
+ */
+
 import semmle.code.cpp.Variable
 
 /**
@@ -7,14 +11,18 @@ import semmle.code.cpp.Variable
 class LoopCounter extends Variable {
   LoopCounter() { exists(ForStmt f | f.getAnIterationVariable() = this) }
 
-  // Gets an access of this variable within loop `f`.
+  /**
+   *  Gets an access of this variable within loop `f`.
+   */
   VariableAccess getVariableAccessInLoop(ForStmt f) {
     this.getALoop() = f and
     result.getEnclosingStmt().getParent*() = f and
     this = result.getTarget()
   }
 
-  // Gets a loop which uses this variable as its counter.
+  /**
+   * Gets a loop which uses this variable as its counter.
+   */
   ForStmt getALoop() { result.getAnIterationVariable() = this }
 }
 
@@ -25,14 +33,18 @@ class LoopCounter extends Variable {
 class LoopControlVariable extends Variable {
   LoopControlVariable() { this = loopControlVariable(_) }
 
-  // Gets an access of this variable within loop `f`.
+  /**
+   * Gets an access of this variable within loop `f`.
+   */
   VariableAccess getVariableAccessInLoop(ForStmt f) {
     this.getALoop() = f and
     result.getEnclosingStmt().getParent*() = f and
     this = result.getTarget()
   }
 
-  // Gets a loop which uses this variable as its control variable.
+  /**
+   * Gets a loop which uses this variable as its control variable.
+   */
   ForStmt getALoop() { this = loopControlVariable(result) }
 }
 

cpp/ql/src/semmle/code/cpp/Linkage.qll

@@ -1,3 +1,7 @@
+/**
+ * Proivdes the `LinkTarget` class representing linker invocations during the build process.
+ */
+
 import semmle.code.cpp.Class
 import semmle.code.cpp.File
 import semmle.code.cpp.Function

cpp/ql/src/semmle/code/cpp/Location.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes and predicates for locations in the source code.
+ */
+
 import semmle.code.cpp.Element
 import semmle.code.cpp.File
 

cpp/ql/src/semmle/code/cpp/Macro.qll

@@ -179,6 +179,11 @@ class MacroInvocation extends MacroAccess {
     result.(Stmt).getGeneratingMacro() = this
   }
 
+  /**
+   * Gets a function that includes an expression that is affected by this macro
+   * invocation. If the macro expansion includes the end of one function and
+   * the beginning of another, this predicate will get both.
+   */
   Function getEnclosingFunction() {
     result = this.getAnAffectedElement().(Expr).getEnclosingFunction()
   }

cpp/ql/src/semmle/code/cpp/models/implementations/Printf.qll

@@ -1,3 +1,10 @@
+/**
+ * Provides implementation classes modelling various standard formatting
+ * functions (`printf`, `snprintf` etc).
+ * See `semmle.code.cpp.models.interfaces.FormattingFunction` for usage
+ * information.
+ */
+
 import semmle.code.cpp.models.interfaces.FormattingFunction
 import semmle.code.cpp.models.interfaces.Alias
 

cpp/ql/src/semmle/code/cpp/models/implementations/Strcat.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides implementation classes modelling `strcat` and various similar functions.
+ * See `semmle.code.cpp.models.Models` for usage information.
+ */
+
 import semmle.code.cpp.models.interfaces.ArrayFunction
 import semmle.code.cpp.models.interfaces.DataFlow
 import semmle.code.cpp.models.interfaces.Taint

cpp/ql/src/semmle/code/cpp/models/interfaces/DataFlow.qll

@@ -19,5 +19,10 @@ import semmle.code.cpp.models.Models
  * to destinations; that is covered by `TaintModel.qll`.
  */
 abstract class DataFlowFunction extends Function {
+  /**
+   * Holds if data can be copied from the argument, qualifier, or buffer
+   * represented by `input` to the return value or buffer represented by
+   * `output`
+   */
   abstract predicate hasDataFlow(FunctionInput input, FunctionOutput output);
 }

cpp/ql/src/semmle/code/cpp/models/interfaces/FunctionInputsAndOutputs.qll

@@ -108,6 +108,20 @@ class FunctionInput extends TFunctionInput {
   predicate isQualifierAddress() { none() }
 }
 
+/**
+ * The input value of a parameter.
+ *
+ *  Example:
+ * ```
+ * void func(int n, char* p, float& r);
+ * ```
+ * - There is an `InParameter` representing the value of `n` (with type `int`) on entry to the
+ *   function.
+ * - There is an `InParameter` representing the value of `p` (with type `char*`) on entry to the
+ *   function.
+ * - There is an `InParameter` representing the "value" of the reference `r` (with type `float&`) on
+ *    entry to the function, _not_ the value of the referred-to `float`.
+ */
 class InParameter extends FunctionInput, TInParameter {
   ParameterIndex index;
 
@@ -121,6 +135,21 @@ class InParameter extends FunctionInput, TInParameter {
   override predicate isParameter(ParameterIndex i) { i = index }
 }
 
+/**
+ * The input value pointed to by a pointer parameter to a function, or the input value referred to
+ * by a reference parameter to a function.
+ *
+ * Example:
+ * ```
+ * void func(int n, char* p, float& r);
+ * ```
+ * - There is an `InParameterDeref` with `getIndex() = 1` that represents the value of `*p` (with
+ *   type `char`) on entry to the function.
+ * - There is an `InParameterDeref` with `getIndex() = 2` that represents the value of `r` (with
+ *   type `float`) on entry to the function.
+ * - There is no `InParameterDeref` representing the value of `n`, because `n` is neither a pointer
+ *   nor a reference.
+ */
 class InParameterDeref extends FunctionInput, TInParameterDeref {
   ParameterIndex index;
 
@@ -134,12 +163,36 @@ class InParameterDeref extends FunctionInput, TInParameterDeref {
   override predicate isParameterDeref(ParameterIndex i) { i = index }
 }
 
+/**
+ * The input value pointed to by the `this` pointer of an instance member function.
+ *
+ * Example:
+ * ```
+ * struct C {
+ *   void mfunc(int n, char* p, float& r) const;
+ * };
+ * ```
+ * - `InQualifierObject` represents the value of `*this` (with type `C const`) on entry to the
+ *   function.
+ */
 class InQualifierObject extends FunctionInput, TInQualifierObject {
   override string toString() { result = "InQualifierObject" }
 
   override predicate isQualifierObject() { any() }
 }
 
+/**
+ * The input value of the `this` pointer of an instance member function.
+ *
+ * Example:
+ * ```
+ * struct C {
+ *   void mfunc(int n, char* p, float& r) const;
+ * };
+ * ```
+ * - `InQualifierAddress` represents the value of `this` (with type `C const *`) on entry to the
+ *   function.
+ */
 class InQualifierAddress extends FunctionInput, TInQualifierAddress {
   override string toString() { result = "InQualifierAddress" }
 
@@ -265,6 +318,21 @@ class FunctionOutput extends TFunctionOutput {
   deprecated final predicate isOutReturnPointer() { isReturnValueDeref() }
 }
 
+/**
+ * The output value pointed to by a pointer parameter to a function, or the output value referred to
+ * by a reference parameter to a function.
+ *
+ * Example:
+ * ```
+ * void func(int n, char* p, float& r);
+ * ```
+ * - There is an `OutParameterDeref` with `getIndex()=1` that represents the value of `*p` (with
+ *   type `char`) on return from the function.
+ * - There is an `OutParameterDeref` with `getIndex()=2` that represents the value of `r` (with
+ *   type `float`) on return from the function.
+ * - There is no `OutParameterDeref` representing the value of `n`, because `n` is neither a
+ *   pointer nor a reference.
+ */
 class OutParameterDeref extends FunctionOutput, TOutParameterDeref {
   ParameterIndex index;
 
@@ -277,18 +345,62 @@ class OutParameterDeref extends FunctionOutput, TOutParameterDeref {
   override predicate isParameterDeref(ParameterIndex i) { i = index }
 }
 
+/**
+ * The output value pointed to by the `this` pointer of an instance member function.
+ *
+ * Example:
+ * ```
+ * struct C {
+ *   void mfunc(int n, char* p, float& r);
+ * };
+ * ```
+ * - The `OutQualifierObject` represents the value of `*this` (with type `C`) on return from the
+ *   function.
+ */
 class OutQualifierObject extends FunctionOutput, TOutQualifierObject {
   override string toString() { result = "OutQualifierObject" }
 
   override predicate isQualifierObject() { any() }
 }
 
+/**
+ * The value returned by a function.
+ *
+ * Example:
+ * ```
+ * int getInt();
+ * char* getPointer();
+ * float& getReference();
+ * ```
+ * - `OutReturnValue` represents the value returned by
+ *   `getInt()` (with type `int`).
+ * - `OutReturnValue` represents the value returned by
+ *   `getPointer()` (with type `char*`).
+ * - `OutReturnValue` represents the "value" of the reference returned by `getReference()` (with
+ *   type `float&`), _not_ the value of the referred-to `float`.
+ */
 class OutReturnValue extends FunctionOutput, TOutReturnValue {
   override string toString() { result = "OutReturnValue" }
 
   override predicate isReturnValue() { any() }
 }
 
+/**
+ * The output value pointed to by the return value of a function, if the function returns a pointer,
+ * or the output value referred to by the return value of a function, if the function returns a
+ * reference.
+ *
+ * Example:
+ * ```
+ * char* getPointer();
+ * float& getReference();
+ * int getInt();
+ * ```
+ * - `OutReturnValueDeref` represents the value of `*getPointer()` (with type `char`).
+ * - `OutReturnValueDeref` represents the value of `getReference()` (with type `float`).
+ * - `OutReturnValueDeref` does not represent the return value of `getInt()` because the return type
+ *   of `getInt()` is neither a pointer nor a reference.
+ */
 class OutReturnValueDeref extends FunctionOutput, TOutReturnValueDeref {
   override string toString() { result = "OutReturnValueDeref" }
 

cpp/ql/src/semmle/code/cpp/models/interfaces/Taint.qll

@@ -24,5 +24,9 @@ import semmle.code.cpp.models.Models
  * data flow.
  */
 abstract class TaintFunction extends Function {
+  /**
+   * Holds if data passed into the argument, qualifier, or buffer represented by
+   * `input` influences the return value or buffer represented by `output`
+   */
   abstract predicate hasTaintFlow(FunctionInput input, FunctionOutput output);
 }