Merge pull request #4343 from rdmarsh2/rdmarsh2/cpp/ir-construction-qldoc

C++: Add some IR QLDoc

Author: jbj

cpp/ql/src/semmle/code/cpp/ir/implementation/aliased_ssa/Operand.qll

@@ -79,7 +79,8 @@ private PhiOperandBase phiOperand(
 }
 
 /**
- * A source operand of an `Instruction`. The operand represents a value consumed by the instruction.
+ * An operand of an `Instruction`. The operand represents a use of the result of one instruction
+ * (the defining instruction) in another instruction (the use instruction)
  */
 class Operand extends TOperand {
   /** Gets a textual representation of this element. */

cpp/ql/src/semmle/code/cpp/ir/implementation/aliased_ssa/internal/AliasedSSA.qll

@@ -133,6 +133,12 @@ abstract class MemoryLocation extends TMemoryLocation {
   predicate isAlwaysAllocatedOnStack() { none() }
 }
 
+/**
+ * Represents a set of `MemoryLocation`s that cannot overlap with
+ * `MemoryLocation`s outside of the set. The `VirtualVariable` will be
+ * represented by a `MemoryLocation` that totally overlaps all other
+ * `MemoryLocations` in the set.
+ */
 abstract class VirtualVariable extends MemoryLocation { }
 
 abstract class AllocationMemoryLocation extends MemoryLocation {

cpp/ql/src/semmle/code/cpp/ir/implementation/raw/Operand.qll

@@ -79,7 +79,8 @@ private PhiOperandBase phiOperand(
 }
 
 /**
- * A source operand of an `Instruction`. The operand represents a value consumed by the instruction.
+ * An operand of an `Instruction`. The operand represents a use of the result of one instruction
+ * (the defining instruction) in another instruction (the use instruction)
  */
 class Operand extends TOperand {
   /** Gets a textual representation of this element. */

cpp/ql/src/semmle/code/cpp/ir/implementation/unaliased_ssa/Operand.qll

@@ -79,7 +79,8 @@ private PhiOperandBase phiOperand(
 }
 
 /**
- * A source operand of an `Instruction`. The operand represents a value consumed by the instruction.
+ * An operand of an `Instruction`. The operand represents a use of the result of one instruction
+ * (the defining instruction) in another instruction (the use instruction)
  */
 class Operand extends TOperand {
   /** Gets a textual representation of this element. */

cpp/ql/src/semmle/code/cpp/ir/implementation/unaliased_ssa/internal/SimpleSSA.qll

@@ -59,6 +59,12 @@ class MemoryLocation extends TMemoryLocation {
   final string getUniqueId() { result = var.getUniqueId() }
 }
 
+/**
+ * Represents a set of `MemoryLocation`s that cannot overlap with
+ * `MemoryLocation`s outside of the set. The `VirtualVariable` will be
+ * represented by a `MemoryLocation` that totally overlaps all other
+ * `MemoryLocations` in the set.
+ */
 class VirtualVariable extends MemoryLocation { }
 
 /** A virtual variable that groups all escaped memory within a function. */

cpp/ql/src/semmle/code/cpp/ir/internal/Overlap.qll

@@ -3,18 +3,33 @@ private newtype TOverlap =
   TMustTotallyOverlap() or
   TMustExactlyOverlap()
 
+/**
+ * Represents a possible overlap between two memory ranges.
+ */
 abstract class Overlap extends TOverlap {
   abstract string toString();
 }
 
+/**
+ * Represents a partial overlap between two memory ranges, which may or may not
+ * actually occur in practice.
+ */
 class MayPartiallyOverlap extends Overlap, TMayPartiallyOverlap {
   final override string toString() { result = "MayPartiallyOverlap" }
 }
 
+/**
+ * Represents an overlap in which the first memory range is known to include all
+ * bits of the second memory range, but may be larger or have a different type.
+ */
 class MustTotallyOverlap extends Overlap, TMustTotallyOverlap {
   final override string toString() { result = "MustTotallyOverlap" }
 }
 
+/**
+ * Represents an overlap between two memory ranges that have the same extent and
+ * the same type.
+ */
 class MustExactlyOverlap extends Overlap, TMustExactlyOverlap {
   final override string toString() { result = "MustExactlyOverlap" }
 }

csharp/ql/src/experimental/ir/implementation/raw/Operand.qll

@@ -79,7 +79,8 @@ private PhiOperandBase phiOperand(
 }
 
 /**
- * A source operand of an `Instruction`. The operand represents a value consumed by the instruction.
+ * An operand of an `Instruction`. The operand represents a use of the result of one instruction
+ * (the defining instruction) in another instruction (the use instruction)
  */
 class Operand extends TOperand {
   /** Gets a textual representation of this element. */

csharp/ql/src/experimental/ir/implementation/unaliased_ssa/Operand.qll

@@ -79,7 +79,8 @@ private PhiOperandBase phiOperand(
 }
 
 /**
- * A source operand of an `Instruction`. The operand represents a value consumed by the instruction.
+ * An operand of an `Instruction`. The operand represents a use of the result of one instruction
+ * (the defining instruction) in another instruction (the use instruction)
  */
 class Operand extends TOperand {
   /** Gets a textual representation of this element. */

csharp/ql/src/experimental/ir/implementation/unaliased_ssa/internal/SimpleSSA.qll

@@ -59,6 +59,12 @@ class MemoryLocation extends TMemoryLocation {
   final string getUniqueId() { result = var.getUniqueId() }
 }
 
+/**
+ * Represents a set of `MemoryLocation`s that cannot overlap with
+ * `MemoryLocation`s outside of the set. The `VirtualVariable` will be
+ * represented by a `MemoryLocation` that totally overlaps all other
+ * `MemoryLocations` in the set.
+ */
 class VirtualVariable extends MemoryLocation { }
 
 /** A virtual variable that groups all escaped memory within a function. */

csharp/ql/src/experimental/ir/internal/Overlap.qll

@@ -3,18 +3,33 @@ private newtype TOverlap =
   TMustTotallyOverlap() or
   TMustExactlyOverlap()
 
+/**
+ * Represents a possible overlap between two memory ranges.
+ */
 abstract class Overlap extends TOverlap {
   abstract string toString();
 }
 
+/**
+ * Represents a partial overlap between two memory ranges, which may or may not
+ * actually occur in practice.
+ */
 class MayPartiallyOverlap extends Overlap, TMayPartiallyOverlap {
   final override string toString() { result = "MayPartiallyOverlap" }
 }
 
+/**
+ * Represents an overlap in which the first memory range is known to include all
+ * bits of the second memory range, but may be larger or have a different type.
+ */
 class MustTotallyOverlap extends Overlap, TMustTotallyOverlap {
   final override string toString() { result = "MustTotallyOverlap" }
 }
 
+/**
+ * Represents an overlap between two memory ranges that have the same extent and
+ * the same type.
+ */
 class MustExactlyOverlap extends Overlap, TMustExactlyOverlap {
   final override string toString() { result = "MustExactlyOverlap" }
 }