Python: Fix up a bunch of function QLDoc

cpp/ql/test/TestUtilities/InlineExpectationsTest.qll

@@ -124,7 +124,7 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Like `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */

csharp/ql/test/TestUtilities/InlineExpectationsTest.qll

@@ -124,7 +124,7 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Like `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */

java/ql/test/TestUtilities/InlineExpectationsTest.qll

@@ -124,7 +124,7 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Like `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */

python/ql/lib/semmle/python/Comment.qll

@@ -59,7 +59,7 @@ class CommentBlock extends @py_comment {
   /** Gets a textual representation of this element. */
   string toString() { result = "Comment block" }
 
-  /** The length of this comment block (in comments) */
+  /** Gets the length of this comment block (in comments) */
   int length() { result = max(int i | comment_block_part(this, _, i)) }
 
   /**

python/ql/lib/semmle/python/Comparisons.qll

@@ -76,22 +76,22 @@ class CompareOp extends int {
   }
 }
 
-/** The `CompareOp` for "equals". */
+/** Gets the `CompareOp` for "equals". */
 CompareOp eq() { result = 1 }
 
-/** The `CompareOp` for "not equals". */
+/** Gets the `CompareOp` for "not equals". */
 CompareOp ne() { result = 2 }
 
-/** The `CompareOp` for "less than". */
+/** Gets the `CompareOp` for "less than". */
 CompareOp lt() { result = 3 }
 
-/** The `CompareOp` for "less than or equal to". */
+/** Gets the `CompareOp` for "less than or equal to". */
 CompareOp le() { result = 4 }
 
-/** The `CompareOp` for "greater than". */
+/** Gets the `CompareOp` for "greater than". */
 CompareOp gt() { result = 5 }
 
-/** The `CompareOp` for "greater than or equal to". */
+/** Gets the `CompareOp` for "greater than or equal to". */
 CompareOp ge() { result = 6 }
 
 /* Workaround precision limits in floating point numbers */

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

@@ -446,6 +446,8 @@ class Unicode extends StrConst {
   }
 
   /**
+   * Gets the quoted representation fo this string.
+   *
    * The extractor puts quotes into the name of each string (to prevent "0" clashing with 0).
    * The following predicate help us match up a string/byte literals in the source
    * which the equivalent object.

python/ql/lib/semmle/python/Flow.qll

@@ -155,7 +155,7 @@ class ControlFlowNode extends @py_flow_node {
   /** Whether this flow node is the first in its scope */
   predicate isEntryNode() { py_scope_flow(this, _, -1) }
 
-  /** The value that this ControlFlowNode points-to. */
+  /** Gets the value that this ControlFlowNode points-to. */
   predicate pointsTo(Value value) { this.pointsTo(_, value, _) }
 
   /** Gets the value that this ControlFlowNode points-to. */
@@ -164,10 +164,10 @@ class ControlFlowNode extends @py_flow_node {
   /** Gets a value that this ControlFlowNode may points-to. */
   Value inferredValue() { this.pointsTo(_, result, _) }
 
-  /** The value and origin that this ControlFlowNode points-to. */
+  /** Gets the value and origin that this ControlFlowNode points-to. */
   predicate pointsTo(Value value, ControlFlowNode origin) { this.pointsTo(_, value, origin) }
 
-  /** The value and origin that this ControlFlowNode points-to, given the context. */
+  /** Gets the value and origin that this ControlFlowNode points-to, given the context. */
   predicate pointsTo(Context context, Value value, ControlFlowNode origin) {
     PointsTo::pointsTo(this, context, value, origin)
   }

python/ql/lib/semmle/python/Function.qll

@@ -5,11 +5,11 @@ import python
  * It is the syntactic entity that is compiled to a code object.
  */
 class Function extends Function_, Scope, AstNode {
-  /** The expression defining this function */
+  /** Gets the expression defining this function */
   CallableExpr getDefinition() { result = this.getParent() }
 
   /**
-   * The scope in which this function occurs, will be a class for a method,
+   * Gets the scope in which this function occurs. This will be a class for a method,
    * another function for nested functions, generator expressions or comprehensions,
    * or a module for a plain function.
    */
@@ -183,8 +183,8 @@ class FunctionDef extends Assign {
   override Stmt getLastStatement() { result = this.getDefinedFunction().getLastStatement() }
 }
 
+/** A function that uses 'fast' locals, stored in the frame not in a dictionary. */
 class FastLocalsFunction extends Function {
-  /** A function that uses 'fast' locals, stored in the frame not in a dictionary. */
   FastLocalsFunction() {
     not exists(ImportStar i | i.getScope() = this) and
     not exists(Exec e | e.getScope() = this)

python/ql/lib/semmle/python/Import.qll

@@ -35,6 +35,8 @@ class ImportExpr extends ImportExpr_ {
   }
 
   /**
+   * Gets the level of this import.
+   *
    * The language specifies level as -1 if relative imports are to be tried first, 0 for absolute imports,
    * and level > 0 for explicit relative imports.
    */

python/ql/lib/semmle/python/Metrics.qll

@@ -18,7 +18,7 @@ class FunctionMetrics extends Function {
   int getNumberOfLinesOfDocStrings() { py_docstringlines(this, result) }
 
   /**
-   * Cyclomatic complexity:
+   * Gets the cyclomatic complexity of the function:
    * The number of linearly independent paths through the source code.
    * Computed as     E - N + 2P,
    * where
@@ -130,13 +130,13 @@ class ClassMetrics extends Class {
   }
 
   /**
-   * The afferent coupling of a class is the number of classes that
+   * Gets the afferent coupling of a class -- the number of classes that
    * directly depend on it.
    */
   int getAfferentCoupling() { result = count(ClassMetrics t | t.dependsOn(this)) }
 
   /**
-   * The efferent coupling of a class is the number of classes that
+   * Gets the efferent coupling of a class -- the number of classes that
    * it directly depends on.
    */
   int getEfferentCoupling() { result = count(ClassMetrics t | this.dependsOn(t)) }
@@ -273,13 +273,13 @@ class ModuleMetrics extends Module {
   int getNumberOfLinesOfDocStrings() { py_docstringlines(this, result) }
 
   /**
-   * The afferent coupling of a class is the number of classes that
+   * Gets the afferent coupling of a class -- the number of classes that
    *  directly depend on it.
    */
   int getAfferentCoupling() { result = count(ModuleMetrics t | t.dependsOn(this)) }
 
   /**
-   * The efferent coupling of a class is the number of classes that
+   * Gets the efferent coupling of a class -- the number of classes that
    *  it directly depends on.
    */
   int getEfferentCoupling() { result = count(ModuleMetrics t | this.dependsOn(t)) }

python/ql/lib/semmle/python/Module.qll

@@ -22,12 +22,13 @@ class Module extends Module_, Scope, AstNode {
   }
 
   /**
+   * Gets the enclosing scope of this module (always none).
+   *
    * This method will be deprecated in the next release. Please use `getEnclosingScope()` instead.
-   * The enclosing scope of this module (always none)
    */
   override Scope getScope() { none() }
 
-  /** The enclosing scope of this module (always none) */
+  /** Gets the enclosing scope of this module (always none) */
   override Scope getEnclosingScope() { none() }
 
   /** Gets the statements forming the body of this module */

python/ql/lib/semmle/python/Scope.qll

@@ -9,11 +9,12 @@ class Scope extends Scope_ {
   Module getEnclosingModule() { result = this.getEnclosingScope().getEnclosingModule() }
 
   /**
+   * Gets the scope enclosing this scope (modules have no enclosing scope).
+   *
    * This method will be deprecated in the next release. Please use `getEnclosingScope()` instead.
    * The reason for this is to avoid confusion around use of `x.getScope+()` where `x` might be an
    * `AstNode` or a `Variable`. Forcing the users to write `x.getScope().getEnclosingScope*()` ensures that
    * the apparent semantics and the actual semantics coincide.
-   * [ Gets the scope enclosing this scope (modules have no enclosing scope) ]
    */
   Scope getScope() { none() }
 

python/ql/lib/semmle/python/SpecialMethods.qll

@@ -112,6 +112,6 @@ class SpecialMethodCallNode extends PotentialSpecialMethodCallNode {
     )
   }
 
-  /** The method that is called. */
+  /** Gets the method that is called. */
   Value getResolvedSpecialMethod() { result = resolvedSpecialMethod }
 }

python/ql/lib/semmle/python/Stmts.qll

@@ -323,7 +323,7 @@ class Raise extends Raise_ {
   override Expr getASubExpression() { py_exprs(result, _, this, _) }
 
   /**
-   * The expression immediately following the `raise`, this is the
+   * Gets the expression immediately following the `raise`. This is the
    * exception raised, but not accounting for tuples in Python 2.
    */
   Expr getException() {
@@ -332,7 +332,7 @@ class Raise extends Raise_ {
     result = this.getExc()
   }
 
-  /** The exception raised, accounting for tuples in Python 2. */
+  /** Gets the exception raised, accounting for tuples in Python 2. */
   Expr getRaised() {
     exists(Expr raw | raw = this.getException() |
       if not major_version() = 2 or not exists(raw.(Tuple).getAnElt())

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

@@ -63,7 +63,7 @@ module syntheticPreUpdateNode {
     override Node getPreUpdateNode() { result.(SyntheticPreUpdateNode).getPostUpdateNode() = this }
 
     /**
-     * A label for this kind of node. This will figure in the textual representation of the synthesized pre-update node.
+     * Gets the label for this kind of node. This will figure in the textual representation of the synthesized pre-update node.
      *
      * There is currently only one reason for needing a pre-update node, so we always use that as the label.
      */
@@ -108,7 +108,7 @@ module syntheticPostUpdateNode {
     }
 
     /**
-     * A label for this kind of node. This will figure in the textual representation of the synthesized post-update node.
+     * Gets the label for this kind of node. This will figure in the textual representation of the synthesized post-update node.
      * We favour being an arguments as the reason for the post-update node in case multiple reasons apply.
      */
     string label() {
@@ -122,6 +122,8 @@ module syntheticPostUpdateNode {
   }
 
   /**
+   * Gets the pre-update node for this node.
+   *
    * An argument might have its value changed as a result of a call.
    * Certain arguments, such as implicit self arguments are already post-update nodes
    * and should not have an extra node synthesised.
@@ -143,7 +145,7 @@ module syntheticPostUpdateNode {
     )
   }
 
-  /** An object might have its value changed after a store. */
+  /** Gets the pre-update node associated with a store. This is used for when an object might have its value changed after a store. */
   CfgNode storePreUpdateNode() {
     exists(Attribute a |
       result.getNode() = a.getObject().getAFlowNode() and
@@ -152,7 +154,7 @@ module syntheticPostUpdateNode {
   }
 
   /**
-   * A node marking the state change of an object after a read.
+   * Gets a node marking the state change of an object after a read.
    *
    * A reverse read happens when the result of a read is modified, e.g. in
    * ```python
@@ -1617,6 +1619,8 @@ import IterableUnpacking
  */
 module MatchUnpacking {
   /**
+   * Holds when there is flow from the subject `nodeFrom` to the case `nodeTo` of a `match` statement.
+   *
    * The subject of a match flows to each top-level pattern
    * (a pattern directly under a `case` statement).
    *

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

@@ -139,7 +139,7 @@ private module SsaComputeImpl {
       Liveness::liveAtEntry(v, succ)
     }
 
-    /** A phi node for `v` at the beginning of basic block `b`. */
+    /** Holds if there is a phi node for `v` at the beginning of basic block `b`. */
     cached
     predicate phiNode(SsaSourceVariable v, BasicBlock b) {
       (
@@ -175,8 +175,8 @@ private module SsaComputeImpl {
   }
 
   /**
-   * A ranking of the indices `i` at which there is an SSA definition or use of
-   * `v` in the basic block `b`.
+   * Holds if the `rankix`th definition or use of the SSA variable `v` in the basic block `b` occurs
+   * at index `i`.
    *
    * Basic block indices are translated to rank indices in order to skip
    * irrelevant indices at which there is no definition or use when traversing
@@ -187,14 +187,14 @@ private module SsaComputeImpl {
     i = rank[rankix](int j | variableDef(v, _, b, j) or variableUse(v, _, b, j))
   }
 
-  /** A definition of a variable occurring at the specified rank index in basic block `b`. */
+  /** Holds if there is a definition of a variable occurring at the specified rank index in basic block `b`. */
   cached
   predicate defRank(SsaSourceVariable v, BasicBlock b, int rankix, int i) {
     variableDef(v, _, b, i) and
     defUseRank(v, b, rankix, i)
   }
 
-  /** A variable access `use` of `v` in `b` at index `i`. */
+  /** Holds if there is a variable access `use` of `v` in `b` at index `i`. */
   cached
   predicate variableUse(SsaSourceVariable v, ControlFlowNode use, BasicBlock b, int i) {
     (v.getAUse() = use or v.hasRefinement(use, _)) and
@@ -205,7 +205,7 @@ private module SsaComputeImpl {
   }
 
   /**
-   * A definition of an SSA variable occurring at the specified position.
+   * Holds if there is a definition of an SSA variable occurring at the specified position.
    * This is either a phi node, a `VariableUpdate`, or a parameter.
    */
   cached
@@ -227,7 +227,7 @@ private module SsaComputeImpl {
    * dominance.
    */
 
-  /** The maximum rank index for the given variable and basic block. */
+  /** Gets the maximum rank index for the given variable and basic block. */
   cached
   int lastRank(SsaSourceVariable v, BasicBlock b) {
     result = max(int rankix | defUseRank(v, b, rankix, _))
@@ -253,7 +253,7 @@ private module SsaComputeImpl {
     i = piIndex()
   }
 
-  /** The SSA definition reaches the rank index `rankix` in its own basic block `b`. */
+  /** Holds if the SSA definition reaches the rank index `rankix` in its own basic block `b`. */
   cached
   predicate ssaDefReachesRank(SsaSourceVariable v, BasicBlock b, int i, int rankix) {
     ssaDefRank(v, b, rankix, i)
@@ -264,7 +264,7 @@ private module SsaComputeImpl {
   }
 
   /**
-   * The SSA definition of `v` at `def` reaches `use` in the same basic block
+   * Holds if the SSA definition of `v` at `def` reaches `use` in the same basic block
    * without crossing another SSA definition of `v`.
    */
   cached
@@ -303,7 +303,7 @@ private module SsaComputeImpl {
     }
 
     /**
-     * The SSA definition of `v` at `def` reaches the end of a basic block `b`, at
+     * Holds if the SSA definition of `v` at `def` reaches the end of a basic block `b`, at
      * which point it is still live, without crossing another SSA definition of `v`.
      */
     cached
@@ -320,7 +320,7 @@ private module SsaComputeImpl {
     }
 
     /**
-     * The SSA definition of `v` at `(defbb, defindex)` reaches `use` without crossing another
+     * Holds if the SSA definition of `v` at `(defbb, defindex)` reaches `use` without crossing another
      * SSA definition of `v`.
      */
     cached
@@ -360,7 +360,7 @@ private module SsaComputeImpl {
       i = rank[rankix](int j | variableDefine(v, _, b, j) or variableSourceUse(v, _, b, j))
     }
 
-    /** A variable access `use` of `v` in `b` at index `i`. */
+    /** Holds if there is a variable access `use` of `v` in `b` at index `i`. */
     cached
     predicate variableSourceUse(SsaSourceVariable v, ControlFlowNode use, BasicBlock b, int i) {
       v.getASourceUse() = use and

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

@@ -15,7 +15,7 @@ private module Aiomysql {
   private import semmle.python.internal.Awaited
 
   /**
-   * A `ConectionPool` is created when the result of `aiomysql.create_pool()` is awaited.
+   * Gets the `ConnectionPool` that is created when the result of `aiomysql.create_pool()` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/pool.html
    */
   API::Node connectionPool() {
@@ -23,7 +23,7 @@ private module Aiomysql {
   }
 
   /**
-   * A `Connection` is created when
+   * Gets the `Connection` that is created when
    * - the result of `aiomysql.connect()` is awaited.
    * - the result of calling `aquire` on a `ConnectionPool` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/connection.html#connection
@@ -35,7 +35,7 @@ private module Aiomysql {
   }
 
   /**
-   * A `Cursor` is created when
+   * Gets the `Cursor` that is created when
    * - the result of calling `cursor` on a `ConnectionPool` is awaited.
    * - the result of calling `cursor` on a `Connection` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/cursors.html
@@ -85,7 +85,7 @@ private module Aiomysql {
   }
 
   /**
-   * An `Engine` is created when the result of calling `aiomysql.sa.create_engine` is awaited.
+   * Gets the `Engine` that is created when the result of calling `aiomysql.sa.create_engine` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/sa.html#engine
    */
   API::Node engine() {
@@ -98,7 +98,7 @@ private module Aiomysql {
   }
 
   /**
-   * A `SAConnection` is created when the result of calling `aquire` on an `Engine` is awaited.
+   * Gets the `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
    * See https://aiomysql.readthedocs.io/en/stable/sa.html#connection
    */
   API::Node saConnection() { result = engine().getMember("acquire").getReturn().getAwaited() }

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

@@ -15,7 +15,7 @@ private module Aiopg {
   private import semmle.python.internal.Awaited
 
   /**
-   * A `ConectionPool` is created when the result of `aiopg.create_pool()` is awaited.
+   * Gets the `ConnectionPool` that is created when the result of `aiopg.create_pool()` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/core.html#pool
    */
   API::Node connectionPool() {
@@ -23,7 +23,7 @@ private module Aiopg {
   }
 
   /**
-   * A `Connection` is created when
+   * Gets the `Connection` that is created when
    * - the result of `aiopg.connect()` is awaited.
    * - the result of calling `aquire` on a `ConnectionPool` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/core.html#connection
@@ -35,7 +35,7 @@ private module Aiopg {
   }
 
   /**
-   * A `Cursor` is created when
+   * Gets the `Cursor` that is created when
    * - the result of calling `cursor` on a `ConnectionPool` is awaited.
    * - the result of calling `cursor` on a `Connection` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/core.html#cursor
@@ -85,7 +85,7 @@ private module Aiopg {
   }
 
   /**
-   * An `Engine` is created when the result of calling `aiopg.sa.create_engine` is awaited.
+   * Gets the `Engine` that is created when the result of calling `aiopg.sa.create_engine` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/sa.html#engine
    */
   API::Node engine() {
@@ -94,7 +94,7 @@ private module Aiopg {
   }
 
   /**
-   * A `SAConnection` is created when the result of calling `aquire` on an `Engine` is awaited.
+   * Gets the `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
    * See https://aiopg.readthedocs.io/en/stable/sa.html#connection
    */
   API::Node saConnection() { result = engine().getMember("acquire").getReturn().getAwaited() }

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

@@ -12,13 +12,13 @@ private import semmle.python.ApiGraphs
 private module Asyncpg {
   private import semmle.python.internal.Awaited
 
-  /** A `ConectionPool` is created when the result of `asyncpg.create_pool()` is awaited. */
+  /** Gets the `ConnectionPool` that 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
+   * Gets the `Connection` that is created when
    * - the result of `asyncpg.connect()` is awaited.
    * - the result of calling `aquire` on a `ConnectionPool` is awaited.
    */

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

@@ -354,7 +354,7 @@ private module Tornado {
   // ---------------------------------------------------------------------------
   // routing
   // ---------------------------------------------------------------------------
-  /** A sequence that defines a number of route rules */
+  /** Gets a sequence that defines a number of route rules */
   SequenceNode routeSetupRuleList() {
     exists(CallNode call | call = any(tornado::web::Application::ClassInstantiation c).asCfgNode() |
       result in [call.getArg(0), call.getArgByName("handlers")]

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

@@ -178,7 +178,6 @@ class SelfInstanceInternal extends TSelfInstance, InstanceObject {
     result = "self instance of " + this.getClass().(ClassObjectInternal).getName()
   }
 
-  /** The boolean value of this object, if it has one */
   override boolean booleanValue() {
     //result = this.getClass().instancesBooleanValue()
     result = maybe()

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

@@ -21,7 +21,7 @@ class ObjectInternal extends TObject {
   abstract string toString();
 
   /**
-   * The boolean value of this object, this may be both
+   * Gets the boolean value of this object. This may be both
    * true and false if the "object" represents a set of possible objects.
    */
   abstract boolean booleanValue();
@@ -88,14 +88,14 @@ class ObjectInternal extends TObject {
   abstract predicate callResult(PointsToContext callee, ObjectInternal obj, CfgOrigin origin);
 
   /**
-   * The integer value of things that have integer values and whose integer value is
+   * Gets the integer value of things that have integer values and whose integer value is
    * tracked.
    * That is, some ints, mainly small numbers, and bools.
    */
   abstract int intValue();
 
   /**
-   * The string value of things that have string values.
+   * Gets the string value of things that have string values.
    * That is, strings.
    */
   abstract string strValue();
@@ -497,7 +497,7 @@ module ObjectInternal {
 
   ObjectInternal superType() { result = TBuiltinClassObject(Builtin::special("super")) }
 
-  /** The old-style class type (Python 2 only) */
+  /** Gets the old-style class type (Python 2 only) */
   ObjectInternal classType() { result = TBuiltinClassObject(Builtin::special("ClassType")) }
 
   ObjectInternal emptyTuple() { result.(BuiltinTupleObjectInternal).length() = 0 }

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

@@ -90,16 +90,8 @@ abstract class TupleObjectInternal extends SequenceObjectInternal {
     none()
   }
 
-  /**
-   * The integer value of things that have integer values.
-   * That is, ints and bools.
-   */
   override int intValue() { none() }
 
-  /**
-   * The integer value of things that have integer values.
-   * That is, strings.
-   */
   override string strValue() { none() }
 
   override predicate calleeAndOffset(Function scope, int paramOffset) { none() }
@@ -241,16 +233,8 @@ class SysVersionInfoObjectInternal extends TSysVersionInfo, SequenceObjectIntern
     none()
   }
 
-  /**
-   * The integer value of things that have integer values.
-   * That is, ints and bools.
-   */
   override int intValue() { none() }
 
-  /**
-   * The integer value of things that have integer values.
-   * That is, strings.
-   */
   override string strValue() { none() }
 
   override predicate calleeAndOffset(Function scope, int paramOffset) { none() }
@@ -261,10 +245,6 @@ class SysVersionInfoObjectInternal extends TSysVersionInfo, SequenceObjectIntern
 
   override predicate subscriptUnknown() { none() }
 
-  /**
-   * Gets the length of the sequence that this "object" represents.
-   * Always returns a value for a sequence, will be -1 if object has no fixed length.
-   */
   override int length() { result = 5 }
 
   override predicate functionAndOffset(CallableObjectInternal function, int offset) { none() }

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

@@ -25,13 +25,13 @@ module BasePointsTo {
   }
 }
 
-/** The kwargs parameter (**kwargs) in a function definition is always a dict */
+/** Gets the kwargs parameter (`**kwargs`). In a function definition this is always a dict. */
 predicate kwargs_points_to(ControlFlowNode f, ClassObject cls) {
   exists(Function func | func.getKwarg() = f.getNode()) and
   cls = theDictType()
 }
 
-/** The varargs (*varargs) in a function definition is always a tuple */
+/** Gets the varargs parameter (`*varargs`). In a function definition this is always a tuple. */
 predicate varargs_points_to(ControlFlowNode f, ClassObject cls) {
   exists(Function func | func.getVararg() = f.getNode()) and
   cls = theTupleType()

python/ql/lib/semmle/python/security/strings/Basic.qll

@@ -45,7 +45,7 @@ abstract deprecated class StringKind extends TaintKind {
 deprecated private class StringEqualitySanitizer extends Sanitizer {
   StringEqualitySanitizer() { this = "string equality sanitizer" }
 
-  /** The test `if untrusted == "KNOWN_VALUE":` sanitizes `untrusted` on its `true` edge. */
+  /* The test `if untrusted == "KNOWN_VALUE":` sanitizes `untrusted` on its `true` edge. */
   override predicate sanitizingEdge(TaintKind taint, PyEdgeRefinement test) {
     taint instanceof StringKind and
     exists(ControlFlowNode const, Cmpop op | const.getNode() instanceof StrConst |

python/ql/lib/semmle/python/templates/PyxlTags.qll

@@ -57,7 +57,7 @@ class PyxlEndIfTag extends PyxlTag {
 class PyxlRawHtml extends PyxlTag {
   PyxlRawHtml() { this.getPyxlTagName() = "rawhtml" }
 
-  /** The text for this raw html, if it is simple text. */
+  /** Gets the text for this raw html, if it is simple text. */
   string getText() {
     exists(Unicode text |
       text = this.getValue() and

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

@@ -63,13 +63,13 @@ class ClassObject extends Object {
   ClassObject getAnImproperSuperType() { result = this.getABaseType*() }
 
   /**
-   * Whether this class is a new style class.
+   * Holds if this class is a new style class.
    * A new style class is one that implicitly or explicitly inherits from `object`.
    */
   predicate isNewStyle() { Types::isNewStyle(this.theClass()) }
 
   /**
-   * Whether this class is an old style class.
+   * Holds if this class is an old style class.
    * An old style class is one that does not inherit from `object`.
    */
   predicate isOldStyle() { Types::isOldStyle(this.theClass()) }
@@ -357,7 +357,7 @@ class ClassObject extends Object {
 }
 
 /**
- * The 'str' class. This is the same as the 'bytes' class for
+ * Gets the 'str' class. This is the same as the 'bytes' class for
  * Python 2 and the 'unicode' class for Python 3
  */
 ClassObject theStrType() {
@@ -375,128 +375,128 @@ ClassObject theAbcMetaClassObject() {
 }
 
 /* Common builtin classes */
-/** The built-in class NoneType */
+/** Gets the built-in class NoneType */
 ClassObject theNoneType() { result.asBuiltin() = Builtin::special("NoneType") }
 
-/** The built-in class 'bool' */
+/** Gets the built-in class 'bool' */
 ClassObject theBoolType() { result.asBuiltin() = Builtin::special("bool") }
 
-/** The builtin class 'type' */
+/** Gets the builtin class 'type' */
 ClassObject theTypeType() { result.asBuiltin() = Builtin::special("type") }
 
-/** The builtin object ClassType (for old-style classes) */
+/** Gets the builtin object ClassType (for old-style classes) */
 ClassObject theClassType() { result.asBuiltin() = Builtin::special("ClassType") }
 
-/** The builtin object InstanceType (for old-style classes) */
+/** Gets the builtin object InstanceType (for old-style classes) */
 ClassObject theInstanceType() { result.asBuiltin() = Builtin::special("InstanceType") }
 
-/** The builtin class 'tuple' */
+/** Gets the builtin class 'tuple' */
 ClassObject theTupleType() { result.asBuiltin() = Builtin::special("tuple") }
 
-/** The builtin class 'int' */
+/** Gets the builtin class 'int' */
 ClassObject theIntType() { result.asBuiltin() = Builtin::special("int") }
 
-/** The builtin class 'long' (Python 2 only) */
+/** Gets the builtin class 'long' (Python 2 only) */
 ClassObject theLongType() { result.asBuiltin() = Builtin::special("long") }
 
-/** The builtin class 'float' */
+/** Gets the builtin class 'float' */
 ClassObject theFloatType() { result.asBuiltin() = Builtin::special("float") }
 
-/** The builtin class 'complex' */
+/** Gets the builtin class 'complex' */
 ClassObject theComplexType() { result.asBuiltin() = Builtin::special("complex") }
 
-/** The builtin class 'object' */
+/** Gets the builtin class 'object' */
 ClassObject theObjectType() { result.asBuiltin() = Builtin::special("object") }
 
-/** The builtin class 'list' */
+/** Gets the builtin class 'list' */
 ClassObject theListType() { result.asBuiltin() = Builtin::special("list") }
 
-/** The builtin class 'dict' */
+/** Gets the builtin class 'dict' */
 ClassObject theDictType() { result.asBuiltin() = Builtin::special("dict") }
 
-/** The builtin class 'Exception' */
+/** Gets the builtin class 'Exception' */
 ClassObject theExceptionType() { result.asBuiltin() = Builtin::special("Exception") }
 
-/** The builtin class for unicode. unicode in Python2, str in Python3 */
+/** Gets the builtin class for unicode. unicode in Python2, str in Python3 */
 ClassObject theUnicodeType() { result.asBuiltin() = Builtin::special("unicode") }
 
-/** The builtin class '(x)range' */
+/** Gets the builtin class '(x)range' */
 ClassObject theRangeType() {
   result = Object::builtin("xrange")
   or
   major_version() = 3 and result = Object::builtin("range")
 }
 
-/** The builtin class for bytes. str in Python2, bytes in Python3 */
+/** Gets the builtin class for bytes. str in Python2, bytes in Python3 */
 ClassObject theBytesType() { result.asBuiltin() = Builtin::special("bytes") }
 
-/** The builtin class 'set' */
+/** Gets the builtin class 'set' */
 ClassObject theSetType() { result.asBuiltin() = Builtin::special("set") }
 
-/** The builtin class 'property' */
+/** Gets the builtin class 'property' */
 ClassObject thePropertyType() { result.asBuiltin() = Builtin::special("property") }
 
-/** The builtin class 'BaseException' */
+/** Gets the builtin class 'BaseException' */
 ClassObject theBaseExceptionType() { result.asBuiltin() = Builtin::special("BaseException") }
 
-/** The class of builtin-functions */
+/** Gets the class of builtin-functions */
 ClassObject theBuiltinFunctionType() {
   result.asBuiltin() = Builtin::special("BuiltinFunctionType")
 }
 
-/** The class of Python functions */
+/** Gets the class of Python functions */
 ClassObject thePyFunctionType() { result.asBuiltin() = Builtin::special("FunctionType") }
 
-/** The builtin class 'classmethod' */
+/** Gets thGets the builtin class 'classmethod' */
 ClassObject theClassMethodType() { result.asBuiltin() = Builtin::special("ClassMethod") }
 
-/** The builtin class 'staticmethod' */
+/** Gets the builtin class 'staticmethod' */
 ClassObject theStaticMethodType() { result.asBuiltin() = Builtin::special("StaticMethod") }
 
-/** The class of modules */
+/** Gets the class of modules */
 ClassObject theModuleType() { result.asBuiltin() = Builtin::special("ModuleType") }
 
-/** The class of generators */
+/** Gets the class of generators */
 ClassObject theGeneratorType() { result.asBuiltin() = Builtin::special("generator") }
 
-/** The builtin class 'TypeError' */
+/** Gets the builtin class 'TypeError' */
 ClassObject theTypeErrorType() { result.asBuiltin() = Builtin::special("TypeError") }
 
-/** The builtin class 'AttributeError' */
+/** Gets the builtin class 'AttributeError' */
 ClassObject theAttributeErrorType() { result.asBuiltin() = Builtin::special("AttributeError") }
 
-/** The builtin class 'KeyError' */
+/** Gets the builtin class 'KeyError' */
 ClassObject theKeyErrorType() { result.asBuiltin() = Builtin::special("KeyError") }
 
-/** The builtin class of bound methods */
+/** Gets the builtin class of bound methods */
 pragma[noinline]
 ClassObject theBoundMethodType() { result.asBuiltin() = Builtin::special("MethodType") }
 
-/** The builtin class of builtin properties */
+/** Gets the builtin class of builtin properties */
 ClassObject theGetSetDescriptorType() {
   result.asBuiltin() = Builtin::special("GetSetDescriptorType")
 }
 
-/** The method descriptor class */
+/** Gets the method descriptor class */
 ClassObject theMethodDescriptorType() {
   result.asBuiltin() = Builtin::special("MethodDescriptorType")
 }
 
-/** The class of builtin properties */
+/** Gets the class of builtin properties */
 ClassObject theBuiltinPropertyType() {
   /* This is CPython specific */
   result.isC() and
   result.getName() = "getset_descriptor"
 }
 
-/** The builtin class 'IOError' */
+/** Gets the builtin class 'IOError' */
 ClassObject theIOErrorType() { result = Object::builtin("IOError") }
 
-/** The builtin class 'super' */
+/** Gets the builtin class 'super' */
 ClassObject theSuperType() { result = Object::builtin("super") }
 
-/** The builtin class 'StopIteration' */
+/** Gets the builtin class 'StopIteration' */
 ClassObject theStopIterationType() { result = Object::builtin("StopIteration") }
 
-/** The builtin class 'NotImplementedError' */
+/** Gets the builtin class 'NotImplementedError' */
 ClassObject theNotImplementedErrorType() { result = Object::builtin("NotImplementedError") }

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

@@ -138,7 +138,7 @@ class Object extends @py_object {
   }
 
   /**
-   * The Boolean value of this object if it always evaluates to true or false.
+   * Gets the Boolean value of this object if it always evaluates to true or false.
    * For example:
    *     false for None, true for 7 and no result for int(x)
    */
@@ -358,34 +358,34 @@ class ListObject extends SequenceObject {
   }
 }
 
-/** The `builtin` module */
+/** Gets the `builtin` module */
 BuiltinModuleObject theBuiltinModuleObject() { result.asBuiltin() = Builtin::builtinModule() }
 
-/** The `sys` module */
+/** Gets the `sys` module */
 BuiltinModuleObject theSysModuleObject() { result.asBuiltin() = Builtin::special("sys") }
 
 /** DEPRECATED -- Use `Object::builtin(name)` instead. */
 deprecated Object builtin_object(string name) { result = Object::builtin(name) }
 
-/** The built-in object None */
+/** Gets the built-in object None */
 Object theNoneObject() { result.asBuiltin() = Builtin::special("None") }
 
-/** The built-in object True */
+/** Gets the built-in object True */
 Object theTrueObject() { result.asBuiltin() = Builtin::special("True") }
 
-/** The built-in object False */
+/** Gets the built-in object False */
 Object theFalseObject() { result.asBuiltin() = Builtin::special("False") }
 
-/** The NameError class */
+/** Gets the NameError class */
 Object theNameErrorType() { result = Object::builtin("NameError") }
 
-/** The StandardError class */
+/** Gets the StandardError class */
 Object theStandardErrorType() { result = Object::builtin("StandardError") }
 
-/** The IndexError class */
+/** Gets the IndexError class */
 Object theIndexErrorType() { result = Object::builtin("IndexError") }
 
-/** The LookupError class */
+/** Gets the LookupError class */
 Object theLookupErrorType() { result = Object::builtin("LookupError") }
 
 /** DEPRECATED -- Use `Object::quitter(name)` instead. */
@@ -400,13 +400,13 @@ deprecated Object theEmptyTupleObject() { result = TupleObject::empty() }
 module Object {
   Object builtin(string name) { result.asBuiltin() = Builtin::builtin(name) }
 
-  /** The named quitter object (quit or exit) in the builtin namespace */
+  /** Gets the named quitter object (quit or exit) in the builtin namespace */
   Object quitter(string name) {
     (name = "quit" or name = "exit") and
     result = builtin(name)
   }
 
-  /** The builtin object `NotImplemented`. Not be confused with `NotImplementedError`. */
+  /** Gets the builtin object `NotImplemented`. Not be confused with `NotImplementedError`. */
   Object notImplemented() { result = builtin("NotImplemented") }
 }
 

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

@@ -2,10 +2,10 @@ import python
 import semmle.python.web.Http
 import semmle.python.types.Extensions
 
-/** The bottle module */
+/** Gets the bottle module */
 deprecated ModuleValue theBottleModule() { result = Module::named("bottle") }
 
-/** The bottle.Bottle class */
+/** Gets the bottle.Bottle class */
 deprecated ClassValue theBottleClass() { result = theBottleModule().attr("Bottle") }
 
 /**

python/ql/lib/semmle/python/web/falcon/General.qll

@@ -1,7 +1,7 @@
 import python
 import semmle.python.web.Http
 
-/** The falcon API class */
+/** Gets the falcon API class */
 deprecated ClassValue theFalconAPIClass() { result = Value::named("falcon.API") }
 
 /** Holds if `route` is routed to `resource` */

python/ql/lib/semmle/python/web/flask/General.qll

@@ -2,10 +2,10 @@ import python
 import semmle.python.web.Http
 import semmle.python.web.flask.Response
 
-/** The flask app class */
+/** Gets the flask app class */
 deprecated ClassValue theFlaskClass() { result = Value::named("flask.Flask") }
 
-/** The flask MethodView class */
+/** Gets the flask MethodView class */
 deprecated ClassValue theFlaskMethodViewClass() { result = Value::named("flask.views.MethodView") }
 
 deprecated ClassValue theFlaskReponseClass() { result = Value::named("flask.Response") }

python/ql/src/Exceptions/UnguardedNextInGenerator.ql

@@ -32,7 +32,11 @@ predicate guarded_not_empty_sequence(EssaVariable sequence) {
   sequence.getDefinition() instanceof EssaEdgeRefinement
 }
 
-/** The pattern `next(iter(x))` is often used where `x` is known not be empty. Check for that. */
+/**
+ * Holds if `iterator` is not exhausted.
+ *
+ * The pattern `next(iter(x))` is often used where `x` is known not be empty. Check for that.
+ */
 predicate iter_not_exhausted(EssaVariable iterator) {
   exists(EssaVariable sequence |
     call_to_iter(iterator.getDefinition().(AssignmentDefinition).getValue(), sequence) and

python/ql/src/Imports/DeprecatedModule.ql

@@ -13,6 +13,9 @@
 import python
 
 /**
+ * Gets the name of a deprecated module (for a particular version of Python) and the name of a suggested
+ * replacement.
+ *
  * The module `name` was deprecated in Python version `major`.`minor`,
  * and module `instead` should be used instead (or `instead = "no replacement"`)
  */

python/ql/src/Lexical/CommentedOutCode.qll

@@ -178,7 +178,7 @@ class CommentedOutCodeBlock extends @py_comment {
   /** Gets a textual representation of this element. */
   string toString() { result = "Commented out code" }
 
-  /** Whether this commented-out code block contains the comment c */
+  /** Holds if this commented-out code block contains the comment c */
   predicate contains(Comment c) {
     this = c
     or
@@ -189,7 +189,7 @@ class CommentedOutCodeBlock extends @py_comment {
     )
   }
 
-  /** The length of this comment block (in comments) */
+  /** Gets the length of this comment block (in comments) */
   int length() { result = count(Comment c | this.contains(c)) }
 
   /**

python/ql/src/Security/CWE-022/TarSlip.ql

@@ -122,7 +122,7 @@ class ExtractMembersSink extends TaintSink {
 class TarFileInfoSanitizer extends Sanitizer {
   TarFileInfoSanitizer() { this = "TarInfo sanitizer" }
 
-  /** The test `if <path_sanitizing_test>:` clears taint on its `false` edge. */
+  /* The test `if <path_sanitizing_test>:` clears taint on its `false` edge. */
   override predicate sanitizingEdge(TaintKind taint, PyEdgeRefinement test) {
     taint instanceof TarFileInfo and
     clears_taint_on_false_edge(test.getTest(), test.getSense())

python/ql/src/Security/CWE-327/TlsLibraryModel.qll

@@ -85,7 +85,7 @@ abstract class TlsLibrary extends string {
   bindingset[this]
   TlsLibrary() { any() }
 
-  /** The name of a specific protocol version. */
+  /** Gets the name of a specific protocol version. */
   abstract string specific_version_name(ProtocolVersion version);
 
   /** Gets a name, which is a member of `version_constants`, that can be used to specify the protocol family `family`. */

python/ql/src/Variables/Definition.qll

@@ -5,12 +5,12 @@ import python
  */
 class Definition extends NameNode, DefinitionNode {
   /**
-   * The variable defined by this control-flow node.
+   * Gets the variable defined by this control-flow node.
    */
   Variable getVariable() { this.defines(result) }
 
   /**
-   * The SSA variable corresponding to the current definition. Since SSA variables
+   * Gets the SSA variable corresponding to the current definition. Since SSA variables
    * are only generated for definitions with at least one use, not all definitions
    * will have an SSA variable.
    */
@@ -67,7 +67,7 @@ class Definition extends NameNode, DefinitionNode {
   }
 
   /**
-   * An immediate re-definition of this definition's variable.
+   * Gets an immediate re-definition of this definition's variable.
    */
   Definition getARedef() {
     result != this and

python/ql/src/Variables/MultiplyDefined.ql

@@ -47,6 +47,8 @@ predicate simple_literal(Expr e) {
 }
 
 /**
+ * Holds if the redefinition is uninteresting.
+ *
  * A multiple definition is 'uninteresting' if it sets a variable to a
  * simple literal before reassigning it.
  * x = None

python/ql/src/analysis/DefinitionTracking.qll

@@ -468,9 +468,9 @@ Definition getUniqueDefinition(Expr use) {
 }
 
 /** Helper class to get suitable locations for attributes */
-class NiceLocationExpr extends @py_expr {
+class NiceLocationExpr extends Expr {
   /** Gets a textual representation of this element. */
-  string toString() { result = this.(Expr).toString() }
+  override string toString() { result = this.(Expr).toString() }
 
   /**
    * Holds if this element is at the specified location.

python/ql/src/analysis/ImportFailure.ql

@@ -58,7 +58,7 @@ predicate ok_to_fail(ImportExpr ie) {
   os_specific_import(ie) != get_os()
 }
 
-class VersionTest extends @py_flow_node {
+class VersionTest extends ControlFlowNode {
   VersionTest() {
     exists(string name |
       name.matches("%version%") and
@@ -66,7 +66,7 @@ class VersionTest extends @py_flow_node {
     )
   }
 
-  string toString() { result = "VersionTest" }
+  override string toString() { result = "VersionTest" }
 }
 
 /** A guard on the version of the Python interpreter */

python/ql/src/printAst.ql

@@ -12,7 +12,7 @@ import semmle.python.PrintAst
 import analysis.DefinitionTracking
 
 /**
- * The source file to generate an AST from.
+ * Gets the source file that will be used to generate the AST.
  */
 external string selectedSourceFile();
 

python/ql/src/semmle/python/functions/ModificationOfParameterWithDefaultCustomizations.qll

@@ -81,7 +81,7 @@ module ModificationOfParameterWithDefault {
   }
 
   /**
-   * A name of a list function that modifies the list.
+   * Gets the name of a list function that modifies the list.
    * See https://docs.python.org/3/tutorial/datastructures.html#more-on-lists
    */
   string list_modifying_method() {
@@ -89,7 +89,7 @@ module ModificationOfParameterWithDefault {
   }
 
   /**
-   * A name of a dict function that modifies the dict.
+   * Gets the name of a dict function that modifies the dict.
    * See https://docs.python.org/3/library/stdtypes.html#dict
    */
   string dict_modifying_method() { result in ["clear", "pop", "popitem", "setdefault", "update"] }

python/ql/test/TestUtilities/InlineExpectationsTest.qll

@@ -124,7 +124,7 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Like `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */

python/ql/test/library-tests/examples/custom-sanitizer/Taint.qll

@@ -13,11 +13,12 @@ class SimpleSource extends TaintSource {
 class MySimpleSanitizer extends Sanitizer {
   MySimpleSanitizer() { this = "MySimpleSanitizer" }
 
-  /**
+  /*
    * The test `if is_safe(arg):` sanitizes `arg` on its `true` edge.
    *
    * Can't handle `if not is_safe(arg):` :\ that's why it's called MySimpleSanitizer
    */
+
   override predicate sanitizingEdge(TaintKind taint, PyEdgeRefinement test) {
     taint instanceof ExternalStringKind and
     exists(CallNode call | test.getTest() = call and test.getSense() = true |
@@ -30,7 +31,7 @@ class MySimpleSanitizer extends Sanitizer {
 class MySanitizerHandlingNot extends Sanitizer {
   MySanitizerHandlingNot() { this = "MySanitizerHandlingNot" }
 
-  /** The test `if is_safe(arg):` sanitizes `arg` on its `true` edge. */
+  /** Holds if the test `if is_safe(arg):` sanitizes `arg` on its `true` edge. */
   override predicate sanitizingEdge(TaintKind taint, PyEdgeRefinement test) {
     taint instanceof ExternalStringKind and
     clears_taint_on_true(test.getTest(), test.getSense(), test)

ruby/ql/test/TestUtilities/InlineExpectationsTest.qll

@@ -124,7 +124,7 @@ abstract class InlineExpectationsTest extends string {
   abstract predicate hasActualResult(Location location, string element, string tag, string value);
 
   /**
-   * Like `hasActualResult`, but returns results that do not require a matching annotation.
+   * Holds similarly to `hasActualResult`, but returns results that do not require a matching annotation.
    * A failure will still arise if there is an annotation that does not match any results, but not vice versa.
    * Override this predicate to specify optional results.
    */