Python: Apply suggestions from code review

Co-authored-by: yoff <lerchedahl@gmail.com>

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);
 
   /**
-   * Holds similarly to `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);
 
   /**
-   * Holds similarly to `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);
 
   /**
-   * Holds similarly to `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/dataflow/new/internal/DataFlowPrivate.qll

@@ -1619,7 +1619,7 @@ import IterableUnpacking
  */
 module MatchUnpacking {
   /**
-   * Holds when there is flow from the subject `nodeFrom` to the case `nodeTo` of a `match` statement.
+   * Holds when there is flow from the subject `nodeFrom` to the (top-level) pattern `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/frameworks/Aiomysql.qll

@@ -15,7 +15,7 @@ private module Aiomysql {
   private import semmle.python.internal.Awaited
 
   /**
-   * Gets the `ConnectionPool` that is created when the result of `aiomysql.create_pool()` is awaited.
+   * Gets a `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 {
   }
 
   /**
-   * Gets the `Connection` that is created when
+   * Gets a `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 {
   }
 
   /**
-   * Gets the `Cursor` that is created when
+   * Gets a `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 {
   }
 
   /**
-   * Gets the `Engine` that is created when the result of calling `aiomysql.sa.create_engine` is awaited.
+   * Gets an `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 {
   }
 
   /**
-   * Gets the `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
+   * Gets an `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
 
   /**
-   * Gets the `ConnectionPool` that is created when the result of `aiopg.create_pool()` is awaited.
+   * Gets a `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 {
   }
 
   /**
-   * Gets the `Connection` that is created when
+   * Gets a `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 {
   }
 
   /**
-   * Gets the `Cursor` that is created when
+   * Gets a `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 {
   }
 
   /**
-   * Gets the `Engine` that is created when the result of calling `aiopg.sa.create_engine` is awaited.
+   * Gets an `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 {
   }
 
   /**
-   * Gets the `SAConnection` that is created when the result of calling `aquire` on an `Engine` is awaited.
+   * Gets an `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
 
-  /** Gets the `ConnectionPool` that is created when the result of `asyncpg.create_pool()` is awaited. */
+  /** Gets a `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()
   }
 
   /**
-   * Gets the `Connection` that is created when
+   * Gets a `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/types/ClassObject.qll

@@ -447,7 +447,7 @@ ClassObject theBuiltinFunctionType() {
 /** Gets the class of Python functions */
 ClassObject thePyFunctionType() { result.asBuiltin() = Builtin::special("FunctionType") }
 
-/** Gets thGets the builtin class 'classmethod' */
+/** Gets the builtin class 'classmethod' */
 ClassObject theClassMethodType() { result.asBuiltin() = Builtin::special("ClassMethod") }
 
 /** Gets the builtin class 'staticmethod' */

python/ql/src/Imports/DeprecatedModule.ql

@@ -13,10 +13,7 @@
 import python
 
 /**
- * Gets the name of a deprecated module (for a particular version of Python) and the name of a suggested
+ * Holds if the module `name` was deprecated in Python version `major`.`minor`,
- * replacement.
- *
- * The module `name` was deprecated in Python version `major`.`minor`,
  * and module `instead` should be used instead (or `instead = "no replacement"`)
  */
 predicate deprecated_module(string name, string instead, int major, int minor) {

python/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);
 
   /**
-   * Holds similarly to `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/tools/recorded-call-graph-metrics/ql/lib/RecordedCalls.qll

@@ -162,7 +162,7 @@ private Builtin traverse_qualname(Builtin parent, string qualname) {
 }
 
 /**
- * Arecorded call where we can identify both the `call` and the `callee` uniquely.
+ * A recorded call where we can identify both the `call` and the `callee` uniquely.
  */
 class IdentifiedRecordedCall extends XMLRecordedCall {
   IdentifiedRecordedCall() {

ruby/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);
 
   /**
-   * Holds similarly to `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.
    */