C++: Miscellaneous IR QLDoc

Author: Dave Bartolomeo

cpp/ql/src/semmle/code/cpp/ir/IRConfiguration.qll

@@ -1 +1,5 @@
+/**
+ * Module used to configure the IR generation process.
+ */
+
 import implementation.IRConfiguration

cpp/ql/src/semmle/code/cpp/ir/PrintIR.qll

@@ -1 +1,11 @@
+/**
+ * Outputs a representation of the IR as a control flow graph.
+ *
+ * This file contains the actual implementation of `PrintIR.ql`. For test cases and very small
+ * databases, `PrintIR.ql` can be run directly to dump the IR for the entire database. For most
+ * uses, however, it is better to write a query that imports `PrintIR.qll`, extends
+ * `PrintIRConfiguration`, and overrides `shouldPrintFunction()` to select a subset of functions to
+ * dump.
+ */
+
 import implementation.aliased_ssa.PrintIR

cpp/ql/src/semmle/code/cpp/ir/implementation/IRType.qll

@@ -32,6 +32,7 @@ private newtype TIRType =
  * all pointer types map to the same instance of `IRAddressType`.
  */
 class IRType extends TIRType {
+  /** Gets a textual representation of this type. */
   string toString() { none() }
 
   /**

cpp/ql/src/semmle/code/cpp/ir/implementation/MemoryAccessKind.qll

@@ -1,3 +1,9 @@
+/**
+ * Provides classes that describe how a particular `Instruction` or its operands access memory.
+ */
+
+private import IRConfiguration
+
 private newtype TMemoryAccessKind =
   TIndirectMemoryAccess() or
   TBufferMemoryAccess() or
@@ -14,6 +20,7 @@ private newtype TMemoryAccessKind =
  * memory result.
  */
 class MemoryAccessKind extends TMemoryAccessKind {
+  /** Gets a textual representation of this access kind. */
   string toString() { none() }
 
   /**

cpp/ql/src/semmle/code/cpp/ir/implementation/Opcode.qll

@@ -91,6 +91,9 @@ private newtype TOpcode =
   TUnreached() or
   TNewObj()
 
+/**
+ * An opcode that specifies the operation performed by an `Instruction`.
+ */
 class Opcode extends TOpcode {
   /** Gets a textual representation of this element. */
   string toString() { result = "UnknownOpcode" }

cpp/ql/src/semmle/code/cpp/ir/implementation/TempVariableTag.qll

@@ -12,5 +12,6 @@ private import Imports::TempVariableTag
  * computed on each branch. The set of possible `TempVariableTag`s is language-dependent.
  */
 class TempVariableTag extends TTempVariableTag {
+  /** Gets a textual representation of this tag. */
   string toString() { result = getTempVariableTagId(this) }
 }

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

@@ -20,6 +20,7 @@ private import Cached
  * Most consumers should use the class `IRBlock`.
  */
 class IRBlockBase extends TIRBlock {
+  /** Gets a textual representation of this block. */
   final string toString() { result = getFirstInstruction(this).toString() }
 
   /** Gets the source location of the first non-`Phi` instruction in this block. */
@@ -282,4 +283,4 @@ private module Cached {
     idominance(isEntryBlock/1, blockSuccessor/2)(_, dominator, block)
 }
 
-Instruction getFirstInstruction(TIRBlock block) { block = MkIRBlock(result) }
+private Instruction getFirstInstruction(TIRBlock block) { block = MkIRBlock(result) }

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes that represent variables accessed by the IR.
+ */
+
 private import internal.IRInternal
 import IRFunction
 private import internal.IRVariableImports as Imports

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

@@ -1,9 +1,9 @@
 /**
  * Outputs a representation of the IR as a control flow graph.
  *
- * This file contains the actual implementation of `PrintAST.ql`. For test cases and very small
- * databases, `PrintAST.ql` can be run directly to dump the IR for the entire database. For most
- * uses, however, it is better to write a query that imports `PrintAST.qll`, extends
+ * This file contains the actual implementation of `PrintIR.ql`. For test cases and very small
+ * databases, `PrintIR.ql` can be run directly to dump the IR for the entire database. For most
+ * uses, however, it is better to write a query that imports `PrintIR.qll`, extends
  * `PrintIRConfiguration`, and overrides `shouldPrintFunction()` to select a subset of functions to
  * dump.
  */
@@ -19,6 +19,7 @@ private newtype TPrintIRConfiguration = MkPrintIRConfiguration()
  * The query can extend this class to control which functions are printed.
  */
 class PrintIRConfiguration extends TPrintIRConfiguration {
+  /** Gets a textual representation of this configuration. */
   string toString() { result = "PrintIRConfiguration" }
 
   /**

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

@@ -20,6 +20,7 @@ private import Cached
  * Most consumers should use the class `IRBlock`.
  */
 class IRBlockBase extends TIRBlock {
+  /** Gets a textual representation of this block. */
   final string toString() { result = getFirstInstruction(this).toString() }
 
   /** Gets the source location of the first non-`Phi` instruction in this block. */
@@ -282,4 +283,4 @@ private module Cached {
     idominance(isEntryBlock/1, blockSuccessor/2)(_, dominator, block)
 }
 
-Instruction getFirstInstruction(TIRBlock block) { block = MkIRBlock(result) }
+private Instruction getFirstInstruction(TIRBlock block) { block = MkIRBlock(result) }