Merge pull request #8336 from tausbn/python-fix-a-bunch-of-ql-warnings

Python: Fix a bunch of QL warnings

Author: tausbn

cpp/ql/test/TestUtilities/InlineExpectationsTest.qll

@@ -124,7 +124,9 @@ 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 if there is an optional result on the specified location.
+   *
+   * This is similar 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,9 @@ 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 if there is an optional result on the specified location.
+   *
+   * This is similar 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,9 @@ 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 if there is an optional result on the specified location.
+   *
+   * This is similar 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/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/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/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 {
@@ -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.
@@ -685,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") }
@@ -728,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. */
-library class AugLoad extends AugLoad_ { }
+/** 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/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)