Merge pull request #1924 from geoffw0/quickfix

CPP: Tiny qldoc fixes.

cpp/ql/src/jsf/4.10 Classes/AV Rule 81.ql

@@ -51,7 +51,7 @@ class ReferenceCopyAssignmentOperator extends MemberFunction {
 
   /**
    * A call to a function called swap. Note: could be a member,
-   * std::swap or a function overloading std::swap (not in std::)
+   * `std::swap` or a function overloading `std::swap` (not in `std::`)
    * so keep it simple
    */
   FunctionCall getASwapCall() {

cpp/ql/src/jsf/4.21 Operators/AV Rule 159.ql

@@ -10,7 +10,7 @@
 
 /*
  * See More Effective C++ item 7.
- * Note: Meyers allows unary & to be overloaded but not comma
+ * Note: Meyers allows unary `&` to be overloaded but not comma.
  */
 
 import cpp

cpp/ql/src/jsf/4.28 Portable Code/AV Rule 213.ql

@@ -15,11 +15,11 @@ import cpp
 /*
  * Interpretation and deviations:
  *   - if the higher operator has precedence > arithmetic then it is fine
- *     RATIONALE: exprs like f(), *x, &x are easily understood to bind tightly
+ *     RATIONALE: exprs like `f()`, `*x`, `&x` are easily understood to bind tightly
  *   - if the higher operator is the RHS of an assign then it is fine
  *     RATIONALE: cf. MISRA, too many cases excluded otherwise
  *   - comparison operators can be mixed with arithmetic
- *     RATIONALE: x==y+z is common and unambiguous
+ *     RATIONALE: `x==y+z` is common and unambiguous
  */
 
 predicate arithmeticPrecedence(int p) { p = 12 or p = 13 }

cpp/ql/src/semmle/code/cpp/controlflow/Guards.qll

@@ -156,7 +156,7 @@ private predicate compares_eq(
 
 /**
  * If `test => part` and `part => left == right + k` then `test => left == right + k`.
- *    Similarly for the case where `test` is false.
+ * Similarly for the case where `test` is false.
  */
 private predicate logical_comparison_eq(
   BinaryLogicalOperation test, Expr left, Expr right, int k, boolean areEqual, boolean testIsTrue
@@ -275,7 +275,7 @@ private predicate compares_ge(
 
 /**
  * If `test => part` and `part => left < right + k` then `test => left < right + k`.
- *    Similarly for the case where `test` evaluates false.
+ * Similarly for the case where `test` evaluates false.
  */
 private predicate logical_comparison_lt(
   BinaryLogicalOperation test, Expr left, Expr right, int k, boolean isLt, boolean testIsTrue
@@ -362,7 +362,7 @@ private predicate add_lt(
   )
 }
 
-/** The int value of integer constant expression. */
+/** The `int` value of integer constant expression. */
 private int int_value(Expr e) {
   e.getUnderlyingType() instanceof IntegralType and
   result = e.getValue().toInt()

cpp/ql/src/semmle/code/cpp/controlflow/SSA.qll

@@ -29,11 +29,11 @@ class SsaDefinition extends ControlFlowNodeBase {
 
   /**
    * Gets a string representation of the SSA variable represented by the pair
-   * (this, v).
+   * `(this, v)`.
    */
   string toString(LocalScopeVariable v) { exists(StandardSSA x | result = x.toString(this, v)) }
 
-  /** Gets a use of the SSA variable represented by the pair (this, v). */
+  /** Gets a use of the SSA variable represented by the pair `(this, v)`. */
   VariableAccess getAUse(LocalScopeVariable v) {
     exists(StandardSSA x | result = x.getAUse(this, v))
   }

cpp/ql/src/semmle/code/cpp/padding/Padding.qll

@@ -2,8 +2,8 @@ import cpp
 
 /**
  * Align the specified offset up to the specified alignment boundary.
- * The result is the smallest integer i such that (i % alignment) = 0
- * and (i >= offset)
+ * The result is the smallest integer `i` such that `(i % alignment) = 0`
+ * and `(i >= offset)`.
  */
 bindingset[offset, alignment]
 private int alignUp(int offset, int alignment) {
@@ -30,16 +30,16 @@ abstract class Architecture extends string {
   /** Gets the size of a pointer, in bits. */
   abstract int pointerSize();
 
-  /** Gets the size of a 'long int', in bits. */
+  /** Gets the size of a `long int`, in bits. */
   abstract int longSize();
 
-  /** Gets the size of a 'long double', in bits. */
+  /** Gets the size of a `long double`, in bits. */
   abstract int longDoubleSize();
 
-  /** Gets the size of a 'long long', in bits. */
+  /** Gets the size of a `long long`, in bits. */
   abstract int longLongSize();
 
-  /** Gets the size of a 'wchar_t', in bits. */
+  /** Gets the size of a `wchar_t`, in bits. */
   abstract int wideCharSize();
 
   /** Gets the alignment boundary for doubles, in bits. */
@@ -479,8 +479,10 @@ class PaddedType extends Class {
   int typeBitSize(Architecture arch) {
     if this instanceof Union
     then
-      // A correct implementation for unions would be
+      // A correct implementation for unions would be:
+      // ```
       //     result = max(fieldSize(_, arch))
+      // ```
       // but that uses a recursive aggregate, which isn't supported in
       // QL. We therefore use this slightly more complex implementation
       // instead.

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

@@ -2,7 +2,7 @@
  * This library is a clone of semmle.code.cpp.controlflow.SSA, with
  * only one difference: extra phi definitions are added after
  * guards. For example:
- *
+ * ```
  *     x = f();
  *     if (x < 10) {
  *       // Block 1
@@ -11,12 +11,12 @@
  *       // Block 2
  *       ...
  *     }
- *
+ * ```
  * In standard SSA, basic blocks 1 and 2 do not need phi definitions
- * for x, because they are dominated by the definition of x on the
- * first line.  In RangeSSA, however, we add phi definitions for x at
+ * for `x`, because they are dominated by the definition of `x` on the
+ * first line.  In RangeSSA, however, we add phi definitions for `x` at
  * the beginning of blocks 1 and 2. This is useful for range analysis
- * because it enables us to deduce a more accurate range for x in the
+ * because it enables us to deduce a more accurate range for `x` in the
  * two branches of the if-statement.
  */
 
@@ -74,19 +74,19 @@ class RangeSsaDefinition extends ControlFlowNodeBase {
 
   /**
    * A string representation of the SSA variable represented by the pair
-   * (this, v).
+   * `(this, v)`.
    */
   string toString(LocalScopeVariable v) { exists(RangeSSA x | result = x.toString(this, v)) }
 
-  /** Gets a use of the SSA variable represented by the pair (this, v) */
+  /** Gets a use of the SSA variable represented by the pair `(this, v)`. */
   VariableAccess getAUse(LocalScopeVariable v) { exists(RangeSSA x | result = x.getAUse(this, v)) }
 
-  /** Gets the control flow node for this definition */
+  /** Gets the control flow node for this definition. */
   ControlFlowNode getDefinition() { result = this }
 
   BasicBlock getBasicBlock() { result.contains(getDefinition()) }
 
-  /** Whether this definition is a phi node for variable v */
+  /** Whether this definition is a phi node for variable `v`. */
   predicate isPhiNode(LocalScopeVariable v) {
     exists(RangeSSA x | x.phi_node(v, this.(BasicBlock)))
   }
@@ -136,7 +136,7 @@ class RangeSsaDefinition extends ControlFlowNodeBase {
     )
   }
 
-  /** Gets the expression assigned to this SsaDefinition */
+  /** Gets the expression assigned to this SsaDefinition. */
   Expr getDefiningValue(LocalScopeVariable v) {
     exists(ControlFlowNode def | def = this.getDefinition() |
       def = v.getInitializer().getExpr() and def = result