C++: comments about shared Operand IPA type

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

@@ -13,13 +13,17 @@ private import Imports::OperandTag
 private import Imports::TOperand
 private import internal.OperandInternal
 
-class TOperand = TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
+/**
+ * An operand of an `Instruction` in this stage of the IR. Implemented as a union of the branches
+ * of `TOperand` that are used in this stage.
+ */
+private class TStageOperand = TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
 
 /**
  * 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 {
+class Operand extends TStageOperand {
   /** Gets a textual representation of this element. */
   string toString() { result = "Operand" }
 

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

@@ -43,9 +43,6 @@ private module Cached {
   class TStageInstruction =
     TRawInstruction or TPhiInstruction or TChiInstruction or TUnreachedInstruction;
 
-  class TStageOperand =
-    TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
-
   cached
   predicate hasInstruction(TStageInstruction instr) {
     instr instanceof TRawInstruction and instr instanceof OldInstruction

cpp/ql/src/semmle/code/cpp/ir/implementation/internal/TOperand.qll

@@ -8,7 +8,18 @@ private import semmle.code.cpp.ir.implementation.unaliased_ssa.IR as Unaliased
 private import semmle.code.cpp.ir.implementation.aliased_ssa.IR as Aliased
 private import semmle.code.cpp.ir.internal.Overlap
 
+/**
+ * Provides the newtype used to represent operands across all phases of the IR.
+ */
 private module Internal {
+  
+  /**
+   * An IR operand. `TOperand` is shared across all phases of the IR. There are branches of this
+   * type for operands created directly from the AST (`TRegisterOperand` and `TNonSSAMemoryOperand`),
+   * for operands computed by each stage of SSA construction (`T*PhiOperand` and
+   * `TAliasedChiOperand`), and a placehold branch for operands that do not exist in a given
+   * stage of IR construction (`TNoOperand`).
+   */
   cached
   newtype TOperand =
     // RAW
@@ -51,6 +62,10 @@ private module Internal {
     }
 }
 
+/**
+ * Reexports some branches from `TOperand` so they can be used in stage modules without importing
+ * `TOperand` itself.
+ */
 private module Shared {
   class TRegisterOperand = Internal::TRegisterOperand;
 
@@ -73,6 +88,12 @@ private module Shared {
   }
 }
 
+/**
+ * Provides wrappers for the constructors of each branch of `TOperand` that is used by the
+ * raw IR stage.
+ * These wrappers are not parameterized because it is not possible to invoke an IPA constructor via
+ * a class alias.
+ */
 module RawOperands {
   import Shared
 
@@ -96,9 +117,12 @@ module RawOperands {
   TChiOperand chiOperand(Raw::Instruction useInstr, ChiOperandTag tag) { none() }
 }
 
-// TODO: can we get everything into either here or Operand.qll?
-// TODO: can we put `TStageOperand` in Construction? Might break something about the module caching setup, `Operand` is currently after everything in SSAConstruction
-// TODO: share empty ChiOperand?
+/**
+ * Provides wrappers for the constructors of each branch of `TOperand` that is used by the
+ * unaliased SSA stage.
+ * These wrappers are not parameterized because it is not possible to invoke an IPA constructor via
+ * a class alias.
+ */
 module UnliasedSSAOperands {
   import Shared
 
@@ -122,6 +146,12 @@ module UnliasedSSAOperands {
   TChiOperand chiOperand(Unaliased::Instruction useInstr, ChiOperandTag tag) { none() }
 }
 
+/**
+ * Provides wrappers for the constructors of each branch of `TOperand` that is used by the
+ * asliased SSA stage.
+ * These wrappers are not parameterized because it is not possible to invoke an IPA constructor via
+ * a class alias.
+ */
 module AliasedSSAOperands {
   import Shared
 

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

@@ -13,13 +13,17 @@ private import Imports::OperandTag
 private import Imports::TOperand
 private import internal.OperandInternal
 
-class TOperand = TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
+/**
+ * An operand of an `Instruction` in this stage of the IR. Implemented as a union of the branches
+ * of `TOperand` that are used in this stage.
+ */
+private class TStageOperand = TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
 
 /**
  * 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 {
+class Operand extends TStageOperand {
   /** Gets a textual representation of this element. */
   string toString() { result = "Operand" }
 

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

@@ -13,13 +13,17 @@ private import Imports::OperandTag
 private import Imports::TOperand
 private import internal.OperandInternal
 
-class TOperand = TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
+/**
+ * An operand of an `Instruction` in this stage of the IR. Implemented as a union of the branches
+ * of `TOperand` that are used in this stage.
+ */
+private class TStageOperand = TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
 
 /**
  * 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 {
+class Operand extends TStageOperand {
   /** Gets a textual representation of this element. */
   string toString() { result = "Operand" }
 

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

@@ -43,9 +43,6 @@ private module Cached {
   class TStageInstruction =
     TRawInstruction or TPhiInstruction or TChiInstruction or TUnreachedInstruction;
 
-  class TStageOperand =
-    TRegisterOperand or TNonSSAMemoryOperand or TPhiOperand or TChiOperand;
-
   cached
   predicate hasInstruction(TStageInstruction instr) {
     instr instanceof TRawInstruction and instr instanceof OldInstruction