Merge pull request github#11939 from github/ginsbach/DocumentNewNamespaces

document new namespaces

Author: ginsbach

docs/codeql/ql-language-reference/name-resolution.rst

@@ -29,6 +29,10 @@ In summary, the kinds of expressions are:
       - These refer to predicates.
       - They can be simple :ref:`names <names>` or names with arities (for example in an :ref:`alias <aliases>`
         definition), or :ref:`selections <selections>`.
+  - **signature expressions**
+      - These refer to module signatures, type signatures, or predicate signatures.
+      - They can be simple :ref:`names <names>`, names with arities, :ref:`selections <selections>`,
+        or :ref:`instantiations <parameterized-modules>`.
 
 .. _names:
 
@@ -164,14 +168,27 @@ As in many other programming languages, a namespace is a mapping from **keys** t
 **entities**. A key is a kind of identifier, for example a name, and a QL entity is
 a :ref:`module <modules>`, a :ref:`type <types>`, or a :ref:`predicate <predicates>`.
 
-Each module in QL has three namespaces:
+Each module in QL has six namespaces:
 
     - The **module namespace**, where the keys are module names and the entities are modules.
     - The **type namespace**, where the keys are type names and the entities are types.
     - The **predicate namespace**, where the keys are pairs of predicate names and arities, 
       and the entities are predicates.
+    - The **module signature namespace**, where the keys are module signature names and the entities are module signatures.
+    - The **type signature namespace**, where the keys are type signature names and the entities are type signatures.
+    - The **predicate signature namespace**, where the keys are pairs of predicate signature names and arities,
+      and the entities are predicate signatures.
 
-It's important to know that there is no relation between names in different namespaces. 
+The six namespaces of any module are not completely independent of each other:
+
+    - No keys may be shared between the **module namespace** and the **module signature namespace**.
+    - No keys may be shared between the **type namespace** and the **type signature namespace**.
+    - No keys may be shared between the **module namespace** and the **type signature namespace**.
+    - No keys may be shared between the **type namespace** and the **module signature namespace**.
+    - No keys may be shared between the **predicate namespace** and the **predicate signature namespace**.
+    - No keys may be shared between the **module signature namespace** and the **type signature namespace**.
+
+There is no relation between names in namespaces of different modules.
 For example, two different modules can define a predicate ``getLocation()`` without confusion. As long as 
 it's clear which namespace you are in, the QL compiler resolves the name to the correct predicate.
 
@@ -182,11 +199,12 @@ The namespaces containing all the built-in entities are called **global namespac
 and are automatically available in any module.
 In particular: 
 
-    - The **global module namespace** is empty.
+    - The **global module namespace** has a single entry ``QlBuiltins``.
     - The **global type namespace** has entries for the :ref:`primitive types <primitive-types>` ``int``, ``float``, 
       ``string``, ``boolean``, and ``date``, as well as any :ref:`database types <database-types>` defined in the database schema.
     - The **global predicate namespace** includes all the `built-in predicates <https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#built-ins>`_,
       as well as any :ref:`database predicates <database-predicates>`.
+    - The **global signature namespaces** are empty.
 
 In practice, this means that you can use the built-in types and predicates directly in a QL module (without
 importing any libraries). You can also use any database predicates and types directly—these depend on the

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

@@ -86,13 +86,25 @@ use information from the database.
 Name resolution
 ---------------
 
-All modules have three environments that dictate name resolution. These are multimaps of keys to declarations.
+All modules have six environments that dictate name resolution. These are multimaps of keys to declarations.
 
 The environments are:
 
 -  The *module environment*, whose keys are module names and whose values are modules.
 -  The *type environment*, whose keys are type names and whose values are types.
 -  The *predicate environment*, whose keys are pairs of predicate names and arities and whose values are predicates.
+-  The *module signature environment*, whose keys are module signature names and whose values are module signatures.
+-  The *type signature environment*, whose keys are type signature names and whose values are type signatures.
+-  The *predicate signature environment*, whose keys are pairs of predicate signature names and arities and whose values are predicate signatures.
+
+For each module, some namespaces are enforced to be disjoint:
+
+-  No keys may be shared between the **module namespace** and the **module signature namespace**.
+-  No keys may be shared between the **type namespace** and the **type signature namespace**.
+-  No keys may be shared between the **module namespace** and the **type signature namespace**.
+-  No keys may be shared between the **type namespace** and the **module signature namespace**.
+-  No keys may be shared between the **predicate namespace** and the **predicate signature namespace**.
+-  No keys may be shared between the **module signature namespace** and the **type signature namespace**.
 
 If not otherwise specified, then the environment for a piece of syntax is the same as the environment of its enclosing syntax.
 
@@ -108,12 +120,14 @@ A *definite* environment has at most one entry for each key. Resolution is uniqu
 Global environments
 ~~~~~~~~~~~~~~~~~~~
 
-The global module environment is empty.
+The global module environment has a single entry ``QlBuiltins``.
 
 The global type environment has entries for the primitive types ``int``, ``float``, ``string``, ``boolean``, and ``date``, as well as any types defined in the database schema.
 
 The global predicate environment includes all the built-in classless predicates, as well as any extensional predicates declared in the database schema.
 
+The three global signature environments are empty.
+
 The program is invalid if any of these environments is not definite.
 
 Module environments