Merge pull request github#13572 from kaspersv/kaspersv/deprecated-imports-docs

Document deprecated imports

Author: kaspersv

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

@@ -126,7 +126,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|, |fields|, |modules|, |aliases|
+**Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|
 
 The ``deprecated`` annotation is applied to names that are outdated and scheduled for removal
 in a future release of QL.

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

@@ -264,7 +264,12 @@ Import statements are used for importing modules. They are of the form:
 Import statements are usually listed at the beginning of the module. Each
 import statement imports one module. You can import multiple modules by 
 including multiple import statements (one for each module you want to import).
-An import statement can also be :ref:`annotated <private>` with ``private``.
+
+An import statement can also be :ref:`annotated <annotations-overview>` with
+``private`` or ``deprecated``. If an import statement is annotated with
+``private`` then the imported names are not reexported. If an imported name is
+only reachable through deprecated imports in a given context then usage of the
+name in that context will generate deprecation warnings.
 
 You can import a module under a different name using the ``as`` keyword, 
 for example ``import javascript as js``.

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

@@ -794,7 +794,7 @@ The following table summarizes the syntactic constructs which can be marked with
 +----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
 | ``private``    | yes     |            | yes               | yes                   | yes     | yes    | yes     | yes     | yes        |
 +----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
-| ``deprecated`` | yes     |            | yes               | yes                   |         | yes    | yes     | yes     | yes        |
+| ``deprecated`` | yes     |            | yes               | yes                   | yes     | yes    | yes     | yes     | yes        |
 +----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+
 | ``override``   |         |            | yes               |                       |         | yes    |         |         |            |
 +----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+------------+