Python: Fix up a bunch of function QLDoc

Author: tausbn

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)) }