C++: QLDoc for IRVariable

Moved a couple of predicates that were only needed by IR construction into `TranslatedElement.qll`

Author: Dave Bartolomeo

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

@@ -7,15 +7,11 @@ private import Imports::TTempVariableTag
 private import Imports::TIRVariable
 private import Imports::IRType
 
-IRUserVariable getIRUserVariable(Language::Function func, Language::Variable var) {
-  result.getVariable() = var and
-  result.getEnclosingFunction() = func
-}
-
 /**
- * A variable referenced by the IR for a function. The variable may be a user-declared variable
- * (`IRUserVariable`) or a temporary variable generated by the AST-to-IR translation
- * (`IRTempVariable`).
+ * A variable referenced by the IR for a function.
+ *
+ * The variable may be a user-declared variable (`IRUserVariable`) or a temporary variable generated
+ * by the AST-to-IR translation (`IRTempVariable`).
  */
 class IRVariable extends TIRVariable {
   Language::Function func;
@@ -27,6 +23,7 @@ class IRVariable extends TIRVariable {
     this = TIRDynamicInitializationFlag(func, _, _)
   }
 
+  /** Gets a textual representation of this element. */
   string toString() { none() }
 
   /**
@@ -162,20 +159,26 @@ class IRGeneratedVariable extends IRVariable {
 
   override string getUniqueId() { none() }
 
+  /**
+   * Gets a string containing the source code location of the AST that generated this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   final string getLocationString() {
     result =
       ast.getLocation().getStartLine().toString() + ":" +
         ast.getLocation().getStartColumn().toString()
   }
 
+  /**
+   * Gets the string that is combined with the location of the variable to generate the string
+   * representation of this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   string getBaseString() { none() }
 }
 
-IRTempVariable getIRTempVariable(Language::AST ast, TempVariableTag tag) {
-  result.getAST() = ast and
-  result.getTag() = tag
-}
-
 /**
  * A temporary variable introduced by IR construction. The most common examples are the variable
  * generated to hold the return value of a function, or the variable generated to hold the result of
@@ -190,6 +193,10 @@ class IRTempVariable extends IRGeneratedVariable, IRAutomaticVariable, TIRTempVa
     result = "Temp: " + Construction::getTempVariableUniqueId(this)
   }
 
+  /**
+   * Gets the "tag" object that differentiates this temporary variable from other temporary
+   * variables generated for the same AST.
+   */
   final TempVariableTag getTag() { result = tag }
 
   override string getBaseString() { result = "#temp" }
@@ -253,6 +260,9 @@ class IRStringLiteral extends IRGeneratedVariable, TIRStringLiteral {
 
   final override string getBaseString() { result = "#string" }
 
+  /**
+   * Gets the AST of the string literal represented by this `IRStringLiteral`.
+   */
   final Language::StringLiteral getLiteral() { result = literal }
 }
 
@@ -270,6 +280,9 @@ class IRDynamicInitializationFlag extends IRGeneratedVariable, TIRDynamicInitial
 
   final override string toString() { result = var.toString() + "#init" }
 
+  /**
+   * Gets variable whose initialization is guarded by this flag.
+   */
   final Language::Variable getVariable() { result = var }
 
   final override string getUniqueId() {

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

@@ -7,15 +7,11 @@ private import Imports::TTempVariableTag
 private import Imports::TIRVariable
 private import Imports::IRType
 
-IRUserVariable getIRUserVariable(Language::Function func, Language::Variable var) {
-  result.getVariable() = var and
-  result.getEnclosingFunction() = func
-}
-
 /**
- * A variable referenced by the IR for a function. The variable may be a user-declared variable
- * (`IRUserVariable`) or a temporary variable generated by the AST-to-IR translation
- * (`IRTempVariable`).
+ * A variable referenced by the IR for a function.
+ *
+ * The variable may be a user-declared variable (`IRUserVariable`) or a temporary variable generated
+ * by the AST-to-IR translation (`IRTempVariable`).
  */
 class IRVariable extends TIRVariable {
   Language::Function func;
@@ -27,6 +23,7 @@ class IRVariable extends TIRVariable {
     this = TIRDynamicInitializationFlag(func, _, _)
   }
 
+  /** Gets a textual representation of this element. */
   string toString() { none() }
 
   /**
@@ -162,20 +159,26 @@ class IRGeneratedVariable extends IRVariable {
 
   override string getUniqueId() { none() }
 
+  /**
+   * Gets a string containing the source code location of the AST that generated this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   final string getLocationString() {
     result =
       ast.getLocation().getStartLine().toString() + ":" +
         ast.getLocation().getStartColumn().toString()
   }
 
+  /**
+   * Gets the string that is combined with the location of the variable to generate the string
+   * representation of this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   string getBaseString() { none() }
 }
 
-IRTempVariable getIRTempVariable(Language::AST ast, TempVariableTag tag) {
-  result.getAST() = ast and
-  result.getTag() = tag
-}
-
 /**
  * A temporary variable introduced by IR construction. The most common examples are the variable
  * generated to hold the return value of a function, or the variable generated to hold the result of
@@ -190,6 +193,10 @@ class IRTempVariable extends IRGeneratedVariable, IRAutomaticVariable, TIRTempVa
     result = "Temp: " + Construction::getTempVariableUniqueId(this)
   }
 
+  /**
+   * Gets the "tag" object that differentiates this temporary variable from other temporary
+   * variables generated for the same AST.
+   */
   final TempVariableTag getTag() { result = tag }
 
   override string getBaseString() { result = "#temp" }
@@ -253,6 +260,9 @@ class IRStringLiteral extends IRGeneratedVariable, TIRStringLiteral {
 
   final override string getBaseString() { result = "#string" }
 
+  /**
+   * Gets the AST of the string literal represented by this `IRStringLiteral`.
+   */
   final Language::StringLiteral getLiteral() { result = literal }
 }
 
@@ -270,6 +280,9 @@ class IRDynamicInitializationFlag extends IRGeneratedVariable, TIRDynamicInitial
 
   final override string toString() { result = var.toString() + "#init" }
 
+  /**
+   * Gets variable whose initialization is guarded by this flag.
+   */
   final Language::Variable getVariable() { result = var }
 
   final override string getUniqueId() {

cpp/ql/src/semmle/code/cpp/ir/implementation/raw/internal/TranslatedElement.qll

@@ -24,6 +24,16 @@ private Element getRealParent(Expr expr) {
   result.(Destructor).getADestruction() = expr
 }
 
+IRUserVariable getIRUserVariable(Function func, Variable var) {
+  result.getVariable() = var and
+  result.getEnclosingFunction() = func
+}
+
+IRTempVariable getIRTempVariable(Locatable ast, TempVariableTag tag) {
+  result.getAST() = ast and
+  result.getTag() = tag
+}
+
 /**
  * Holds if `expr` is a constant of a type that can be replaced directly with
  * its value in the IR. This does not include address constants as we have no

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

@@ -7,15 +7,11 @@ private import Imports::TTempVariableTag
 private import Imports::TIRVariable
 private import Imports::IRType
 
-IRUserVariable getIRUserVariable(Language::Function func, Language::Variable var) {
-  result.getVariable() = var and
-  result.getEnclosingFunction() = func
-}
-
 /**
- * A variable referenced by the IR for a function. The variable may be a user-declared variable
- * (`IRUserVariable`) or a temporary variable generated by the AST-to-IR translation
- * (`IRTempVariable`).
+ * A variable referenced by the IR for a function.
+ *
+ * The variable may be a user-declared variable (`IRUserVariable`) or a temporary variable generated
+ * by the AST-to-IR translation (`IRTempVariable`).
  */
 class IRVariable extends TIRVariable {
   Language::Function func;
@@ -27,6 +23,7 @@ class IRVariable extends TIRVariable {
     this = TIRDynamicInitializationFlag(func, _, _)
   }
 
+  /** Gets a textual representation of this element. */
   string toString() { none() }
 
   /**
@@ -162,20 +159,26 @@ class IRGeneratedVariable extends IRVariable {
 
   override string getUniqueId() { none() }
 
+  /**
+   * Gets a string containing the source code location of the AST that generated this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   final string getLocationString() {
     result =
       ast.getLocation().getStartLine().toString() + ":" +
         ast.getLocation().getStartColumn().toString()
   }
 
+  /**
+   * Gets the string that is combined with the location of the variable to generate the string
+   * representation of this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   string getBaseString() { none() }
 }
 
-IRTempVariable getIRTempVariable(Language::AST ast, TempVariableTag tag) {
-  result.getAST() = ast and
-  result.getTag() = tag
-}
-
 /**
  * A temporary variable introduced by IR construction. The most common examples are the variable
  * generated to hold the return value of a function, or the variable generated to hold the result of
@@ -190,6 +193,10 @@ class IRTempVariable extends IRGeneratedVariable, IRAutomaticVariable, TIRTempVa
     result = "Temp: " + Construction::getTempVariableUniqueId(this)
   }
 
+  /**
+   * Gets the "tag" object that differentiates this temporary variable from other temporary
+   * variables generated for the same AST.
+   */
   final TempVariableTag getTag() { result = tag }
 
   override string getBaseString() { result = "#temp" }
@@ -253,6 +260,9 @@ class IRStringLiteral extends IRGeneratedVariable, TIRStringLiteral {
 
   final override string getBaseString() { result = "#string" }
 
+  /**
+   * Gets the AST of the string literal represented by this `IRStringLiteral`.
+   */
   final Language::StringLiteral getLiteral() { result = literal }
 }
 
@@ -270,6 +280,9 @@ class IRDynamicInitializationFlag extends IRGeneratedVariable, TIRDynamicInitial
 
   final override string toString() { result = var.toString() + "#init" }
 
+  /**
+   * Gets variable whose initialization is guarded by this flag.
+   */
   final Language::Variable getVariable() { result = var }
 
   final override string getUniqueId() {

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

@@ -7,15 +7,11 @@ private import Imports::TTempVariableTag
 private import Imports::TIRVariable
 private import Imports::IRType
 
-IRUserVariable getIRUserVariable(Language::Function func, Language::Variable var) {
-  result.getVariable() = var and
-  result.getEnclosingFunction() = func
-}
-
 /**
- * A variable referenced by the IR for a function. The variable may be a user-declared variable
- * (`IRUserVariable`) or a temporary variable generated by the AST-to-IR translation
- * (`IRTempVariable`).
+ * A variable referenced by the IR for a function.
+ *
+ * The variable may be a user-declared variable (`IRUserVariable`) or a temporary variable generated
+ * by the AST-to-IR translation (`IRTempVariable`).
  */
 class IRVariable extends TIRVariable {
   Language::Function func;
@@ -27,6 +23,7 @@ class IRVariable extends TIRVariable {
     this = TIRDynamicInitializationFlag(func, _, _)
   }
 
+  /** Gets a textual representation of this element. */
   string toString() { none() }
 
   /**
@@ -162,20 +159,26 @@ class IRGeneratedVariable extends IRVariable {
 
   override string getUniqueId() { none() }
 
+  /**
+   * Gets a string containing the source code location of the AST that generated this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   final string getLocationString() {
     result =
       ast.getLocation().getStartLine().toString() + ":" +
         ast.getLocation().getStartColumn().toString()
   }
 
+  /**
+   * Gets the string that is combined with the location of the variable to generate the string
+   * representation of this variable.
+   *
+   * This is used by debugging and printing code only.
+   */
   string getBaseString() { none() }
 }
 
-IRTempVariable getIRTempVariable(Language::AST ast, TempVariableTag tag) {
-  result.getAST() = ast and
-  result.getTag() = tag
-}
-
 /**
  * A temporary variable introduced by IR construction. The most common examples are the variable
  * generated to hold the return value of a function, or the variable generated to hold the result of
@@ -190,6 +193,10 @@ class IRTempVariable extends IRGeneratedVariable, IRAutomaticVariable, TIRTempVa
     result = "Temp: " + Construction::getTempVariableUniqueId(this)
   }
 
+  /**
+   * Gets the "tag" object that differentiates this temporary variable from other temporary
+   * variables generated for the same AST.
+   */
   final TempVariableTag getTag() { result = tag }
 
   override string getBaseString() { result = "#temp" }
@@ -253,6 +260,9 @@ class IRStringLiteral extends IRGeneratedVariable, TIRStringLiteral {
 
   final override string getBaseString() { result = "#string" }
 
+  /**
+   * Gets the AST of the string literal represented by this `IRStringLiteral`.
+   */
   final Language::StringLiteral getLiteral() { result = literal }
 }
 
@@ -270,6 +280,9 @@ class IRDynamicInitializationFlag extends IRGeneratedVariable, TIRDynamicInitial
 
   final override string toString() { result = var.toString() + "#init" }
 
+  /**
+   * Gets variable whose initialization is guarded by this flag.
+   */
   final Language::Variable getVariable() { result = var }
 
   final override string getUniqueId() {

csharp/ql/src/experimental/ir/implementation/raw/internal/TranslatedElement.qll

@@ -21,6 +21,16 @@ ArrayType getArrayOfDim(int dim, Type type) {
   result.getElementType() = type
 }
 
+IRUserVariable getIRUserVariable(Language::Function func, Language::Variable var) {
+  result.getVariable() = var and
+  result.getEnclosingFunction() = func
+}
+
+IRTempVariable getIRTempVariable(Language::AST ast, TempVariableTag tag) {
+  result.getAST() = ast and
+  result.getTag() = tag
+}
+
 private predicate canCreateCompilerGeneratedElement(Element generatedBy, int nth) {
   generatedBy instanceof ForeachStmt and nth in [0 .. ForeachElements::noGeneratedElements() - 1]
   or