Python: Fix a bunch of class QLDoc

python/ql/lib/semmle/python/AstExtended.qll

@@ -1,6 +1,6 @@
 import python
 
-/** Syntactic node (Class, Function, Module, Expr, Stmt or Comprehension) corresponding to a flow node */
+/** A syntactic node (Class, Function, Module, Expr, Stmt or Comprehension) corresponding to a flow node */
 abstract class AstNode extends AstNode_ {
   /*
    * Special comment for documentation generation.
@@ -61,31 +61,31 @@ abstract class AstNode extends AstNode_ {
 }
 
 /* Parents */
-/** Internal implementation class */
+/** The parent of a `Function`. Internal implementation class */
 class FunctionParent extends FunctionParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `Arguments` node. Internal implementation class */
 class ArgumentsParent extends ArgumentsParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `ExprList`. Internal implementation class */
 class ExprListParent extends ExprListParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `ExprContext`. Internal implementation class */
 class ExprContextParent extends ExprContextParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `StmtList`. Internal implementation class */
 class StmtListParent extends StmtListParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `StrList`. Internal implementation class */
 class StrListParent extends StrListParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `Expr`. Internal implementation class */
 class ExprParent extends ExprParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `PatternList`. Internal implementation class */
 class PatternListParent extends PatternListParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `Pattern`. Internal implementation class */
 class PatternParent extends PatternParent_ { }
 
 class DictItem extends DictItem_, AstNode {
@@ -120,7 +120,7 @@ class Comprehension extends Comprehension_, AstNode {
 class BytesOrStr extends BytesOrStr_ { }
 
 /**
- * Part of a string literal formed by implicit concatenation.
+ * A part of a string literal formed by implicit concatenation.
  * For example the string literal "abc" expressed in the source as `"a" "b" "c"`
  * would be composed of three `StringPart`s.
  */

python/ql/lib/semmle/python/Comprehensions.qll

@@ -1,6 +1,6 @@
 import python
 
-/** Base class for list, set and dictionary comprehensions, and generator expressions. */
+/** The base class for list, set and dictionary comprehensions, and generator expressions. */
 abstract class Comp extends Expr {
   abstract Function getFunction();
 

python/ql/lib/semmle/python/Exprs.qll

@@ -315,7 +315,7 @@ class Ellipsis extends Ellipsis_ {
 }
 
 /**
- * Immutable literal expressions (except tuples).
+ * An immutable literal expression (except tuples).
  * Consists of string (both unicode and byte) literals and numeric literals.
  */
 abstract class ImmutableLiteral extends Expr {
@@ -687,7 +687,7 @@ class False extends BooleanLiteral {
   override boolean booleanValue() { result = false }
 }
 
-/** `None` */
+/** The `None` constant. */
 class None extends NameConstant {
   /* syntax: None */
   None() { name_consts(this, "None") }
@@ -730,20 +730,20 @@ class Guard extends Guard_ {
 /** A context in which an expression used */
 class ExprContext extends ExprContext_ { }
 
-/** Load context, the context of var in len(var) */
+/** The load context, the context of var in len(var) */
 class Load extends Load_ { }
 
-/** Store context, the context of var in var = 0 */
+/** The store context, the context of var in var = 0 */
 class Store extends Store_ { }
 
-/** Delete context, the context of var in del var */
+/** The delete context, the context of var in del var */
 class Del extends Del_ { }
 
-/** This is an artifact of the Python grammar which includes an AugLoad context, even though it is never used. */
+/** The context of an augmented load. This is an artifact of the Python grammar which includes an AugLoad context, even though it is never used. */
 class AugLoad extends AugLoad_ { }
 
-/** Augmented store context, the context of var in var += 1 */
+/** The augmented store context, the context of var in var += 1 */
 class AugStore extends AugStore_ { }
 
-/** Parameter context, the context of var in def f(var): pass */
+/** The parameter context, the context of var in def f(var): pass */
 class Param extends Param_ { }

python/ql/lib/semmle/python/Operations.qll

@@ -1,6 +1,6 @@
 import python
 
-/** Base class for operators */
+/** The base class for operators */
 class Operator extends Operator_ {
   /** Gets the name of the special method used to implement this operator */
   string getSpecialMethodName() { none() }
@@ -131,7 +131,7 @@ class Compare extends Compare_ {
   }
 }
 
-/** List of comparison operators in a comparison */
+/** A list of comparison operators in a comparison */
 class CmpopList extends CmpopList_ { }
 
 /** A comparison operator */

python/ql/lib/semmle/python/SelfAttribute.qll

@@ -31,7 +31,7 @@ private predicate self_attribute(Attribute attr, Class cls) {
   )
 }
 
-/** Helper class for UndefinedClassAttribute.ql & MaybeUndefinedClassAttribute.ql */
+/** A helper class for UndefinedClassAttribute.ql & MaybeUndefinedClassAttribute.ql */
 class SelfAttributeRead extends SelfAttribute {
   SelfAttributeRead() {
     this.getCtx() instanceof Load and

python/ql/lib/semmle/python/dataflow/new/SensitiveDataSources.qll

@@ -227,7 +227,7 @@ private module SensitiveDataModeling {
   }
 
   /**
-   * Any kind of variable assignment (also including with/for) where the name indicates
+   * A variable assignment (also including with/for) where the name indicates
    * it contains sensitive data.
    *
    * Note: We _could_ make any access to a variable with a sensitive name a source of

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

@@ -6,14 +6,14 @@
 private import python
 private import internal.TypeTracker as Internal
 
-/** Any string that may appear as the name of an attribute or access path. */
+/** A string that may appear as the name of an attribute or access path. */
 class AttributeName = Internal::ContentName;
 
-/** Either an attribute name, or the empty string (representing no attribute). */
+/** An attribute name, or the empty string (representing no attribute). */
 class OptionalAttributeName = Internal::OptionalContentName;
 
 /**
- * Summary of the steps needed to track a value to a given dataflow node.
+ * The summary of the steps needed to track a value to a given dataflow node.
  *
  * This can be used to track objects that implement a certain API in order to
  * recognize calls to that API. Note that type-tracking does not by itself provide a

python/ql/lib/semmle/python/dataflow/new/internal/DataFlowPrivate.qll

@@ -613,7 +613,7 @@ newtype TDataFlowCallable =
   TLambda(Function lambda) { lambda.isLambda() } or
   TModule(Module m)
 
-/** Represents a callable. */
+/** A callable. */
 abstract class DataFlowCallable extends TDataFlowCallable {
   /** Gets a textual representation of this element. */
   abstract string toString();
@@ -714,7 +714,7 @@ newtype TDataFlowCall =
   TClassCall(CallNode call) { call = any(ClassValue c | not c.isAbsent()).getACall() } or
   TSpecialCall(SpecialMethodCallNode special)
 
-/** Represents a call. */
+/** A call. */
 abstract class DataFlowCall extends TDataFlowCall {
   /** Gets a textual representation of this element. */
   abstract string toString();
@@ -739,7 +739,7 @@ abstract class DataFlowCall extends TDataFlowCall {
 }
 
 /**
- * Represents a call to a function/lambda.
+ * A call to a function/lambda.
  * This excludes calls to bound methods, classes, and special methods.
  * Bound method calls and class calls insert an argument for the explicit
  * `self` parameter, and special method calls have special argument passing.
@@ -826,7 +826,7 @@ class ClassCall extends DataFlowCall, TClassCall {
   override DataFlowCallable getEnclosingCallable() { result.getScope() = call.getScope() }
 }
 
-/** Represents a call to a special method. */
+/** A call to a special method. */
 class SpecialCall extends DataFlowCall, TSpecialCall {
   SpecialMethodCallNode special;
 

python/ql/lib/semmle/python/dataflow/old/Implementation.qll

@@ -79,7 +79,7 @@ abstract class AttributePath extends TAttributePath {
   predicate noAttribute() { this = TNoAttribute() }
 }
 
-/** AttributePath for no attribute. */
+/** The `AttributePath` for no attribute. */
 class NoAttribute extends TNoAttribute, AttributePath {
   override string toString() { result = "no attribute" }
 
@@ -88,7 +88,7 @@ class NoAttribute extends TNoAttribute, AttributePath {
   override AttributePath fromAttribute(string name) { none() }
 }
 
-/** AttributePath for an attribute. */
+/** The `AttributePath` for an attribute. */
 class NamedAttributePath extends TAttribute, AttributePath {
   override string toString() {
     exists(string attr |
@@ -124,7 +124,7 @@ newtype TTaintTrackingNode =
   }
 
 /**
- * Class representing the (node, context, path, kind) tuple.
+ * A class representing the (node, context, path, kind) tuple.
  * Used for context-sensitive path-aware taint-tracking.
  */
 class TaintTrackingNode extends TTaintTrackingNode {

python/ql/lib/semmle/python/dataflow/old/TaintTracking.qll

@@ -180,7 +180,7 @@ abstract class TaintKind extends string {
 }
 
 /**
- * Alias of `TaintKind`, so the two types can be used interchangeably.
+ * An Alias of `TaintKind`, so the two types can be used interchangeably.
  */
 class FlowLabel = TaintKind;
 
@@ -561,7 +561,7 @@ module DataFlowExtension {
     ControlFlowNode getACalleeSuccessorNode(CallNode call) { none() }
   }
 
-  /** Data flow variable that modifies the basic data-flow. */
+  /** A data flow variable that modifies the basic data-flow. */
   class DataFlowVariable extends EssaVariable {
     /**
      * Gets a successor node for data-flow.
@@ -608,7 +608,7 @@ private import semmle.python.pointsto.PointsTo
  */
 module DataFlow {
   /**
-   * Generic taint kind, source and sink classes for convenience and
+   * The generic taint kind, source and sink classes for convenience and
    * compatibility with other language libraries
    */
   class Extension = DataFlowExtension::DataFlowNode;

python/ql/lib/semmle/python/essa/Essa.qll

@@ -134,7 +134,7 @@ private newtype TEssaDefinition =
   TPhiFunction(SsaSourceVariable v, BasicBlock b) { EssaDefinitions::phiNode(v, b) }
 
 /**
- * Definition of an extended-SSA (ESSA) variable.
+ * A definition of an extended-SSA (ESSA) variable.
  * There is exactly one definition for each variable,
  * and exactly one variable for each definition.
  */
@@ -515,7 +515,7 @@ class AssignmentDefinition extends EssaNodeDefinition {
   override string getAPrimaryQlClass() { result = "AssignmentDefinition" }
 }
 
-/** Capture of a raised exception `except ExceptionType ex:` */
+/** A capture of a raised exception `except ExceptionType ex:` */
 class ExceptionCapture extends EssaNodeDefinition {
   ExceptionCapture() {
     SsaSource::exception_capture(this.getSourceVariable(), this.getDefiningNode())
@@ -631,7 +631,7 @@ class DeletionDefinition extends EssaNodeDefinition {
 }
 
 /**
- * Definition of variable at the entry of a scope. Usually this represents the transfer of
+ * A definition of variable at the entry of a scope. Usually this represents the transfer of
  * a global or non-local variable from one scope to another.
  */
 class ScopeEntryDefinition extends EssaNodeDefinition {
@@ -645,7 +645,7 @@ class ScopeEntryDefinition extends EssaNodeDefinition {
   override string getAPrimaryQlClass() { result = "ScopeEntryDefinition" }
 }
 
-/** Possible redefinition of variable via `from ... import *` */
+/** A possible redefinition of variable via `from ... import *` */
 class ImportStarRefinement extends EssaNodeRefinement {
   ImportStarRefinement() {
     SsaSource::import_star_refinement(this.getSourceVariable(), _, this.getDefiningNode())
@@ -654,7 +654,7 @@ class ImportStarRefinement extends EssaNodeRefinement {
   override string getAPrimaryQlClass() { result = "ImportStarRefinement" }
 }
 
-/** Assignment of an attribute `obj.attr = val` */
+/** An assignment of an attribute `obj.attr = val` */
 class AttributeAssignment extends EssaNodeRefinement {
   AttributeAssignment() {
     SsaSource::attribute_assignment_refinement(this.getSourceVariable(), _, this.getDefiningNode())
@@ -693,7 +693,7 @@ class ArgumentRefinement extends EssaNodeRefinement {
   override string getAPrimaryQlClass() { result = "ArgumentRefinement" }
 }
 
-/** Deletion of an attribute `del obj.attr`. */
+/** A deletion of an attribute `del obj.attr`. */
 class EssaAttributeDeletion extends EssaNodeRefinement {
   EssaAttributeDeletion() {
     SsaSource::attribute_deletion_refinement(this.getSourceVariable(), _, this.getDefiningNode())
@@ -734,7 +734,7 @@ class SingleSuccessorGuard extends EssaNodeRefinement {
 }
 
 /**
- * Implicit definition of the names of sub-modules in a package.
+ * An implicit definition of the names of sub-modules in a package.
  * Although the interpreter does not pre-define these names, merely populating them
  * as they are imported, this is a good approximation for static analysis.
  */
@@ -784,7 +784,7 @@ class SelfCallsiteRefinement extends MethodCallsiteRefinement {
   override string getAPrimaryQlClass() { result = "SelfCallsiteRefinement" }
 }
 
-/** Python specific sub-class of generic EssaEdgeRefinement */
+/** A Python specific sub-class of generic EssaEdgeRefinement */
 class PyEdgeRefinement extends EssaEdgeRefinement {
   override string getRepresentation() {
     /*

python/ql/lib/semmle/python/filters/GeneratedCode.qll

@@ -112,7 +112,7 @@ abstract class SpecificGeneratedFile extends GeneratedFile {
 
   }
 
-/** File generated by the spitfire templating engine */
+/** A file generated by the spitfire templating engine */
 class SpitfireGeneratedFile extends SpecificGeneratedFile {
   SpitfireGeneratedFile() {
     exists(Module m | m.getFile() = this and not m instanceof SpitfireTemplate |
@@ -127,14 +127,14 @@ class SpitfireGeneratedFile extends SpecificGeneratedFile {
   override string getTool() { result = "spitfire" }
 }
 
-/** File generated by the pyxl templating engine */
+/** A file generated by the pyxl templating engine */
 class PyxlGeneratedFile extends SpecificGeneratedFile {
   PyxlGeneratedFile() { this.getSpecifiedEncoding() = "pyxl" }
 
   override string getTool() { result = "pyxl" }
 }
 
-/** File generated by the mako templating engine */
+/** A file generated by the mako templating engine */
 class MakoGeneratedFile extends SpecificGeneratedFile {
   MakoGeneratedFile() {
     exists(Module m | m.getFile() = this |
@@ -166,7 +166,7 @@ string from_mako_import(Module m) {
   )
 }
 
-/** File generated by Google's protobuf tool. */
+/** A file generated by Google's protobuf tool. */
 class ProtobufGeneratedFile extends SpecificGeneratedFile {
   ProtobufGeneratedFile() {
     this.getAbsolutePath().regexpMatch(".*_pb2?.py") and

python/ql/lib/semmle/python/filters/Tests.qll

@@ -15,7 +15,7 @@ class UnitTestClass extends TestScope {
 
 abstract class Test extends TestScope { }
 
-/** Class of test function that uses the `unittest` framework */
+/** A test function that uses the `unittest` framework */
 class UnitTestFunction extends Test {
   UnitTestFunction() {
     this.getScope+() instanceof UnitTestClass and
@@ -37,7 +37,7 @@ class NoseTestFunction extends Test {
   }
 }
 
-/** Class of functions that are clearly tests, but don't belong to a specific framework */
+/** A function that is clearly a test, but doesn't belong to a specific framework */
 class UnknownTestFunction extends Test {
   UnknownTestFunction() {
     this.(Function).getName().matches("test%") and

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

@@ -47,7 +47,7 @@ private module Aiomysql {
   }
 
   /**
-   * Calling `execute` on a `Cursor` constructs a query.
+   * A query. Calling `execute` on a `Cursor` constructs a query.
    * See https://aiomysql.readthedocs.io/en/stable/cursors.html#Cursor.execute
    */
   class CursorExecuteCall extends SqlConstruction::Range, DataFlow::CallCfgNode {
@@ -73,7 +73,7 @@ private module Aiomysql {
   }
 
   /**
-   * Awaiting the result of calling `execute` executes the query.
+   * An awaited query. Awaiting the result of calling `execute` executes the query.
    * See https://aiomysql.readthedocs.io/en/stable/cursors.html#Cursor.execute
    */
   class AwaitedCursorExecuteCall extends SqlExecution::Range {
@@ -104,7 +104,7 @@ private module Aiomysql {
   API::Node saConnection() { result = engine().getMember("acquire").getReturn().getAwaited() }
 
   /**
-   * Calling `execute` on a `SAConnection` constructs a query.
+   * A query. Calling `execute` on a `SAConnection` constructs a query.
    * See https://aiomysql.readthedocs.io/en/stable/sa.html#aiomysql.sa.SAConnection.execute
    */
   class SAConnectionExecuteCall extends SqlConstruction::Range, DataFlow::CallCfgNode {
@@ -132,7 +132,7 @@ private module Aiomysql {
   }
 
   /**
-   * Awaiting the result of calling `execute` executes the query.
+   * An awaited query. Awaiting the result of calling `execute` executes the query.
    * See https://aiomysql.readthedocs.io/en/stable/sa.html#aiomysql.sa.SAConnection.execute
    */
   class AwaitedSAConnectionExecuteCall extends SqlExecution::Range {

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

@@ -47,7 +47,7 @@ private module Aiopg {
   }
 
   /**
-   * Calling `execute` on a `Cursor` constructs a query.
+   * A query. Calling `execute` on a `Cursor` constructs a query.
    * See https://aiopg.readthedocs.io/en/stable/core.html#aiopg.Cursor.execute
    */
   class CursorExecuteCall extends SqlConstruction::Range, DataFlow::CallCfgNode {
@@ -73,7 +73,7 @@ private module Aiopg {
   }
 
   /**
-   * Awaiting the result of calling `execute` executes the query.
+   * An awaited query. Awaiting the result of calling `execute` executes the query.
    * See https://aiopg.readthedocs.io/en/stable/core.html#aiopg.Cursor.execute
    */
   class AwaitedCursorExecuteCall extends SqlExecution::Range {
@@ -100,7 +100,7 @@ private module Aiopg {
   API::Node saConnection() { result = engine().getMember("acquire").getReturn().getAwaited() }
 
   /**
-   * Calling `execute` on a `SAConnection` constructs a query.
+   * A query. Calling `execute` on a `SAConnection` constructs a query.
    * See https://aiopg.readthedocs.io/en/stable/sa.html#aiopg.sa.SAConnection.execute
    */
   class SAConnectionExecuteCall extends SqlConstruction::Range, DataFlow::CallCfgNode {
@@ -128,7 +128,7 @@ private module Aiopg {
   }
 
   /**
-   * Awaiting the result of calling `execute` executes the query.
+   * An awaited query. Awaiting the result of calling `execute` executes the query.
    * See https://aiopg.readthedocs.io/en/stable/sa.html#aiopg.sa.SAConnection.execute
    */
   class AwaitedSAConnectionExecuteCall extends SqlExecution::Range {

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

@@ -46,7 +46,7 @@ private module Asyncpg {
     }
   }
 
-  /** `Connection`s and `ConnectionPool`s provide some methods that access the file system. */
+  /** A model of `Connection` and `ConnectionPool`, which provide some methods that access the file system. */
   class FileAccessOnConnection extends FileSystemAccess::Range, DataFlow::MethodCallNode {
     string methodName;
 

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

@@ -20,7 +20,7 @@ private import semmle.python.frameworks.PEP249
  */
 module ClickhouseDriver {
   /**
-   * `clickhouse_driver` implements PEP249,
+   * A model of `clickhouse-driver`, which implements PEP249,
    * providing ways to execute SQL statements against a database.
    */
   class ClickHouseDriverPEP249 extends PEP249::PEP249ModuleApiNode {

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

@@ -1862,7 +1862,8 @@ module PrivateDjango {
   // routing modeling
   // ---------------------------------------------------------------------------
   /**
-   * In order to recognize a class as being a django view class, based on the `as_view`
+   * A class that may be a django view class. In order to recognize a class as being a django view class,
+   * based on the `as_view`
    * call, we need to be able to track such calls on _any_ class. This is provided by
    * the member predicates of this QL class.
    *
@@ -1973,7 +1974,7 @@ module PrivateDjango {
   /** Provides a class for modeling new django route handlers. */
   module DjangoRouteHandler {
     /**
-     * Extend this class to model new APIs. If you want to refine existing API models,
+     * A django route handler. Extend this class to model new APIs. If you want to refine existing API models,
      * extend `DjangoRouteHandler` instead.
      */
     abstract class Range extends Function { }

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

@@ -27,7 +27,10 @@ private module MySQLdb {
   // ---------------------------------------------------------------------------
   // MySQLdb
   // ---------------------------------------------------------------------------
-  /** MySQLdb implements PEP 249, providing ways to execute SQL statements against a database. */
+  /**
+   * A model for MySQLdb as a module that implements PEP 249, providing ways to execute SQL statements
+   * against a database.
+   */
   class MySQLdb extends PEP249::PEP249ModuleApiNode {
     MySQLdb() { this = API::moduleImport("MySQLdb") }
   }

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

@@ -22,7 +22,10 @@ private module Psycopg2 {
   // ---------------------------------------------------------------------------
   // Psycopg
   // ---------------------------------------------------------------------------
-  /** psycopg2 implements PEP 249, providing ways to execute SQL statements against a database. */
+  /**
+   * A model of psycopg2 as a module that implements PEP 249, providing ways to execute SQL statements
+   * against a database.
+   */
   class Psycopg2 extends PEP249::PEP249ModuleApiNode {
     Psycopg2() { this = API::moduleImport("psycopg2") }
   }

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

@@ -15,7 +15,10 @@ private import semmle.python.frameworks.PEP249
  * See https://pypi.org/project/PyMySQL/
  */
 private module PyMySQL {
-  /** PyMySQL implements PEP 249, providing ways to execute SQL statements against a database. */
+  /**
+   * A model of PyMySQL as a module that implements PEP 249, providing ways to execute SQL statements
+   * against a database.
+   */
   class PyMySQLPEP249 extends PEP249::PEP249ModuleApiNode {
     PyMySQLPEP249() { this = API::moduleImport("pymysql") }
   }

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

@@ -2338,7 +2338,8 @@ private module StdlibPrivate {
   // sqlite3
   // ---------------------------------------------------------------------------
   /**
-   * sqlite3 implements PEP 249, providing ways to execute SQL statements against a database.
+   * A model of sqlite3 as a module that implements PEP 249, providing ways to execute SQL statements
+   * against a database.
    *
    * See https://devdocs.io/python~3.9/library/sqlite3
    */

python/ql/lib/semmle/python/objects/Callables.qll

@@ -53,7 +53,7 @@ abstract class CallableObjectInternal extends ObjectInternal {
   override ObjectInternal getIterNext() { none() }
 }
 
-/** Class representing Python functions */
+/** A Python function. */
 class PythonFunctionObjectInternal extends CallableObjectInternal, TPythonFunctionObject {
   override Function getScope() {
     exists(CallableExpr expr |
@@ -167,7 +167,7 @@ private BasicBlock blockReturningNone(Function func) {
   )
 }
 
-/** Class representing built-in functions such as `len` or `print`. */
+/** A built-in function such as `len` or `print`. */
 class BuiltinFunctionObjectInternal extends CallableObjectInternal, TBuiltinFunctionObject {
   override Builtin getBuiltin() { this = TBuiltinFunctionObject(result) }
 
@@ -290,7 +290,7 @@ private Builtin getBuiltinFunctionReturnType(Builtin func) {
   )
 }
 
-/** Class representing methods of built-in classes (otherwise known as method-descriptors) such as `list.append`. */
+/** A method of a built-in class (otherwise known as method-descriptors) such as `list.append`. */
 class BuiltinMethodObjectInternal extends CallableObjectInternal, TBuiltinMethodObject {
   override Builtin getBuiltin() { this = TBuiltinMethodObject(result) }
 
@@ -380,7 +380,7 @@ class BuiltinMethodObjectInternal extends CallableObjectInternal, TBuiltinMethod
 }
 
 /**
- * Class representing bound-methods.
+ * A bound-method.
  * Note that built-in methods, such as `[].append` are also represented as bound-methods.
  * Although built-in methods and bound-methods are distinct classes in CPython, their behavior
  * is the same and we treat them identically.

python/ql/lib/semmle/python/objects/Classes.qll

@@ -6,7 +6,7 @@ private import semmle.python.pointsto.PointsToContext
 private import semmle.python.pointsto.MRO
 private import semmle.python.types.Builtins
 
-/** Class representing classes */
+/** A class. */
 abstract class ClassObjectInternal extends ObjectInternal {
   override string getName() { result = this.getClassDeclaration().getName() }
 
@@ -109,7 +109,7 @@ abstract class ClassObjectInternal extends ObjectInternal {
   override predicate isNotSubscriptedType() { any() }
 }
 
-/** Class representing Python source classes */
+/** A class that is defined in Python source. */
 class PythonClassObjectInternal extends ClassObjectInternal, TPythonClassObject {
   /** Gets the scope for this Python class */
   Class getScope() {
@@ -163,7 +163,7 @@ class PythonClassObjectInternal extends ClassObjectInternal, TPythonClassObject
   }
 }
 
-/** Class representing built-in classes, except `type` */
+/** A built-in class, except `type`. */
 class BuiltinClassObjectInternal extends ClassObjectInternal, TBuiltinClassObject {
   override Builtin getBuiltin() { this = TBuiltinClassObject(result) }
 

python/ql/lib/semmle/python/objects/Constants.qll

@@ -7,7 +7,7 @@ private import semmle.python.pointsto.PointsToContext
 private import semmle.python.types.Builtins
 
 /**
- * Class representing constants.
+ * A constant.
  * Includes `None`, `True` and `False` as
  * well as strings and integers.
  */

python/ql/lib/semmle/python/objects/Descriptors.qll

@@ -6,7 +6,7 @@ private import semmle.python.pointsto.PointsToContext
 private import semmle.python.pointsto.MRO
 private import semmle.python.types.Builtins
 
-/** Class representing property objects in Python */
+/** A property object. */
 class PropertyInternal extends ObjectInternal, TProperty {
   /** Gets the name of this property */
   override string getName() { result = this.getGetter().getName() }

python/ql/lib/semmle/python/objects/ObjectAPI.qll

@@ -26,7 +26,7 @@ class ClassScope = Class;
 class ModuleScope = Module;
 
 /**
- * Class representing values in the Python program
+ * A value in the Python program.
  * Each `Value` is a static approximation to a set of one or more real objects.
  */
 class Value extends TObject {
@@ -144,7 +144,7 @@ class Value extends TObject {
 }
 
 /**
- * Class representing modules in the Python program
+ * A module in the Python program.
  * Each `ModuleValue` represents a module object in the Python program.
  */
 class ModuleValue extends Value instanceof ModuleObjectInternal {
@@ -339,7 +339,7 @@ module Value {
 }
 
 /**
- * Class representing callables in the Python program
+ * A callable in the Python program.
  * Callables include Python functions, built-in functions and bound-methods,
  * but not classes.
  */
@@ -447,7 +447,7 @@ class CallableValue extends Value {
 }
 
 /**
- * Class representing bound-methods, such as `o.func`, where `o` is an instance
+ * A bound-method, such as `o.func`, where `o` is an instance
  * of a class that has a callable attribute `func`.
  */
 class BoundMethodValue extends CallableValue instanceof BoundMethodObjectInternal {
@@ -468,7 +468,7 @@ class BoundMethodValue extends CallableValue instanceof BoundMethodObjectInterna
 }
 
 /**
- * Class representing classes in the Python program, both Python and built-in.
+ * A class in the Python program, both Python and built-in.
  */
 class ClassValue extends Value {
   ClassValue() { this.(ObjectInternal).isClass() = true }
@@ -655,7 +655,7 @@ class ClassValue extends Value {
 }
 
 /**
- * Class representing functions in the Python program, both Python and built-in.
+ * A function in the Python program, both Python and built-in.
  * Note that this does not include other callables such as bound-methods.
  */
 abstract class FunctionValue extends CallableValue {
@@ -721,7 +721,7 @@ abstract class FunctionValue extends CallableValue {
   predicate isLambda() { this.getOrigin().getNode() instanceof Lambda }
 }
 
-/** Class representing Python functions */
+/** A Python function. */
 class PythonFunctionValue extends FunctionValue {
   PythonFunctionValue() { this instanceof PythonFunctionObjectInternal }
 
@@ -769,7 +769,7 @@ class PythonFunctionValue extends FunctionValue {
   }
 }
 
-/** Class representing builtin functions, such as `len` or `print` */
+/** A builtin function, such as `len` or `print`. */
 class BuiltinFunctionValue extends FunctionValue {
   BuiltinFunctionValue() { this instanceof BuiltinFunctionObjectInternal }
 
@@ -796,7 +796,7 @@ class BuiltinFunctionValue extends FunctionValue {
   }
 }
 
-/** Class representing builtin methods, such as `list.append` or `set.add` */
+/** A builtin method, such as `list.append` or `set.add` */
 class BuiltinMethodValue extends FunctionValue {
   BuiltinMethodValue() { this instanceof BuiltinMethodObjectInternal }
 

python/ql/lib/semmle/python/pointsto/CallGraph.qll

@@ -23,6 +23,8 @@ private newtype TTInvocation =
   }
 
 /**
+ * A function invocation.
+ *
  * This class represents a static approximation to the
  * dynamic call-graph. A `FunctionInvocation` represents
  * all calls made to a function for a given context.

python/ql/lib/semmle/python/pointsto/PointsToContext.qll

@@ -126,7 +126,7 @@ module Context {
 }
 
 /**
- * Points-to context. Context can be one of:
+ * A points-to context. Context can be one of:
  *    * "main": Used for scripts.
  *    * "import": Use for non-script modules.
  *    * "default": Use for functions and methods without caller context.

python/ql/lib/semmle/python/types/Exceptions.qll

@@ -13,7 +13,7 @@
 
 import python
 
-/** Subset of ControlFlowNodes which might raise an exception */
+/** The subset of ControlFlowNodes which might raise an exception */
 class RaisingNode extends ControlFlowNode {
   RaisingNode() {
     exists(this.getAnExceptionalSuccessor())
@@ -363,7 +363,7 @@ predicate scope_raises_unknown(Scope s) {
   )
 }
 
-/** ControlFlowNode for an 'except' statement. */
+/** The ControlFlowNode for an 'except' statement. */
 class ExceptFlowNode extends ControlFlowNode {
   ExceptFlowNode() { this.getNode() instanceof ExceptStmt }
 

python/ql/lib/semmle/python/types/Extensions.qll

@@ -65,7 +65,7 @@ abstract deprecated class CustomPointsToAttribute extends Object {
 }
 
 /* An example */
-/** Any variable iterating over range or xrange must be an integer */
+/** An extension representing the fact that a variable iterating over range or xrange must be an integer */
 class RangeIterationVariableFact extends PointsToExtension {
   RangeIterationVariableFact() {
     exists(For f, ControlFlowNode iterable |

python/ql/lib/semmle/python/types/Object.qll

@@ -14,6 +14,8 @@ private predicate is_an_object(@py_object obj) {
 }
 
 /**
+ * An object.
+ *
  * Instances of this class represent objects in the Python program. However, since
  *  the QL database is static and Python programs are dynamic, there are necessarily a
  *  number of approximations.
@@ -217,7 +219,7 @@ private Object findByName3(string longName) {
 }
 
 /**
- * Numeric objects (ints and floats).
+ * A numeric object (int or float).
  * Includes those occurring in the source as a literal
  * or in a builtin module as a value.
  */
@@ -269,7 +271,7 @@ class NumericObject extends Object {
 }
 
 /**
- * String objects (unicode or bytes).
+ * A string object (unicode or bytes).
  * Includes those occurring in the source as a literal
  * or in a builtin module as a value.
  */
@@ -299,7 +301,7 @@ class StringObject extends Object {
 }
 
 /**
- * Sequence objects (lists and tuples)
+ * A sequence object (list or tuple)
  *  Includes those occurring in the source as a literal
  *  or in a builtin module as a value.
  */

python/ql/lib/semmle/python/web/bottle/Redirect.qll

@@ -12,7 +12,7 @@ import semmle.python.web.bottle.General
 deprecated FunctionValue bottle_redirect() { result = theBottleModule().attr("redirect") }
 
 /**
- * Represents an argument to the `bottle.redirect` function.
+ * An argument to the `bottle.redirect` function.
  */
 deprecated class BottleRedirect extends TaintSink {
   override string toString() { result = "bottle.redirect" }

python/ql/lib/semmle/python/web/bottle/Request.qll

@@ -68,7 +68,7 @@ deprecated class UntrustedFile extends TaintKind {
 //   TO DO.. File uploads -- Should check about file uploads for other frameworks as well.
 //  Move UntrustedFile to shared location
 //
-/** Parameter to a bottle request handler function */
+/** A parameter to a bottle request handler function */
 deprecated class BottleRequestParameter extends HttpRequestTaintSource {
   BottleRequestParameter() {
     exists(BottleRoute route | route.getANamedArgument() = this.(ControlFlowNode).getNode())

python/ql/src/Classes/ClassAttributes.qll

@@ -1,7 +1,7 @@
 import python
 private import semmle.python.pointsto.PointsTo
 
-/** Helper class for UndefinedClassAttribute.ql and MaybeUndefinedClassAttribute.ql */
+/** A helper class for UndefinedClassAttribute.ql and MaybeUndefinedClassAttribute.ql */
 class CheckClass extends ClassObject {
   private predicate ofInterest() {
     not this.unknowableAttributes() and

python/ql/src/Variables/Undefined.qll

@@ -2,7 +2,7 @@ import python
 import Loop
 import semmle.python.dataflow.TaintTracking
 
-/** Marker for "uninitialized". */
+/** A marker for "uninitialized". */
 class Uninitialized extends TaintKind {
   Uninitialized() { this = "undefined" }
 }

python/ql/src/analysis/DefinitionTracking.qll

@@ -467,7 +467,7 @@ Definition getUniqueDefinition(Expr use) {
   not result = TLocalDefinition(use)
 }
 
-/** Helper class to get suitable locations for attributes */
+/** A helper class to get suitable locations for attributes */
 class NiceLocationExpr extends Expr {
   /** Gets a textual representation of this element. */
   override string toString() { result = this.(Expr).toString() }

python/ql/src/experimental/Security/CWE-348/ClientSuppliedIpUsedInSecurityCheck.ql

@@ -18,7 +18,7 @@ import ClientSuppliedIpUsedInSecurityCheckLib
 import DataFlow::PathGraph
 
 /**
- * Taint-tracking configuration tracing flow from obtaining a client ip from an HTTP header to a sensitive use.
+ * A taint-tracking configuration tracing flow from obtaining a client ip from an HTTP header to a sensitive use.
  */
 class ClientSuppliedIpUsedInSecurityCheckConfig extends TaintTracking::Configuration {
   ClientSuppliedIpUsedInSecurityCheckConfig() { this = "ClientSuppliedIpUsedInSecurityCheckConfig" }

python/ql/src/experimental/semmle/python/templates/Airspeed.qll

@@ -8,7 +8,7 @@ import experimental.semmle.python.templates.SSTISink
 deprecated ClassValue theAirspeedTemplateClass() { result = Value::named("airspeed.Template") }
 
 /**
- * Sink representing the `airspeed.Template` class instantiation argument.
+ * A sink representing the `airspeed.Template` class instantiation argument.
  *
  *  import airspeed
  *  temp = airspeed.Template(`"sink"`)

python/ql/src/experimental/semmle/python/templates/Bottle.qll

@@ -10,7 +10,7 @@ deprecated ClassValue theBottleSimpleTemplateClass() {
 }
 
 /**
- * Sink representing the `bottle.SimpleTemplate` class instantiation argument.
+ * A sink representing the `bottle.SimpleTemplate` class instantiation argument.
  *
  *  from bottle import SimpleTemplate
  *  template = SimpleTemplate(`sink`)
@@ -29,7 +29,7 @@ deprecated class BottleSimpleTemplateSink extends SSTISink {
 }
 
 /**
- * Sink representing the `bottle.template` function call argument.
+ * A sink representing the `bottle.template` function call argument.
  *
  *  from bottle import template
  *  tmp = template(`sink`)

python/ql/src/experimental/semmle/python/templates/Chameleon.qll

@@ -10,7 +10,7 @@ deprecated ClassValue theChameleonPageTemplateClass() {
 }
 
 /**
- * Sink representing the `chameleon.PageTemplate` class instantiation argument.
+ * A sink representing the `chameleon.PageTemplate` class instantiation argument.
  *
  *  from chameleon import PageTemplate
  *  template = PageTemplate(`sink`)

python/ql/src/experimental/semmle/python/templates/Cheetah.qll

@@ -10,7 +10,7 @@ deprecated ClassValue theCheetahTemplateClass() {
 }
 
 /**
- * Sink representing the instantiation argument of any class which derives from
+ * A sink representing the instantiation argument of any class which derives from
  * the `Cheetah.Template.Template` class .
  *
  *  from Cheetah.Template import Template

python/ql/src/experimental/semmle/python/templates/Chevron.qll

@@ -8,7 +8,7 @@ import experimental.semmle.python.templates.SSTISink
 deprecated Value theChevronRenderFunc() { result = Value::named("chevron.render") }
 
 /**
- * Sink representing the `chevron.render` function call argument.
+ * A sink representing the `chevron.render` function call argument.
  *
  *  import chevron
  *  tmp = chevron.render(`sink`,{ 'key' : 'value' })

python/ql/src/experimental/semmle/python/templates/DjangoTemplate.qll

@@ -7,7 +7,7 @@ import experimental.semmle.python.templates.SSTISink
 deprecated ClassValue theDjangoTemplateClass() { result = Value::named("django.template.Template") }
 
 /**
- * Sink representng `django.template.Template` class instantiation argument.
+ * A sink representng `django.template.Template` class instantiation argument.
  *
  *  from django.template import Template
  *  template = Template(`sink`)

python/ql/src/experimental/semmle/python/templates/FlaskTemplate.qll

@@ -9,7 +9,7 @@ deprecated Value theFlaskRenderTemplateClass() {
 }
 
 /**
- * Sink representng `flask.render_template_string` function call argument.
+ * A sink representng `flask.render_template_string` function call argument.
  *
  *  from flask import render_template_string
  *  render_template_string(`sink`)

python/ql/src/experimental/semmle/python/templates/Genshi.qll

@@ -15,7 +15,7 @@ deprecated ClassValue theGenshiMarkupTemplateClass() {
 }
 
 /**
- * Sink representing the `genshi.template.TextTemplate` class instantiation argument.
+ * A sink representing the `genshi.template.TextTemplate` class instantiation argument.
  *
  *  from genshi.template import TextTemplate
  *  tmpl = TextTemplate('sink')
@@ -34,7 +34,7 @@ deprecated class GenshiTextTemplateSink extends SSTISink {
 }
 
 /**
- * Sink representing the `genshi.template.MarkupTemplate` class instantiation argument.
+ * A sink representing the `genshi.template.MarkupTemplate` class instantiation argument.
  *
  *  from genshi.template import MarkupTemplate
  *  tmpl = MarkupTemplate('sink')

python/ql/src/experimental/semmle/python/templates/Jinja.qll

@@ -11,7 +11,7 @@ deprecated ClassValue theJinja2TemplateClass() { result = Value::named("jinja2.T
 deprecated Value theJinja2FromStringValue() { result = Value::named("jinja2.from_string") }
 
 /**
- * Sink representing the `jinja2.Template` class instantiation argument.
+ * A sink representing the `jinja2.Template` class instantiation argument.
  *
  *  from jinja2 import Template
  *  template = Template(`sink`)
@@ -30,7 +30,7 @@ deprecated class Jinja2TemplateSink extends SSTISink {
 }
 
 /**
- * Sink representing the `jinja2.from_string` function call argument.
+ * A sink representing the `jinja2.from_string` function call argument.
  *
  *  from jinja2 import from_string
  *  template = from_string(`sink`)

python/ql/src/experimental/semmle/python/templates/Mako.qll

@@ -8,7 +8,7 @@ import experimental.semmle.python.templates.SSTISink
 deprecated ClassValue theMakoTemplateClass() { result = Value::named("mako.template.Template") }
 
 /**
- * Sink representing the `mako.template.Template` class instantiation argument.
+ * A sink representing the `mako.template.Template` class instantiation argument.
  *
  *  from mako.template import Template
  *  mytemplate = Template("hello world!")

python/ql/src/experimental/semmle/python/templates/TRender.qll

@@ -8,7 +8,7 @@ import experimental.semmle.python.templates.SSTISink
 deprecated ClassValue theTRenderTemplateClass() { result = Value::named("trender.TRender") }
 
 /**
- * Sink representing the `trender.TRender` class instantiation argument.
+ * A sink representing the `trender.TRender` class instantiation argument.
  *
  *  from trender import TRender
  *  template = TRender(`sink`)

python/ql/test/experimental/library-tests/CallGraph/CallGraphTest.qll

@@ -88,7 +88,7 @@ private newtype TCallGraphResolver =
   TPointsToResolver() or
   TTypeTrackerResolver()
 
-/** Describes a method of call graph resolution */
+/** A method of call graph resolution */
 abstract class CallGraphResolver extends TCallGraphResolver {
   abstract predicate callEdge(Call call, Function callable);
 

python/ql/test/library-tests/PointsTo/inheritance/Mro.ql

@@ -2,7 +2,7 @@ import python
 private import semmle.python.objects.ObjectInternal
 private import semmle.python.pointsto.PointsTo
 
-/** Make unknown type visible */
+/** An unknown type. Not usually visible. */
 class UnknownType extends UnknownClassInternal {
   override string toString() { result = "*UNKNOWN TYPE" }
 }

python/ql/test/library-tests/PointsTo/metaclass/Mro.ql

@@ -2,7 +2,7 @@ import python
 private import semmle.python.objects.ObjectInternal
 private import semmle.python.pointsto.PointsTo
 
-/** Make unknown type visible */
+/** An unknown type. Not usually visible. */
 class UnknownType extends UnknownClassInternal {
   override string toString() { result = "*UNKNOWN TYPE" }
 }

python/ql/test/library-tests/PointsTo/metaclass/test.ql

@@ -1,7 +1,7 @@
 import python
 private import semmle.python.objects.ObjectInternal
 
-/** Make unknown type visible */
+/** An unknown type. Not usually visible. */
 class UnknownType extends UnknownClassInternal {
   override string toString() { result = "*UNKNOWN TYPE" }
 }

python/ql/test/library-tests/taint/example/DilbertConfig.qll

@@ -17,7 +17,7 @@ class Wally extends Engineer {
   Wally() { this = "Wally" }
 }
 
-/** Then the configuration */
+/** The configuration for this example. */
 class DilbertConfig extends TaintTracking::Configuration {
   DilbertConfig() { this = "Dilbert config" }
 

python/tools/recorded-call-graph-metrics/ql/lib/RecordedCalls.qll

@@ -162,7 +162,7 @@ private Builtin traverse_qualname(Builtin parent, string qualname) {
 }
 
 /**
- * Class of recorded calls where we can identify both the `call` and the `callee` uniquely.
+ * Arecorded call where we can identify both the `call` and the `callee` uniquely.
  */
 class IdentifiedRecordedCall extends XMLRecordedCall {
   IdentifiedRecordedCall() {
@@ -212,14 +212,14 @@ class IdentifiedRecordedCall extends XMLRecordedCall {
 }
 
 /**
- * Class of recorded calls where we cannot identify both the `call` and the `callee` uniquely.
+ * A recorded call where we cannot identify both the `call` and the `callee` uniquely.
  */
 class UnidentifiedRecordedCall extends XMLRecordedCall {
   UnidentifiedRecordedCall() { not this instanceof IdentifiedRecordedCall }
 }
 
 /**
- * Recorded calls made from outside project folder, that can be ignored when evaluating
+ * A Recorded call made from outside the project folder. These can be ignored when evaluating
  * call-graph quality.
  */
 class IgnoredRecordedCall extends XMLRecordedCall {