Python: Reword QLDoc for class modeling with type-tracking

As discussed in https://github.com/github/codeql/pull/4797#discussion_r542423387

python/.vscode/ql.code-snippets

@@ -321,13 +321,13 @@
             "      DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }",
             "",
             "      /**",
-            "       * A source of an instance of `$1.$2`.",
+            "       * A source of instances of `$1.$2`, extend this class to model new instances.",
             "       *",
-            "       * This can include instantiation of the class, return value from function",
+            "       * This can include instantiations of the class, return values from function",
-            "       * calls, or a special parameter that will be set when functions are call by external",
+            "       * calls, or a special parameter that will be set when functions are called by an external",
             "       * library.",
             "       *",
-            "       * Use `$2::instance()` predicate to get references to instances of `$1.$2`.",
+            "       * Use the predicate `$2::instance()` to get references to instances of `$1.$2`.",
             "       */",
             "      abstract class InstanceSource extends DataFlow::Node { }",
             "",

python/ql/src/semmle/python/frameworks/Django.qll

@@ -540,9 +540,9 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.request.HttpRequest`.
+           * A source of instances of `django.http.request.HttpRequest`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
            * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
@@ -646,13 +646,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponse`.
+           * A source of instances of `django.http.response.HttpResponse`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponse::instance()` predicate to get references to instances of `django.http.response.HttpResponse`.
+           * Use the predicate `HttpResponse::instance()` to get references to instances of `django.http.response.HttpResponse`.
            */
           abstract class InstanceSource extends HTTP::Server::HttpResponse::Range, DataFlow::Node {
           }
@@ -716,13 +716,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseRedirect`.
+           * A source of instances of `django.http.response.HttpResponseRedirect`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseRedirect::instance()` predicate to get references to instances of `django.http.response.HttpResponseRedirect`.
+           * Use the predicate `HttpResponseRedirect::instance()` to get references to instances of `django.http.response.HttpResponseRedirect`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -782,13 +782,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponsePermanentRedirect`.
+           * A source of instances of `django.http.response.HttpResponsePermanentRedirect`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponsePermanentRedirect::instance()` predicate to get references to instances of `django.http.response.HttpResponsePermanentRedirect`.
+           * Use the predicate `HttpResponsePermanentRedirect::instance()` to get references to instances of `django.http.response.HttpResponsePermanentRedirect`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -849,13 +849,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseNotModified`.
+           * A source of instances of `django.http.response.HttpResponseNotModified`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseNotModified::instance()` predicate to get references to instances of `django.http.response.HttpResponseNotModified`.
+           * Use the predicate `HttpResponseNotModified::instance()` to get references to instances of `django.http.response.HttpResponseNotModified`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -910,13 +910,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseBadRequest`.
+           * A source of instances of `django.http.response.HttpResponseBadRequest`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseBadRequest::instance()` predicate to get references to instances of `django.http.response.HttpResponseBadRequest`.
+           * Use the predicate `HttpResponseBadRequest::instance()` to get references to instances of `django.http.response.HttpResponseBadRequest`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -973,13 +973,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseNotFound`.
+           * A source of instances of `django.http.response.HttpResponseNotFound`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseNotFound::instance()` predicate to get references to instances of `django.http.response.HttpResponseNotFound`.
+           * Use the predicate `HttpResponseNotFound::instance()` to get references to instances of `django.http.response.HttpResponseNotFound`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1036,13 +1036,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseForbidden`.
+           * A source of instances of `django.http.response.HttpResponseForbidden`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseForbidden::instance()` predicate to get references to instances of `django.http.response.HttpResponseForbidden`.
+           * Use the predicate `HttpResponseForbidden::instance()` to get references to instances of `django.http.response.HttpResponseForbidden`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1099,13 +1099,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseNotAllowed`.
+           * A source of instances of `django.http.response.HttpResponseNotAllowed`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseNotAllowed::instance()` predicate to get references to instances of `django.http.response.HttpResponseNotAllowed`.
+           * Use the predicate `HttpResponseNotAllowed::instance()` to get references to instances of `django.http.response.HttpResponseNotAllowed`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1163,13 +1163,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseGone`.
+           * A source of instances of `django.http.response.HttpResponseGone`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseGone::instance()` predicate to get references to instances of `django.http.response.HttpResponseGone`.
+           * Use the predicate `HttpResponseGone::instance()` to get references to instances of `django.http.response.HttpResponseGone`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1226,13 +1226,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.HttpResponseServerError`.
+           * A source of instances of `django.http.response.HttpResponseServerError`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `HttpResponseServerError::instance()` predicate to get references to instances of `django.http.response.HttpResponseServerError`.
+           * Use the predicate `HttpResponseServerError::instance()` to get references to instances of `django.http.response.HttpResponseServerError`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1289,13 +1289,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.JsonResponse`.
+           * A source of instances of `django.http.response.JsonResponse`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `JsonResponse::instance()` predicate to get references to instances of `django.http.response.JsonResponse`.
+           * Use the predicate `JsonResponse::instance()` to get references to instances of `django.http.response.JsonResponse`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1355,13 +1355,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.StreamingHttpResponse`.
+           * A source of instances of `django.http.response.StreamingHttpResponse`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `StreamingHttpResponse::instance()` predicate to get references to instances of `django.http.response.StreamingHttpResponse`.
+           * Use the predicate `StreamingHttpResponse::instance()` to get references to instances of `django.http.response.StreamingHttpResponse`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 
@@ -1418,13 +1418,13 @@ private module Django {
           DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
           /**
-           * A source of an instance of `django.http.response.FileResponse`.
+           * A source of instances of `django.http.response.FileResponse`, extend this class to model new instances.
            *
-           * This can include instantiation of the class, return value from function
+           * This can include instantiations of the class, return values from function
-           * calls, or a special parameter that will be set when functions are call by external
+           * calls, or a special parameter that will be set when functions are called by an external
            * library.
            *
-           * Use `FileResponse::instance()` predicate to get references to instances of `django.http.response.FileResponse`.
+           * Use the predicate `FileResponse::instance()` to get references to instances of `django.http.response.FileResponse`.
            */
           abstract class InstanceSource extends HttpResponse::InstanceSource, DataFlow::Node { }
 

python/ql/src/semmle/python/frameworks/Fabric.qll

@@ -281,13 +281,13 @@ private module FabricV2 {
         DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
         /**
-         * A source of an instance of `fabric.connection.Connection`.
+         * A source of instances of `fabric.connection.Connection`, extend this class to model new instances.
          *
-         * This can include instantiation of the class, return value from function
+         * This can include instantiations of the class, return values from function
          * calls, or a special parameter that will be set when functions are called by an external
          * library.
          *
-         * Use `Connection::instance()` predicate to get references to instances of `fabric.connection.Connection`.
+         * Use the predicate `Connection::instance()` to get references to instances of `fabric.connection.Connection`.
          */
         abstract class InstanceSource extends DataFlow::Node { }
 
@@ -457,7 +457,7 @@ private module FabricV2 {
        */
       module Group {
         /**
-         * A source of an instance of a subclass of `fabric.group.Group`
+         * A source of instances of a subclass of `fabric.group, extend this class to model new instances.Group`
          *
          * This can include instantiation of a class, return value from function
          * calls, or a special parameter that will be set when functions are called by an external

python/ql/src/semmle/python/frameworks/Flask.qll

@@ -97,13 +97,13 @@ private module FlaskModel {
       DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
       /**
-       * A source of an instance of `flask.Flask`.
+       * A source of instances of `flask.Flask`, extend this class to model new instances.
        *
-       * This can include instantiation of the class, return value from function
+       * This can include instantiations of the class, return values from function
-       * calls, or a special parameter that will be set when functions are call by external
+       * calls, or a special parameter that will be set when functions are called by an external
        * library.
        *
-       * Use `Flask::instance()` predicate to get references to instances of `flask.Flask`.
+       * Use the predicate `Flask::instance()` to get references to instances of `flask.Flask`.
        */
       abstract class InstanceSource extends DataFlow::Node { }
 
@@ -207,13 +207,13 @@ private module FlaskModel {
     DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
     /**
-     * A source of an instance of `flask.Response`.
+     * A source of instances of `flask.Response`, extend this class to model new instances.
      *
-     * This can include instantiation of the class, return value from function
+     * This can include instantiations of the class, return values from function
-     * calls, or a special parameter that will be set when functions are call by external
+     * calls, or a special parameter that will be set when functions are called by an external
      * library.
      *
-     * Use `Response::instance()` predicate to get references to instances of `flask.Response`.
+     * Use the predicate `Response::instance()` to get references to instances of `flask.Response`.
      */
     abstract class InstanceSource extends HTTP::Server::HttpResponse::Range, DataFlow::Node { }
 

python/ql/src/semmle/python/frameworks/PEP249.qll

@@ -29,13 +29,13 @@ DataFlow::Node connect() { result = connect(DataFlow::TypeTracker::end()) }
  */
 module Connection {
   /**
-   * A source of an instance of `db.Connection`.
+   * A source of instances of `db.Connection`, extend this class to model new instances.
    *
-   * This can include instantiation of the class, return value from function
+   * This can include instantiations of the class, return values from function
    * calls, or a special parameter that will be set when functions are called by external
    * libraries.
    *
-   * Use `Connection::instance()` predicate to get references to instances of `db.Connection`.
+   * Use the predicate `Connection::instance()` to get references to instances of `db.Connection`.
    *
    * Extend this class if the module implementing PEP 249 offers more direct ways to obtain
    * a connection than going through `connect`.

python/ql/src/semmle/python/frameworks/Stdlib.qll

@@ -1116,13 +1116,13 @@ private module Stdlib {
       DataFlow::Node classRef() { result = classRef(DataFlow::TypeTracker::end()) }
 
       /**
-       * A source of an instance of `cgi.FieldStorage`.
+       * A source of instances of `cgi.FieldStorage`, extend this class to model new instances.
        *
-       * This can include instantiation of the class, return value from function
+       * This can include instantiations of the class, return values from function
-       * calls, or a special parameter that will be set when functions are call by external
+       * calls, or a special parameter that will be set when functions are called by an external
        * library.
        *
-       * Use `FieldStorage::instance()` predicate to get references to instances of `cgi.FieldStorage`.
+       * Use the predicate `FieldStorage::instance()` to get references to instances of `cgi.FieldStorage`.
        */
       abstract class InstanceSource extends DataFlow::Node { }
 
@@ -1569,13 +1569,13 @@ private module Stdlib {
     }
 
     /**
-     * A source of an instance of the `BaseHTTPRequestHandler` class or any subclass.
+     * A source of instances of the `BaseHTTPRequestHandler` class or any subclass, extend this class to model new instances.
      *
-     * This can include instantiation of the class, return value from function
+     * This can include instantiations of the class, return values from function
-     * calls, or a special parameter that will be set when functions are call by external
+     * calls, or a special parameter that will be set when functions are called by an external
      * library.
      *
-     * Use `classname::instance()` predicate to get references to instances of the `BaseHTTPRequestHandler` class or any subclass.
+     * Use the predicate `classname::instance()` to get references to instances of the `BaseHTTPRequestHandler` class or any subclass.
      */
     abstract class InstanceSource extends DataFlow::Node { }
 

python/ql/src/semmle/python/frameworks/Werkzeug.qll

@@ -24,13 +24,13 @@ module Werkzeug {
        */
       module MultiDict {
         /**
-         * A source of an instance of `werkzeug.datastructures.MultiDict`.
+         * A source of instances of `werkzeug.datastructures.MultiDict`, extend this class to model new instances.
          *
-         * This can include instantiation of the class, return value from function
+         * This can include instantiations of the class, return values from function
-         * calls, or a special parameter that will be set when functions are call by external
+         * calls, or a special parameter that will be set when functions are called by an external
          * library.
          *
-         * Use `MultiDict::instance()` predicate to get references to instances of `werkzeug.datastructures.MultiDict`.
+         * Use the predicate `MultiDict::instance()` to get references to instances of `werkzeug.datastructures.MultiDict`.
          */
         abstract class InstanceSource extends DataFlow::Node { }
 
@@ -72,13 +72,13 @@ module Werkzeug {
        */
       module FileStorage {
         /**
-         * A source of an instance of `werkzeug.datastructures.FileStorage`.
+         * A source of instances of `werkzeug.datastructures.FileStorage`, extend this class to model new instances.
          *
-         * This can include instantiation of the class, return value from function
+         * This can include instantiations of the class, return values from function
          * calls, or a special parameter that will be set when functions are called by an external
          * library.
          *
-         * Use `FileStorage::instance()` predicate to get references to instances of `werkzeug.datastructures.FileStorage`.
+         * Use the predicate `FileStorage::instance()` to get references to instances of `werkzeug.datastructures.FileStorage`.
          */
         abstract class InstanceSource extends DataFlow::Node { }