Swift: More comments.

Author: MathiasVP

swift/ql/lib/codeql/swift/controlflow/internal/ControlFlowGraphImpl.qll

@@ -1349,17 +1349,21 @@ module Exprs {
     }
   }
 
+  /** Control-flow for a `TapExpr`. See the QLDoc for `TapExpr` for the semantics of a `TapExpr`. */
   private class TapExprTree extends AstStandardPostOrderTree {
     override TapExpr ast;
 
     final override ControlFlowElement getChildElement(int i) {
+      // We first visit the local variable declaration.
       i = 0 and
       result.asAstNode() = ast.getVar()
       or
+      // Then we visit the expression that gives the local variable its initial value.
       i = 1 and
       result.asAstNode() = ast.getSubExpr().getFullyConverted()
       or
-      // Note: The CFG for the body will skip the first element in the
+      // And finally, we visit the body that potentially mutates the local variable.
+      // Note that the CFG for the body will skip the first element in the
       // body because it's guarenteed to be the variable declaration
       // that we've already visited at i = 0. See the explanation
       // in `BraceStmtTree` for why this is necessary.

swift/ql/lib/codeql/swift/dataflow/internal/TaintTrackingPrivate.qll

@@ -20,6 +20,14 @@ private module Cached {
   cached
   predicate defaultAdditionalTaintStep(DataFlow::Node nodeFrom, DataFlow::Node nodeTo) {
     // Flow through one argument of `appendLiteral` and `appendInterpolation` and to the second argument.
+    // This is needed for string interpolation generated by the compiler. An interpolated string
+    // like `"I am \(n) years old."` is represented as
+    // ```
+    // $interpolated = ""
+    // appendLiteral(&$interpolated, "I am ")
+    // appendInterpolation(&$interpolated, n)
+    // appendLiteral(&$interpolated, " years old.")
+    // ```
     exists(ApplyExpr apply1, ApplyExpr apply2, ExprCfgNode e |
       nodeFrom.asExpr() = [apply1, apply2].getAnArgument().getExpr() and
       apply1.getFunction() = apply2 and

swift/ql/lib/codeql/swift/elements/expr/TapExpr.qll

@@ -1,4 +1,11 @@
-// generated by codegen/codegen.py, remove this comment if you wish to edit this file
 private import codeql.swift.generated.expr.TapExpr
 
+/**
+ * A `TapExpr` is an internal expression generated by the Swift compiler.
+ *
+ * If `e` is a `TapExpr`, the semantics of evaluating `e` is:
+ * 1. Create a local variable `e.getVar()` and assign it the value `e.getSubExpr()`.
+ * 2. Execute `e.getBody()` which potentially modifies the local variable.
+ * 3. Return the value of the local variable.
+ */
 class TapExpr extends TapExprBase { }