Python: Fix up a bunch of function QLDoc

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"] }