Python: Apply suggestions from documentation review.

Co-authored-by: Felicity Chapman <felicitymay@github.com>
Co-authored-by: Rasmus Wriedt Larsen <rasmuswriedtlarsen@gmail.com>

Author: 3 people

python/ql/src/Expressions/CallArgs.qll

@@ -1,4 +1,4 @@
-/** INTERNAL - Methods used for queries relating to the correct invocation of functions. */
+/** INTERNAL - Methods used by queries that test whether functions are invoked correctly.  */
 
 import python
 import Testing.Mox

python/ql/src/Expressions/Formatting/AdvancedFormatting.qll

@@ -52,7 +52,7 @@ library class PossibleAdvancedFormatString extends StrConst {
     predicate isExplicitlyNumbered() { exists(this.fieldId(_, _).toInt()) }
 }
 
-/** Holds if there is a sequence of `{` braces in `fmt` of length `len` beginning at index `index`. */
+/** Holds if the formatting string `fmt` contains a sequence of braces `{` of length `len`, beginning at index `index`. */
 predicate brace_sequence(PossibleAdvancedFormatString fmt, int index, int len) {
     exists(string text | text = fmt.getText() |
         text.charAt(index) = "{" and not text.charAt(index - 1) = "{" and len = 1
@@ -63,12 +63,12 @@ predicate brace_sequence(PossibleAdvancedFormatString fmt, int index, int len) {
     )
 }
 
-/** Holds if index `index` in the format string `fmt` contains an escaped `{`. */
+/** Holds if index `index` in the format string `fmt` contains an escaped brace `{`. */
 predicate escaped_brace(PossibleAdvancedFormatString fmt, int index) {
     exists(int len | brace_sequence(fmt, index, len) | len % 2 = 0)
 }
 
-/** Holds if index `index` in the format string `fmt` contains a left curly brace that acts as an escape. */
+/** Holds if index `index` in the format string `fmt` contains a left brace `{` that acts as an escape character. */
 predicate escaping_brace(PossibleAdvancedFormatString fmt, int index) {
     escaped_brace(fmt, index + 1)
 }
@@ -114,7 +114,7 @@ class AdvancedFormatString extends PossibleAdvancedFormatString {
     AdvancedFormatString() { advanced_format_call(_, this, _) }
 }
 
-/** A string formatting operation using the `format` method. */
+/** A string formatting operation that uses the `format` method. */
 class AdvancedFormattingCall extends Call {
     AdvancedFormattingCall() { advanced_format_call(this, _, _) }
 

python/ql/src/Expressions/IsComparisons.qll

@@ -1,8 +1,8 @@
-/** INTERNAL - Helper predicates for queries concerning comparison of objects using `is`. */
+/** INTERNAL - Helper predicates for queries that inspect the comparison of objects using `is`. */
 
 import python
 
-/** Holds if `comp` uses `is` or `is not` (represented as `op`) to compare its `left` and `right` arguments. */
+/** Holds if the comparison `comp` uses `is` or `is not` (represented as `op`) to compare its `left` and `right` arguments. */
 predicate comparison_using_is(Compare comp, ControlFlowNode left, Cmpop op, ControlFlowNode right) {
     exists(CompareNode fcomp | fcomp = comp.getAFlowNode() |
         fcomp.operands(left, op, right) and
@@ -41,7 +41,7 @@ predicate invalid_to_use_is_portably(ClassValue c) {
     not probablySingleton(c)
 }
 
-/** Holds if `f` points to either `True`, `False`, or `None`. */
+/** Holds if the control flow node `f` points to either `True`, `False`, or `None`. */
 predicate simple_constant(ControlFlowNode f) {
     exists(Value val | f.pointsTo(val) |
         val = Value::named("True") or val = Value::named("False") or val = Value::named("None")
@@ -102,8 +102,7 @@ private predicate comparison_one_type(Compare comp, Cmpop op, ClassValue cls) {
 }
 
 /**
- * Holds if the comparison `comp` (with operator `op`) is an invalid comparison using `is` or `is not`
- * when applied to instances of the class `cls`.
+* Holds if using `is` or `is not` as the operator `op` in the comparison `comp` would be invalid when applied to the class `cls`.
  */
 predicate invalid_portable_is_comparison(Compare comp, Cmpop op, ClassValue cls) {
     // OK to use 'is' when defining '__eq__'

python/ql/src/Expressions/RedundantComparison.qll

@@ -1,4 +1,4 @@
-/** Helper functions for queries having to do with redundant comparisons. */
+/** Helper functions for queries that test redundant comparisons. */
 
 import python
 
@@ -11,7 +11,7 @@ class RedundantComparison extends Compare {
         )
     }
 
-    /** Holds if this comparison could be due to a missing `self.`, for example
+    /** Holds if this comparison could be redundant due to a missing `self.`, for example
      * ```python
      * foo == foo
      * ```

python/ql/src/Resources/FileOpen.qll

@@ -130,7 +130,7 @@ predicate function_should_close_parameter(Function func) {
     )
 }
 
-/** Holds if `f` opens a file, either directly or indirectly. */
+/** Holds if the function `f` opens a file, either directly or indirectly. */
 predicate function_opens_file(FunctionValue f) {
     f = Value::named("open")
     or
@@ -145,7 +145,7 @@ predicate function_opens_file(FunctionValue f) {
     )
 }
 
-/** Holds if `v` refers to a file opened at `open` which is subsequently returned from a function. */
+/** Holds if the variable `v` refers to a file opened at `open` which is subsequently returned from a function. */
 predicate file_is_returned(EssaVariable v, ControlFlowNode open) {
     exists(NameNode n, Return ret |
         var_is_open(v, open) and

python/ql/src/semmle/python/Class.qll

@@ -119,10 +119,10 @@ class Class extends Class_, Scope, AstNode {
     /** Gets the name used to define this class */
     override string getName() { result = Class_.super.getName() }
 
-    /** Whether this expression may have a side effect (as determined purely from its syntax). */
+    /** Holds if this expression may have a side effect (as determined purely from its syntax). */
     predicate hasSideEffects() { any() }
 
-    /** Whether this is probably a mixin (has 'mixin' or similar in name or docstring) */
+    /** Holds if this is probably a mixin (has 'mixin' or similar in name or docstring) */
     predicate isProbableMixin() {
         (
             this.getName().toLowerCase().matches("%mixin%")