Merge pull request github#13263 from github/ginsbach/DocumentAnnotationsForParameterised

update QL specification on annotations for parameterised modules

Author: ginsbach

docs/codeql/ql-language-reference/ql-language-specification.rst

@@ -704,12 +704,14 @@ Various kinds of syntax can have *annotations* applied to them. Annotations are
    simpleAnnotation ::= "abstract"
                     |   "cached"
                     |   "external"
+                    |   "extensible"
                     |   "final"
                     |   "transient"
                     |   "library"
                     |   "private"
                     |   "deprecated"
                     |   "override"
+                    |   "additional"
                     |   "query"
 
    argsAnnotation ::= "pragma" "[" ("inline" | "inline_late" | "noinline" | "nomagic" | "noopt" | "assume_small_delta") "]"
@@ -725,31 +727,36 @@ Simple annotations
 
 The following table summarizes the syntactic constructs which can be marked with each annotation in a valid program; for example, an ``abstract`` annotation preceding a character is invalid.
 
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| Annotation     | Classes | Characters | Member predicates | Non-member predicates | Imports | Fields | Modules | Aliases |
-+================+=========+============+===================+=======================+=========+========+=========+=========+
-| ``abstract``   | yes     |            | yes               |                       |         |        |         |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``cached``     | yes     | yes        | yes               | yes                   |         |        | yes     |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``external``   |         |            |                   | yes                   |         |        |         |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``final``      | yes     |            | yes               |                       |         | yes    |         | yes     |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``transient``  |         |            |                   | yes                   |         |        |         |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``library``    | yes     |            |                   |                       |         |        |         |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``private``    | yes     |            | yes               | yes                   | yes     | yes    | yes     | yes     |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``deprecated`` | yes     |            | yes               | yes                   |         | yes    | yes     | yes     |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``override``   |         |            | yes               |                       |         | yes    |         |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| ``query``      |         |            |                   | yes                   |         |        |         | yes     |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| Annotation     | Classes | Characters | Member predicates | Non-member predicates | Imports | Fields | Modules | Aliases | Signatures |
++================+=========+============+===================+=======================+=========+========+=========+=========+============+
+| ``abstract``   | yes     |            | yes               |                       |         |        |         |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``cached``     | yes     | yes        | yes               | yes                   |         |        | yes     |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``external``   |         |            |                   | yes                   |         |        |         |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``extensible`` |         |            |                   | yes                   |         |        |         |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``final``      | yes     |            | yes               |                       |         | yes    |         | (yes)   |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``transient``  |         |            |                   | yes                   |         |        |         |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``library``    | (yes)   |            |                   |                       |         |        |         |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``private``    | yes     |            | yes               | yes                   | yes     | yes    | yes     | yes     | yes        |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``deprecated`` | yes     |            | yes               | yes                   |         | yes    | yes     | yes     | yes        |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``override``   |         |            | yes               |                       |         | yes    |         |         |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``additional`` | yes     |            |                   | yes                   |         |        | yes     | yes     | yes        |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| ``query``      |         |            |                   | yes                   |         |        |         | yes     |            |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
 
 The ``library`` annotation is only usable within a QLL file, not a QL file.
+The ``final`` annotation is usable on type aliases, but not on module aliases and predicate aliases.
 
 Annotations on aliases apply to the name introduced by the alias. An alias may, for example, have different privacy to the name it aliases.
 
@@ -799,11 +806,13 @@ Binding sets are checked by the QL compiler in the following way:
 
 A predicate may have several different binding sets, which can be stated by using multiple ``bindingset`` annotations on the same predicate.
 
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
-| Pragma         | Classes | Characters | Member predicates | Non-member predicates | Imports | Fields | Modules | Aliases |
-+================+=========+============+===================+=======================+=========+========+=========+=========+
-| ``bindingset`` |         | yes        | yes               | yes                   |         |        |         |         |
-+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+| Pragma         | Classes | Characters | Member predicates | Non-member predicates | Imports | Fields | Modules | Aliases | Signatures |
++================+=========+============+===================+=======================+=========+========+=========+=========+============+
+| ``bindingset`` |         | yes        | yes               | yes                   |         |        |         |         | (yes)      |
++----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
+
+The ``bindingset`` pragma is usable with type signatures and predicate signatures, but not with module signatures.
 
 QLDoc
 -----
@@ -2159,12 +2168,14 @@ The complete grammar for QL is as follows:
    simpleAnnotation ::= "abstract"
                     |   "cached"
                     |   "external"
+                    |   "extensible"
                     |   "final"
                     |   "transient"
                     |   "library"
                     |   "private"
                     |   "deprecated"
                     |   "override"
+                    |   "additional"
                     |   "query"
 
    argsAnnotation ::= "pragma" "[" ("inline" | "inline_late" | "noinline" | "nomagic" | "noopt" | "assume_small_delta") "]"