Swift: additional QLDoc around closures

Author: Robert Marsh

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

@@ -42,6 +42,8 @@ predicate isPropertyGetterElement(PropertyGetterElement pge, Accessor accessor,
 }
 
 predicate isNormalAutoClosureOrExplicitClosure(ClosureExpr clos) {
+  // short-circuiting operators have a `BinaryExpr` as the parent of the `AutoClosureExpr`,
+  // so we exclude them by checking for a `CallExpr`.
   clos instanceof AutoClosureExpr and
   exists(CallExpr call | call.getAnArgument().getExpr() = clos)
   or
@@ -201,6 +203,10 @@ class KeyPathElement extends ControlFlowElement, TKeyPathElement {
   override string toString() { result = expr.toString() }
 }
 
+/**
+ * A control flow element representing a closure in its role as a control flow
+ * scope.
+ */
 class ClosureElement extends ControlFlowElement, TClosureElement {
   ClosureExpr expr;
 

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

@@ -1148,6 +1148,10 @@ module Exprs {
     }
   }
 
+  /**
+   * The control flow for an explicit closure or a normal autoclosure in its
+   * role as a control flow scope.
+   */
   class ClosureExprTree extends StandardPreOrderTree, TClosureElement {
     ClosureExpr expr;
 

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

@@ -4,7 +4,8 @@ private import codeql.swift.elements.expr.Expr
 
 /**
  * A Swift autoclosure expression, that is, a closure automatically generated
- * around an argument when the parameter has the `@autoclosure` attribute. For
+ * around an argument when the parameter has the `@autoclosure` attribute or
+ * for the rtight-hand operand of short-circuiting logical operations. For
  * example, there is an `AutoClosureExpr` around the value `0` in:
  * ```
  * func myFunction(_ expr: @autoclosure () -> Int) {