Add QLDoc

Author: owen-mc

go/extractor/dbscheme/tables.go

@@ -1102,7 +1102,7 @@ var UsesTable = NewTable("uses",
 // declare a new variable in the guard to the variable that is implicitly
 // declared at the beginning of the case clause to represent that variable
 // with the correct type
-var ImplicitVarDeclTable = NewTable("implicitvardecl",
+var ImplicitCaseVarDeclTable = NewTable("implicitcasevardecl",
 	EntityColumn(CaseClauseType, "caseclause"),
 	EntityColumn(ObjectType, "object"),
 )

go/extractor/extractor.go

@@ -862,7 +862,7 @@ func emitImplicitObjects(tw *trap.Writer, ts *ast.TypeSwitchStmt) {
 				log.Fatalf("getTypeLabel() called for implicit variable %s", obj.Name())
 				return trap.InvalidLabel
 			})
-			dbscheme.ImplicitVarDeclTable.Emit(tw, cclbl, objlbl)
+			dbscheme.ImplicitCaseVarDeclTable.Emit(tw, cclbl, objlbl)
 		}
 	}
 }

go/ql/lib/go.dbscheme

@@ -190,7 +190,7 @@ defs(int ident: @ident ref, int object: @object ref);
 
 uses(int ident: @ident ref, int object: @object ref);
 
-implicitvardecl(int caseclause: @caseclause ref, int object: @object ref);
+implicitcasevardecl(int caseclause: @caseclause ref, int object: @object ref);
 
 types(unique int id: @type, int kind: int ref);
 

go/ql/lib/semmle/go/Scopes.qll

@@ -122,9 +122,10 @@ class Entity extends @object {
   /**
    * Gets the declaring identifier for this entity, if any.
    *
-   * Note that type switch statements which define a new variable in the guard
+   * Note that type switch statements which declare a new variable in the guard
    * actually have a new variable (of the right type) implicitly declared at
-   * the beginning of each case clause, and these do not have a declaration.
+   * the beginning of each case clause, and these do not have a syntactic
+   * declaration.
    */
   Ident getDeclaration() { result.declares(this) }
 
@@ -137,6 +138,15 @@ class Entity extends @object {
   /** Gets a textual representation of this entity. */
   string toString() { result = this.getName() }
 
+  private predicate hasRealLocationInfo(
+    string filepath, int startline, int startcolumn, int endline, int endcolumn
+  ) {
+    // take the location of the declaration if there is one
+    this.getDeclaration().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn) or
+    any(CaseClause cc | this = cc.getImplicitlyDeclaredVariable())
+        .hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
+  }
+
   /**
    * Holds if this element is at the specified location.
    * The location spans column `startcolumn` of line `startline` to
@@ -147,23 +157,15 @@ class Entity extends @object {
   predicate hasLocationInfo(
     string filepath, int startline, int startcolumn, int endline, int endcolumn
   ) {
-    // take the location of the declaration if there is one
-    if exists(this.getDeclaration())
-    then this.getDeclaration().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
-    else
-      // take the location of the implicit declaration if there is one
-      if this = any(CaseClause cc).getImplicitlyDeclaredVariable()
-      then
-        any(CaseClause cc | this = cc.getImplicitlyDeclaredVariable())
-            .hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
-      else (
-        // otherwise fall back on dummy location
-        filepath = "" and
-        startline = 0 and
-        startcolumn = 0 and
-        endline = 0 and
-        endcolumn = 0
-      )
+    this.hasRealLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
+    or
+    // otherwise fall back on dummy location
+    not this.hasRealLocationInfo(_, _, _, _, _) and
+    filepath = "" and
+    startline = 0 and
+    startcolumn = 0 and
+    endline = 0 and
+    endcolumn = 0
   }
 }
 

go/ql/lib/semmle/go/Stmt.qll

@@ -777,7 +777,13 @@ class CaseClause extends @caseclause, Stmt, ScopeNode {
   /** Gets the number of statements of this `case` clause. */
   int getNumStmt() { result = this.getNumChildStmt() }
 
-  LocalVariable getImplicitlyDeclaredVariable() { implicitvardecl(this, result) }
+  /**
+   * Gets the implicitly declared variable for this `case` clause, if any.
+   *
+   * This exists for case clauses in type switch statements which declare a
+   * variable in the guard.
+   */
+  LocalVariable getImplicitlyDeclaredVariable() { implicitcasevardecl(this, result) }
 
   override predicate mayHaveSideEffects() {
     this.getAnExpr().mayHaveSideEffects() or

go/ql/lib/semmle/go/controlflow/ControlFlowGraphImpl.qll

@@ -311,9 +311,9 @@ newtype TControlFlowNode =
    * `cc` of type switch statement `ts`, and its assignment of the value from the guard.
    */
   MkTypeSwitchImplicitVariable(CaseClause cc, Expr switchExpr) {
-    exists(TypeSwitchStmt ts | ts.getAssign() instanceof DefineStmt |
+    exists(TypeSwitchStmt ts, DefineStmt ds | ds = ts.getAssign() |
       cc = ts.getACase() and
-      switchExpr = ts.getAssign().(DefineStmt).getRhs().(TypeAssertExpr).getExpr()
+      switchExpr = ds.getRhs().(TypeAssertExpr).getExpr()
     )
   } or
   /**

go/ql/lib/semmle/go/controlflow/IR.qll

@@ -1287,7 +1287,10 @@ module IR {
    * }
    * ```
    *
-   * The `y` inside the case clause is actually a local variable that is implicitly declared.
+   * The `y` inside the case clause is actually a local variable with type `Type1` that
+   * is implicitly declared at the top of the case clause. In case clauses which list
+   * more than one type and default clauses, the type of the implicitly declared variable
+   * is the same as the expression which is being switched on.
    */
   class TypeSwitchImplicitVariableInstruction extends Instruction, MkTypeSwitchImplicitVariable {
     CaseClause cc;
@@ -1302,7 +1305,7 @@ module IR {
 
     override ControlFlow::Root getRoot() { result.isRootOf(cc) }
 
-    override string toString() { result = "implicit variable declaration" }
+    override string toString() { result = "implicit type switch variable declaration" }
 
     override predicate hasLocationInfo(
       string filepath, int startline, int startcolumn, int endline, int endcolumn