Merge pull request #4597 from yoff/python-fix-ql-doc

Python: Fix ql doc

Author: tausbn

python/ql/src/semmle/python/dataflow/new/RemoteFlowSources.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides an extension point for for modeling user-controlled data.
+ * Such data is often used as data-flow sources in security queries.
+ */
+
 private import python
 private import semmle.python.dataflow.new.DataFlow
 // Need to import since frameworks can extend `RemoteFlowSource::Range`

python/ql/src/semmle/python/dataflow/new/TypeTracker.qll

@@ -44,12 +44,24 @@ class StepSummary extends TStepSummary {
   }
 }
 
+/** Provides predicates for updating step summaries (`StepSummary`s). */
 module StepSummary {
+  /**
+   * Gets the summary that corresponds to having taken a forwards
+   * heap and/or inter-procedural step from `nodeFrom` to `nodeTo`.
+   */
   cached
   predicate step(Node nodeFrom, Node nodeTo, StepSummary summary) {
     exists(Node mid | typePreservingStep*(nodeFrom, mid) and smallstep(mid, nodeTo, summary))
   }
 
+  /**
+   * Gets the summary that corresponds to having taken a forwards
+   * local, heap and/or inter-procedural step from `nodeFrom` to `nodeTo`.
+   *
+   * Unlike `StepSummary::step`, this predicate does not compress
+   * type-preserving steps.
+   */
   predicate smallstep(Node nodeFrom, Node nodeTo, StepSummary summary) {
     typePreservingStep(nodeFrom, nodeTo) and
     summary = LevelStep()
@@ -291,6 +303,7 @@ class TypeTracker extends TTypeTracker {
   }
 }
 
+/** Provides predicates for implementing custom `TypeTracker`s. */
 module TypeTracker {
   /**
    * Gets a valid end point of type tracking.

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

@@ -118,11 +118,13 @@ class Node extends TNode {
   Node track(TypeTracker t2, TypeTracker t) { t = t2.step(this, result) }
 }
 
+/** A data-flow node corresponding to an SSA variable. */
 class EssaNode extends Node, TEssaNode {
   EssaVariable var;
 
   EssaNode() { this = TEssaNode(var) }
 
+  /** Gets the `EssaVariable` represented by this data-flow node. */
   EssaVariable getVar() { result = var }
 
   override EssaVariable asVar() { result = var }
@@ -135,11 +137,13 @@ class EssaNode extends Node, TEssaNode {
   override Location getLocation() { result = var.getDefinition().getLocation() }
 }
 
+/** A data-flow node corresponding to a control-flow node. */
 class CfgNode extends Node, TCfgNode {
   ControlFlowNode node;
 
   CfgNode() { this = TCfgNode(node) }
 
+  /** Gets the `ControlFlowNode` represented by this data-flow node. */
   ControlFlowNode getNode() { result = node }
 
   override ControlFlowNode asCfgNode() { result = node }
@@ -352,39 +356,48 @@ class BarrierGuard extends GuardNode {
 }
 
 /**
- * A reference contained in an object. This is either a field or a property.
+ * Algebraic datatype for tracking data content associated with values.
+ * Content can be collection elements or object attributes.
  */
 newtype TContent =
   /** An element of a list. */
   TListElementContent() or
   /** An element of a set. */
   TSetElementContent() or
-  /** An element of a tuple at a specifik index. */
+  /** An element of a tuple at a specific index. */
   TTupleElementContent(int index) { exists(any(TupleNode tn).getElement(index)) } or
   /** An element of a dictionary under a specific key. */
   TDictionaryElementContent(string key) {
     key = any(KeyValuePair kvp).getKey().(StrConst).getS()
     or
     key = any(Keyword kw).getArg()
   } or
-  /** An element of a dictionary at any key. */
+  /** An element of a dictionary under any key. */
   TDictionaryElementAnyContent() or
   /** An object attribute. */
   TAttributeContent(string attr) { attr = any(Attribute a).getName() }
 
+/**
+ * A data-flow value can have associated content.
+ * If the value is a collection, it can have elements,
+ * if it is an object, it can have attribute values.
+ */
 class Content extends TContent {
   /** Gets a textual representation of this element. */
   string toString() { result = "Content" }
 }
 
+/** An element of a list. */
 class ListElementContent extends TListElementContent, Content {
   override string toString() { result = "List element" }
 }
 
+/** An element of a set. */
 class SetElementContent extends TSetElementContent, Content {
   override string toString() { result = "Set element" }
 }
 
+/** An element of a tuple at a specific index. */
 class TupleElementContent extends TTupleElementContent, Content {
   int index;
 
@@ -396,6 +409,7 @@ class TupleElementContent extends TTupleElementContent, Content {
   override string toString() { result = "Tuple element at index " + index.toString() }
 }
 
+/** An element of a dictionary under a specific key. */
 class DictionaryElementContent extends TDictionaryElementContent, Content {
   string key;
 
@@ -407,10 +421,12 @@ class DictionaryElementContent extends TDictionaryElementContent, Content {
   override string toString() { result = "Dictionary element at key " + key }
 }
 
+/** An element of a dictionary under any key. */
 class DictionaryElementAnyContent extends TDictionaryElementAnyContent, Content {
   override string toString() { result = "Any dictionary element" }
 }
 
+/** An object attribute. */
 class AttributeContent extends TAttributeContent, Content {
   private string attr;
 

python/ql/src/semmle/python/frameworks/MySQLdb.qll

@@ -32,6 +32,7 @@ module MySQLdb {
   /** Gets a reference to the `MySQLdb` module. */
   DataFlow::Node moduleMySQLdb() { result = moduleMySQLdb(DataFlow::TypeTracker::end()) }
 
+  /** MySQLdb implements PEP 249, providing ways to execute SQL statements against a database. */
   class MySQLdb extends PEP249Module {
     MySQLdb() { this = moduleMySQLdb() }
   }

python/ql/src/semmle/python/frameworks/Werkzeug.qll

@@ -6,6 +6,12 @@ private import python
 private import semmle.python.dataflow.new.DataFlow
 private import semmle.python.dataflow.new.TaintTracking
 
+/**
+ * Provides models for the `Werkzeug` PyPI package.
+ * See
+ * - https://pypi.org/project/Werkzeug/
+ * - https://werkzeug.palletsprojects.com/en/1.0.x/#werkzeug
+ */
 module Werkzeug {
   /** Provides models for the `werkzeug` module. */
   module werkzeug {