Merge pull request #20571 from github/ginsbach/MoreAnnotationDocs

document `extensible` and `additional` in QL reference and spec

Author: ginsbach

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

@@ -97,13 +97,27 @@ own body, or they must inherit from another class that overrides ``isSource``:
       // doesn't need to override `isSource`, because it inherits it from ConfigA
     }
 
+.. index:: additional
+.. _additional:
+
+``additional``
+==============
+
+**Available for**: |classes|, |algebraic datatypes|, |type unions|, |non-member predicates|, |modules|, |aliases|, |signatures|
+
+The ``additional`` annotation can be used on declarations in explicit modules.
+All declarations that are not required by a module signature in modules that implement |module signatures| must be annotated with ``additional``.
+
+Omitting ``additional`` on such declarations, or using the annotation in any other context, will result in a compiler error.
+Other than that, the annotation has no effect.
+
 .. index:: cached
 .. _cached:
 
 ``cached``
 ==========
 
-**Available for**: |classes|, |algebraic datatypes|, |characteristic predicates|, |member predicates|, |non-member predicates|, |modules|
+**Available for**: |classes|, |algebraic datatypes|, |type unions|, |characteristic predicates|, |member predicates|, |non-member predicates|, |modules|
 
 The ``cached`` annotation indicates that an entity should be evaluated in its entirety and
 stored in the evaluation cache. All later references to this entity will use the 
@@ -126,7 +140,7 @@ body must also be annotated with ``cached``, otherwise a compiler error is repor
 ``deprecated``
 ==============
 
-**Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|
+**Available for**: |classes|, |algebraic datatypes|, |type unions|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|, |signatures|
 
 The ``deprecated`` annotation is applied to names that are outdated and scheduled for removal
 in a future release of QL.
@@ -151,6 +165,16 @@ For example, the name ``DataFlowNode`` is deprecated and has the following QLDoc
 
 This QLDoc comment appears when you use the name ``DataFlowNode`` in a QL editor.
 
+.. index:: extensible
+.. _extensible:
+
+``extensible``
+==============
+
+**Available for**: |non-member predicates|
+
+The ``extensible`` annotation is used to mark predicates that are populated at evaluation time through data extensions.
+
 .. index:: external
 .. _external:
 
@@ -235,7 +259,7 @@ warning.
 ``private``
 ===========
 
-**Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|
+**Available for**: |classes|, |algebraic datatypes|, |type unions|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|, |signatures|
 
 The ``private`` annotation is used to prevent names from being exported.
 
@@ -461,7 +485,7 @@ For more information, see ":ref:`monotonic-aggregates`."
 Binding sets
 ============
 
-**Available for**: |classes|, |characteristic predicates|, |member predicates|, |non-member predicates|
+**Available for**: |classes|, |characteristic predicates|, |member predicates|, |non-member predicates|, |predicate signatures|, |type signatures|
 
 ``bindingset[...]``
 -------------------
@@ -490,4 +514,9 @@ The ``bindingset`` annotation takes a comma-separated list of variables.
 .. |aliases|                   replace:: :ref:`aliases <aliases>`
 .. |type-aliases|              replace:: :ref:`type aliases <type-aliases>`
 .. |algebraic datatypes|       replace:: :ref:`algebraic datatypes <algebraic-datatypes>`
+.. |type unions|               replace:: :ref:`type unions <type-unions>`
 .. |expressions|               replace:: :ref:`expressions <expressions>`
+.. |signatures|                replace:: :ref:`signatures <signatures>`
+.. |predicate signatures|      replace:: :ref:`predicate signatures <predicate-signatures>`
+.. |type signatures|           replace:: :ref:`type signatures <type-signatures>`
+.. |module signatures|         replace:: :ref:`module signatures <module-signatures>`

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

@@ -36,7 +36,7 @@ Architecture
 
 A *QL program* consists of a query module defined in a QL file and a number of library modules defined in QLL files that it imports (see "`Import directives <#import-directives>`__"). The module in the QL file includes one or more queries (see "`Queries <#queries>`__"). A module may also include *import directives* (see "`Import directives <#import-directives>`__"), non-member predicates (see "`Non-member predicates <#non-member-predicates>`__"), class definitions (see "`Classes <#classes>`__"), and module definitions (see "`Modules <#modules>`__").
 
-QL programs are interpreted in the context of a *database* and a *library path* . The database provides a number of definitions: database types (see "`Types <#types>`__"), entities (see "`Values <#values>`__"), built-in predicates (see "`Built-ins <#built-ins>`__"), and the *database content* of built-in predicates and external predicates (see "`Evaluation <#evaluation>`__"). The library path is a sequence of file-system directories that hold QLL files.
+QL programs are interpreted in the context of a *database* and a *library path* . The database provides a number of definitions: database types (see "`Types <#types>`__"), entities (see "`Values <#values>`__"), built-in predicates (see "`Built-ins <#built-ins>`__"), and the *database content* of built-in predicates, external predicates, and extensible predicates (see "`Evaluation <#evaluation>`__"). The library path is a sequence of file-system directories that hold QLL files.
 
 A QL program can be *evaluated* (see "`Evaluation <#evaluation>`__") to produce a set of tuples of values (see "`Values <#values>`__").
 
@@ -935,6 +935,7 @@ When a predicate is a top-level clause in a module, it is called a non-member pr
 
 A valid non-member predicate can be annotated with ``additional``, ``cached``, ``deprecated``, ``extensible``, ``external``, ``transient``, ``private``, and ``query``.
 Note, the ``transient`` annotation can only be applied if the non-member predicate is also annotated with ``external``.
+Note, the annotations ``extensible`` and ``external`` cannot both be used on the same non-member predicate.
 
 The head of the predicate gives a name, an optional *result type*, and a sequence of variables declarations that are *arguments*:
 
@@ -952,7 +953,7 @@ The body of a predicate is of one of three forms:
 
 In the first form, with just a semicolon, the predicate is said to not have a body. In the second form, the body of the predicate is the given formula (see "`Formulas <#formulas>`__"). In the third form, the body is a higher-order relation.
 
-A valid non-member predicate must have a body, either a formula or a higher-order relation, unless it is external, in which case it must not have a body.
+A valid non-member predicate must have a body, either a formula or a higher-order relation, unless it is external or extensible, in which case it must not have a body.
 
 The typing environment for the body of the formula, if present, maps the variables in the head of the predicate to their associated types. If the predicate has a result type, then the typing environment also maps ``result`` to the result type.
 
@@ -1053,7 +1054,7 @@ A member predicate ``p`` with enclosing class ``C`` *shadows* a member predicate
 
 Member predicates have one or more *root definitions*. If a member predicate overrides no other member predicate, then it is its own root definition. Otherwise, its root definitions are those of any member predicate that it overrides.
 
-A valid member predicate must have a body unless it is abstract or external, in which case it must not have a body.
+A valid member predicate must have a body unless it is abstract, in which case it must not have a body.
 
 A valid member predicate must override another member predicate if it is annotated override.
 
@@ -2180,7 +2181,7 @@ If a QL program has no valid stratification, then the program itself is not vali
 Layer evaluation
 ~~~~~~~~~~~~~~~~
 
-The store is first initialized with the *database content* of all built-in predicates and external predicates. The database content of a predicate is a set of ordered tuples that are included in the database.
+The store is first initialized with the *database content* of all built-in predicates, external predicates, and extensible predicates. The database content of a predicate is a set of ordered tuples that are included in the database.
 
 Each layer of the stratification is *populated* in order. To populate a layer, each predicate in the layer is repeatedly populated until the store stops changing. The way that a predicate is populated is as follows:
 

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

@@ -10,6 +10,10 @@ Signatures
 Parameterized modules use signatures as a type system for their parameters.
 There are three categories of signatures: **predicate signatures**, **type signatures**, and **module signatures**.
 
+.. index:: predicate signature
+
+.. _predicate-signatures:
+
 Predicate signatures
 ====================
 
@@ -36,6 +40,10 @@ For example:
 
     signature int operator(int lhs, int rhs);
 
+.. index:: type signature
+
+.. _type-signatures:
+
 Type signatures
 ===============
 
@@ -66,6 +74,10 @@ For example:
       string toString();
     }
 
+.. index:: module signature
+
+.. _module-signatures:
+
 Module signatures
 =================