C++: Add QLDoc for AST range analysis libraries

Author: Robert Marsh

cpp/ql/src/semmle/code/cpp/rangeanalysis/NanAnalysis.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes and predicates for recognizing floating point expressions which cannot be NaN.
+ */
+
 import cpp
 private import semmle.code.cpp.rangeanalysis.RangeSSA
 

cpp/ql/src/semmle/code/cpp/rangeanalysis/PointlessComparison.qll

@@ -11,8 +11,17 @@ private float lowerBoundFC(Expr expr) { result = lowerBound(expr.getFullyConvert
 /** Gets the upper bound of the fully converted expression. */
 private float upperBoundFC(Expr expr) { result = upperBound(expr.getFullyConverted()) }
 
+/**
+ * Describes which side of a pointless comparison is known to be smaller.
+ */
 newtype SmallSide =
+  /**
+   * Represents that the left side of a pointless comparison is known to be smaller.
+   */
   LeftIsSmaller() or
+  /**
+   * Represents that the right side of a pointless comparison is known to be smaller.
+   */
   RightIsSmaller()
 
 /**

cpp/ql/src/semmle/code/cpp/rangeanalysis/RangeAnalysisUtils.qll

@@ -5,15 +5,27 @@ import cpp
  * relation) or 'non-strict' (a `<=` or `>=` relation).
  */
 newtype RelationStrictness =
+  /**
+   * Represents that a relation is 'strict' (that is, a `<` or `>` relation).
+   */
   Strict() or
+  /**
+   * Represents that a relation is 'non-strict' (that is, a `<+` or `>+` relation)
+   */
   Nonstrict()
 
 /**
  * Describes whether a relation is 'greater' (that is, a `>` or `>=`
  * relation) or 'lesser' (a `<` or `<=` relation).
  */
 newtype RelationDirection =
+  /**
+   * Represents that a relation is 'greater' (that is, a `>` or `>=` relation).
+   */
   Greater() or
+  /**
+   * Represents that a relation is 'lesser' (that is, a `<` or `<=` relation).
+   */
   Lesser()
 
 private RelationStrictness negateStrictness(RelationStrictness strict) {
@@ -28,12 +40,18 @@ private RelationDirection negateDirection(RelationDirection dir) {
   dir = Lesser() and result = Greater()
 }
 
+/**
+ * Holds if `dir` is `Greater` (that is, a `>` or `>=` relation)
+ */
 boolean directionIsGreater(RelationDirection dir) {
   dir = Greater() and result = true
   or
   dir = Lesser() and result = false
 }
 
+/**
+ * Holds if `dir` is `Lesser` (that is, a `<` or `<=` relation)
+ */
 boolean directionIsLesser(RelationDirection dir) {
   dir = Greater() and result = false
   or

cpp/ql/src/semmle/code/cpp/rangeanalysis/RangeSSA.qll

@@ -25,6 +25,10 @@ import semmle.code.cpp.controlflow.Dominance
 import semmle.code.cpp.controlflow.SSAUtils
 private import RangeAnalysisUtils
 
+/**
+ * The SSA logic comes in two versions: the standard SSA and range-analysis RangeSSA.
+ * This class provides the range-analysis SSA logic.
+ */
 library class RangeSSA extends SSAHelper {
   RangeSSA() { this = 1 }
 
@@ -84,6 +88,7 @@ class RangeSsaDefinition extends ControlFlowNodeBase {
   /** Gets the control flow node for this definition. */
   ControlFlowNode getDefinition() { result = this }
 
+  /** Gets the basic block containing this definition. */
   BasicBlock getBasicBlock() { result.contains(getDefinition()) }
 
   /** Whether this definition is a phi node for variable `v`. */
@@ -97,11 +102,13 @@ class RangeSsaDefinition extends ControlFlowNodeBase {
     guard_defn(v, guard, this, branch)
   }
 
+  /** Gets the primary location of this definition. */
   Location getLocation() { result = this.(ControlFlowNode).getLocation() }
 
   /** Whether this definition is from a parameter */
   predicate definedByParameter(Parameter p) { this = p.getFunction().getEntryPoint() }
 
+  /** Gets a definition of `v` that is a phi input for this basic block. */
   RangeSsaDefinition getAPhiInput(StackVariable v) {
     this.isPhiNode(v) and
     exists(BasicBlock pred |
@@ -153,6 +160,9 @@ class RangeSsaDefinition extends ControlFlowNodeBase {
     )
   }
 
+  /**
+   * Holds if this definition of the variable `v` reached the end of the basic block `b`.
+   */
   predicate reachesEndOfBB(StackVariable v, BasicBlock b) {
     exists(RangeSSA x | x.ssaDefinitionReachesEndOfBB(v, this, b))
   }