C++: document new IR class and predicates

Robert Marsh · Robert Marsh · commit e40ce91e7e46 · 2018-09-20T10:06:18.000-07:00
diff --git a/cpp/ql/src/semmle/code/cpp/ir/implementation/aliased_ssa/Instruction.qll b/cpp/ql/src/semmle/code/cpp/ir/implementation/aliased_ssa/Instruction.qll
@@ -967,13 +967,31 @@ class CompareNEInstruction extends CompareInstruction {
   }
 }
 
+/**
+ * Represents an instruction that does a relative comparison of two values, such as `<` or `>=`.
+ */
 class RelationalInstruction extends CompareInstruction {
   RelationalInstruction() {
     opcode instanceof RelationalOpcode
   }
-
+  /**
+   * Gets the operand on the "greater" (or "greater-or-equal") side
+   * of this relational instruction, that is, the side that is larger
+   * if the overall instruction evaluates to `true`; for example on
+   * `x <= 20` this is the `20`, and on `y > 0` it is `y`.
+   */
   abstract Instruction getGreaterOperand();
+
+  /**
+   * Gets the operand on the "lesser" (or "lesser-or-equal") side
+   * of this relational instruction, that is, the side that is smaller
+   * if the overall instruction evaluates to `true`; for example on
+   * `x <= 20` this is `x`, and on `y > 0` it is the `0`.
+   */
   abstract Instruction getLesserOperand();
+  /**
+   * Holds if this relational instruction is strict (is not an "or-equal" instruction).
+   */
   abstract predicate isStrict();
 }
 
diff --git a/cpp/ql/src/semmle/code/cpp/ir/implementation/raw/Instruction.qll b/cpp/ql/src/semmle/code/cpp/ir/implementation/raw/Instruction.qll
@@ -967,13 +967,31 @@ class CompareNEInstruction extends CompareInstruction {
   }
 }
 
+/**
+ * Represents an instruction that does a relative comparison of two values, such as `<` or `>=`.
+ */
 class RelationalInstruction extends CompareInstruction {
   RelationalInstruction() {
     opcode instanceof RelationalOpcode
   }
-
+  /**
+   * Gets the operand on the "greater" (or "greater-or-equal") side
+   * of this relational instruction, that is, the side that is larger
+   * if the overall instruction evaluates to `true`; for example on
+   * `x <= 20` this is the `20`, and on `y > 0` it is `y`.
+   */
   abstract Instruction getGreaterOperand();
+
+  /**
+   * Gets the operand on the "lesser" (or "lesser-or-equal") side
+   * of this relational instruction, that is, the side that is smaller
+   * if the overall instruction evaluates to `true`; for example on
+   * `x <= 20` this is `x`, and on `y > 0` it is the `0`.
+   */
   abstract Instruction getLesserOperand();
+  /**
+   * Holds if this relational instruction is strict (is not an "or-equal" instruction).
+   */
   abstract predicate isStrict();
 }
 
diff --git a/cpp/ql/src/semmle/code/cpp/ir/implementation/unaliased_ssa/Instruction.qll b/cpp/ql/src/semmle/code/cpp/ir/implementation/unaliased_ssa/Instruction.qll
@@ -967,13 +967,31 @@ class CompareNEInstruction extends CompareInstruction {
   }
 }
 
+/**
+ * Represents an instruction that does a relative comparison of two values, such as `<` or `>=`.
+ */
 class RelationalInstruction extends CompareInstruction {
   RelationalInstruction() {
     opcode instanceof RelationalOpcode
   }
-
+  /**
+   * Gets the operand on the "greater" (or "greater-or-equal") side
+   * of this relational instruction, that is, the side that is larger
+   * if the overall instruction evaluates to `true`; for example on
+   * `x <= 20` this is the `20`, and on `y > 0` it is `y`.
+   */
   abstract Instruction getGreaterOperand();
+
+  /**
+   * Gets the operand on the "lesser" (or "lesser-or-equal") side
+   * of this relational instruction, that is, the side that is smaller
+   * if the overall instruction evaluates to `true`; for example on
+   * `x <= 20` this is `x`, and on `y > 0` it is the `0`.
+   */
   abstract Instruction getLesserOperand();
+  /**
+   * Holds if this relational instruction is strict (is not an "or-equal" instruction).
+   */
   abstract predicate isStrict();
 }
 
