Merge pull request github#3170 from shati-patel/21-ql-language

CodeQL docs: Update intros in QL handbook and QL spec

Author: shati-patel

docs/language/ql-handbook/aliases.rst

@@ -4,8 +4,9 @@
 Aliases
 #######
 
-An alias is an alternative name for an existing QL entity. Once you've defined an alias,
-you can use that new name to refer to the entity in the current module's :ref:`namespace <namespaces>`.
+An alias is an alternative name for an existing QL entity. 
+
+Once you've defined an alias, you can use that new name to refer to the entity in the current module's :ref:`namespace <namespaces>`.
 
 Defining an alias
 *****************

docs/language/ql-handbook/annotations.rst

@@ -4,6 +4,7 @@ Annotations
 ###########
 
 An annotation is a string that you can place directly before the declaration of a QL entity or name.
+
 For example, to declare a module ``M`` as private, you could use::
 
     private module M {

docs/language/ql-handbook/evaluation.rst

@@ -3,6 +3,8 @@
 Evaluation of QL programs
 #########################
 
+A QL program is evaluated in a number of different steps.
+
 Process
 *******
 

docs/language/ql-handbook/expressions.rst

@@ -3,11 +3,10 @@
 Expressions
 ###########
 
-An expression evaluates to a set of values in QL. For example, the expression ``1 + 2`` 
-evaluates to the integer ``3`` and the expression ``"QL"`` evaluates to the string ``"QL"``.
+An expression evaluates to a set of values and has a type.
 
-A valid expression also has a :ref:`type <types>`. 
-In the above examples, ``1 + 2`` has type ``int`` and ``"QL"`` has type ``string``.
+For example, the expression ``1 + 2`` 
+evaluates to the integer ``3`` and the expression ``"QL"`` evaluates to the string ``"QL"``. ``1 + 2`` has :ref:`type <types>` ``int`` and ``"QL"`` has type ``string``.
 
 The following sections describe the expressions that are available in QL.
 

docs/language/ql-handbook/formulas.rst

@@ -3,10 +3,9 @@
 Formulas
 ########
 
-Formulas define logical relations between the :ref:`free variables <free-variables>` used in
-:ref:`expressions <expressions>`.
+Formulas define logical relations between the free variables used in expressions.
 
-Depending on the values assigned to those free variables, a formula can be true or false.
+Depending on the values assigned to those :ref:`free variables <free-variables>`, a formula can be true or false.
 When a formula is true, we often say that the formula *holds*.
 For example, the formula ``x = 4 + 5`` holds if the value ``9`` is assigned to ``x``, but it
 doesn't hold for other assignments to ``x``. 

docs/language/ql-handbook/lexical-syntax.rst

@@ -3,10 +3,10 @@
 Lexical syntax
 ##############
 
+The QL syntax includes different kinds of keywords, identifiers, and comments.
+
 For an overview of the lexical syntax, see `Lexical syntax 
-<https://help.semmle.com/QL/ql-spec/language.html#lexical-syntax>`_
-in the QL language specification. In particular, you can find the list of QL keywords, the
-different kinds of identifiers, and a description of comments.
+<https://help.semmle.com/QL/ql-spec/language.html#lexical-syntax>`_ in the QL language specification.
 
 .. index:: comment, QLDoc
 .. _comments:

docs/language/ql-handbook/name-resolution.rst

@@ -3,6 +3,8 @@
 Name resolution
 ###############
 
+The QL compiler resolves names to program elements.
+
 As in other programming languages, there is a distinction between the names used in QL code, 
 and the underlying QL entities they refer to.
 

docs/language/ql-handbook/queries.rst

@@ -4,15 +4,16 @@
 Queries
 #######
 
-Queries are the output of a QL program: they evaluate to sets of results. Indeed, we
-often refer to the whole QL program as a *query*.
+Queries are the output of a QL program. They evaluate to sets of results.
 
 There are two kinds of queries. For a given :ref:`query module <query-modules>`, the queries in that module are:
   - The :ref:`select clause <select-clauses>`, if any, defined in that module.
   - Any :ref:`query predicates <query-predicates>` in that module's predicate 
     :ref:`namespace <namespaces>`. That is, they can be defined in the module itself, or 
     imported from a different module.
 
+We often also refer to the whole QL program as a query.
+
 .. index:: from, where, select
 .. _select-clauses:
 

docs/language/ql-handbook/types.rst

@@ -5,7 +5,9 @@
 Types
 #####
 
-QL is a statically typed language, so each variable must have a declared **type**. A type is a set of values.
+QL is a statically typed language, so each variable must have a declared type.
+
+A type is a set of values.
 For example, the type ``int`` is the set of integers. 
 Note that a value can belong to more than one of these sets, which means that it can have more 
 than one type.

docs/language/ql-handbook/variables.rst

@@ -5,11 +5,11 @@ Variables
 #########
 
 Variables in QL are used in a similar way to variables in algebra or logic. They represent sets
-of values, and those values are usually restricted by a :ref:`formula <formulas>`.
+of values, and those values are usually restricted by a formula.
 
 This is different from variables in some other programming languages, where variables represent
 memory locations that may contain data. That data can also change over time. For example, in
-QL, ``n = n + 1`` is an equality formula that holds only
+QL, ``n = n + 1`` is an equality :ref:`formula <formulas>` that holds only
 if ``n`` is equal to ``n + 1`` (so in fact it does not hold for any numeric value).
 In Java, ``n = n + 1`` is not an equality, but an assignment that changes the value of ``n`` by
 adding ``1`` to the current value.