Python: Address QL docs

python/ql/src/semmle/code/python/dataflow/DataFlow.qll

@@ -1,10 +1,26 @@
 /**
- * Provides classes for performing local (intra-procedural) and
- * global (inter-procedural) data flow analyses.
+ * Provides a library for local (intra-procedural) and global (inter-procedural)
+ * data flow analysis: deciding whether data can flow from a _source_ to a
+ * _sink_.
+ *
+ * Unless configured otherwise, _flow_ means that the exact value of
+ * the source may reach the sink. We do not track flow across pointer
+ * dereferences or array indexing. To track these types of flow, where the
+ * exact value may not be preserved, import
+ * `semmle.code.python.dataflow.TaintTracking`.
+ *
+ * To use global (interprocedural) data flow, extend the class
+ * `DataFlow::Configuration` as documented on that class. To use local
+ * (intraprocedural) data flow, call `DataFlow::localFlowStep*` with
+ *  arguments of type `DataFlow::Node`.
  */
 
 import python
 
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
 module DataFlow {
   import semmle.code.python.dataflow.internal.DataFlowImpl
 }

python/ql/src/semmle/code/python/dataflow/DataFlow2.qll

@@ -1,10 +1,26 @@
 /**
- * Provides classes for performing local (intra-procedural) and
- * global (inter-procedural) data flow analyses.
+ * Provides a library for local (intra-procedural) and global (inter-procedural)
+ * data flow analysis: deciding whether data can flow from a _source_ to a
+ * _sink_.
+ *
+ * Unless configured otherwise, _flow_ means that the exact value of
+ * the source may reach the sink. We do not track flow across pointer
+ * dereferences or array indexing. To track these types of flow, where the
+ * exact value may not be preserved, import
+ * `semmle.code.python.dataflow.TaintTracking`.
+ *
+ * To use global (interprocedural) data flow, extend the class
+ * `DataFlow::Configuration` as documented on that class. To use local
+ * (intraprocedural) data flow, call `DataFlow::localFlowStep*` with
+ *  arguments of type `DataFlow::Node`.
  */
 
 import python
 
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
 module DataFlow2 {
   import semmle.code.python.dataflow.internal.DataFlowImpl2
 }

python/ql/src/semmle/code/python/dataflow/TaintTracking.qll

@@ -1,10 +1,19 @@
 /**
  * Provides classes for performing local (intra-procedural) and
  * global (inter-procedural) taint-tracking analyses.
+ *
+ * To use global (interprocedural) taint tracking, extend the class
+ * `TaintTracking::Configuration` as documented on that class. To use local
+ * (intraprocedural) taint tracking, call `TaintTracking::localTaint` or
+ * `TaintTracking::localTaintStep` with arguments of type `DataFlow::Node`.
  */
 
 import python
 
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ */
 module TaintTracking {
   import semmle.code.python.dataflow.internal.tainttracking1.TaintTrackingImpl
 }

python/ql/src/semmle/code/python/dataflow/internal/DataFlowPrivate.qll

@@ -68,7 +68,10 @@ newtype TDataFlowType =
   TStringFlow()
 
 class DataFlowType extends TDataFlowType {
-  string toString() { none() }
+  /**
+   * No representation yet
+   */
+   string toString() { none() }
 }
 
 /** Gets a viable run-time target for the call `call`. */

python/ql/src/semmle/code/python/dataflow/internal/DataFlowPublic.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides Python-specific definitions for use in the data flow library.
+ */
+
 import python
 private import DataFlowPrivate
 

python/ql/src/semmle/code/python/dataflow/internal/TaintTrackingPublic.qll

@@ -1,12 +1,17 @@
-private import python
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ */
+
+ private import python
 private import TaintTrackingPrivate
 private import semmle.code.python.dataflow.DataFlow
 
-// /**
-//  * Holds if taint propagates from `source` to `sink` in zero or more local
-//  * (intra-procedural) steps.
-//  */
-// predicate localTaint(DataFlow::Node source, DataFlow::Node sink) { localTaintStep*(source, sink) }
+/**
+ * Holds if taint propagates from `source` to `sink` in zero or more local
+ * (intra-procedural) steps.
+ */
+predicate localTaint(DataFlow::Node source, DataFlow::Node sink) { localTaintStep*(source, sink) }
 
 // /**
 //  * Holds if taint can flow from `e1` to `e2` in zero or more
@@ -19,13 +24,13 @@ private import semmle.code.python.dataflow.DataFlow
 // /** A member (property or field) that is tainted if its containing object is tainted. */
 // abstract class TaintedMember extends AssignableMember { }
 
-// /**
-//  * Holds if taint propagates from `nodeFrom` to `nodeTo` in exactly one local
-//  * (intra-procedural) step.
-//  */
-// predicate localTaintStep(DataFlow::Node nodeFrom, DataFlow::Node nodeTo) {
-//   // Ordinary data flow
-//   DataFlow::localFlowStep(nodeFrom, nodeTo)
-//   or
-//   localAdditionalTaintStep(nodeFrom, nodeTo)
-// }
+/**
+ * Holds if taint propagates from `nodeFrom` to `nodeTo` in exactly one local
+ * (intra-procedural) step.
+ */
+predicate localTaintStep(DataFlow::Node nodeFrom, DataFlow::Node nodeTo) {
+  // Ordinary data flow
+  DataFlow::localFlowStep(nodeFrom, nodeTo)
+  or
+  localAdditionalTaintStep(nodeFrom, nodeTo)
+}