QL: Add some missing qldoc

asgerf · asgerf · commit b0801c9b2f44 · 2022-04-13T08:45:25.000+02:00
diff --git a/ql/ql/src/codeql_ql/dataflow/DataFlow.qll b/ql/ql/src/codeql_ql/dataflow/DataFlow.qll
@@ -1,3 +1,13 @@
+/**
+ * Experimental library for reasoning about data flow.
+ *
+ * Current limitations:
+ * - Global flow does not reason about subclassing, overriding, and dispatch
+ * - `this`, `result`, and local field variables are treated less precisely
+ *   than regular variables (see VarScoping.qll)
+ * - Polarity is not tracked, that is, global flow does not care about negation at all.
+ */
+
 private import codeql_ql.ast.Ast
 private import internal.NodesInternal
 private import internal.DataFlowNumbering
@@ -15,8 +25,10 @@ private import internal.GlobalFlow as GlobalFlow
  * To reason about global data flow, use `SuperNode.track()`.
  */
 class Node extends TNode {
+  /** Gets a string representation of this element. */
   string toString() { none() } // overridden in subclasses
 
+  /** Gets the location of element. */
   Location getLocation() { none() } // overridden in subclasses
 
   /**
@@ -158,8 +170,10 @@ class FieldNode extends Node, MkFieldNode {
   /** Gets the member predicate or charpred for which this node represents access to the field. */
   Predicate getPredicate() { result = pred }
 
+  /** Gets the declaration of the field. */
   FieldDecl getFieldDeclaration() { result = fieldDecl }
 
+  /** Gets the name of the field. */
   string getFieldName() { result = fieldDecl.getName() }
 
   override string toString() { result = "'" + this.getFieldName() + "' in " + pred.getName() }
diff --git a/ql/ql/src/codeql_ql/dataflow/internal/VarScoping.qll b/ql/ql/src/codeql_ql/dataflow/internal/VarScoping.qll
@@ -1,3 +1,15 @@
+/**
+ * Computes scopes in which it is safe to unify all uses of a given variable.
+ *
+ * It is not accurate to unify variables across a disjunction, so the scope of a variable
+ * is restricted to its nearest enclosing disjunction operand ("disjunct").
+ * At such a disjunct, we introduce a "refinement" of the variable, which is seen as a
+ * redefinition of the variable within that disjunct.
+ *
+ * In principle this should also be done for `this`, `result`, and local field variables
+ * but currently it is not.
+ */
+
 private import codeql_ql.ast.Ast
 private import codeql_ql.ast.internal.AstNodeNumbering
 
