Python: Add comments

Author: yoff

python/ql/lib/semmle/python/frameworks/Asyncpg.qll

@@ -10,16 +10,23 @@ private import semmle.python.ApiGraphs
 
 /** Provides models for the `asyncpg` PyPI package. */
 private module Asyncpg {
+  /** A `ConectionPool` is created when the result of `asyncpg.create_pool()` is awaited. */
   API::Node connectionPool() {
     result = API::moduleImport("asyncpg").getMember("create_pool").getReturn().getAwaited()
   }
 
+  /**
+   * A `Connection` is created when
+   * - the result of `asyncpg.connect()` is awaited.
+   * - the result of calling `aquire` on a c=`ConnectionPool` is awaited.
+   */
   API::Node connection() {
     result = API::moduleImport("asyncpg").getMember("connect").getReturn().getAwaited()
     or
     result = connectionPool().getMember("acquire").getReturn().getAwaited()
   }
 
+  /** Reverse lookup of the query argument name for a query method. */
   private string queryMethodName(string queryArg) {
     result in ["copy_from_query", "execute", "fetch", "fetchrow", "fetchval"] and
     queryArg = "query"
@@ -28,6 +35,7 @@ private module Asyncpg {
     queryArg = "command"
   }
 
+  /** `Connection`s and `ConnectionPool`s provide some methods that execute SQL. */
   class SqlExecutionOnConnection extends SqlExecution::Range, DataFlow::MethodCallNode {
     string queryArg;
 
@@ -38,6 +46,7 @@ private module Asyncpg {
     override DataFlow::Node getSql() { result in [this.getArg(0), this.getArgByName(queryArg)] }
   }
 
+  /** Reverse lokup of the path argument name for a method accessing the file system. */
   private string fileAccessMethodName(string pathArg) {
     result in ["copy_from_query", "copy_from_table"] and
     pathArg = "output"
@@ -46,18 +55,20 @@ private module Asyncpg {
     pathArg = "source"
   }
 
+  /** `Connection`s and `ConnectionPool`s provide some methods that access the file system. */
   class FileAccessOnConnection extends FileSystemAccess::Range, DataFlow::MethodCallNode {
     string pathArg;
 
     FileAccessOnConnection() {
       this.calls([connectionPool().getAUse(), connection().getAUse()], fileAccessMethodName(pathArg))
     }
 
+    // The path argument is keyword only.
     override DataFlow::Node getAPathArgument() { result in [this.getArgByName(pathArg)] }
   }
 
   /**
-   * Holds if `result` is the result of awaiting `n`.
+   * Holds if `result` is the result of awaiting `awaitedValue`.
    */
   pragma[inline]
   DataFlow::Node awaited(DataFlow::Node awaitedValue) {
@@ -88,6 +99,15 @@ private module Asyncpg {
     )
   }
 
+  /**
+   * Provides models of the `PreparedStatement` class in `asyncpg`.
+   * `PreparedStatement`s are created when the result of calling `prepare(query)` on a connection is awaited.
+   * The result of calling `prepare(query)` is a `PreparedStatementFactory` and the argument, `query` needs to
+   * be tracked to the place where a `PreparedStatement` is created and then futher to any executing methods.
+   * Hence the two type trackers.
+   *
+   * TODO: Rewrite this, once we have `API::CallNode` available.
+   */
   module PreparedStatement {
     private DataFlow::TypeTrackingNode preparedStatementFactory(
       DataFlow::TypeTracker t, DataFlow::Node sql
@@ -128,6 +148,17 @@ private module Asyncpg {
     }
   }
 
+  /**
+   * Provides models of the `Cursor` class in `asyncpg`.
+   * `Cursor`s are created
+   * - when the result of calling `cursor(query)` on a connection is awaited.
+   * - when the result of calling `cursor()` on a prepared statement is awaited.
+   * The result of calling `cursor` in either case is a `CursorFactory` and the argument, `query` needs to
+   * be tracked to the place where a `Cursor` is created, hence the type tracker.
+   * The creation of the `Cursor` executes the query.
+   *
+   * TODO: Rewrite this, once we have `API::CallNode` available.
+   */
   module Cursor {
     private DataFlow::TypeTrackingNode cursorFactory(DataFlow::TypeTracker t, DataFlow::Node sql) {
       // cursor created from connection
@@ -149,6 +180,7 @@ private module Asyncpg {
       cursorFactory(DataFlow::TypeTracker::end(), sql).flowsTo(result)
     }
 
+    /** The creation of a `Cursor` executes the associated query. */
     class CursorCreation extends SqlExecution::Range {
       DataFlow::Node sql;