Merge pull request #1654 from felicity-semmle/ql-handbook/SD-3691-vale-corrections

Ql handbook: Corrections for issues found using Vale

docs/ql-documentation/ql-handbook/annotations.rst

@@ -45,8 +45,8 @@ You can also find a summary table in the Annotations section of the
 .. index:: abstract
 .. _abstract:
 
-abstract
-========
+``abstract``
+============
 
 **Available for**: |classes|, |member predicates|
 
@@ -89,8 +89,8 @@ own body, or they must inherit from another class that overrides ``isSource``::
 .. index:: cached
 .. _cached:
 
-cached
-======
+``cached``
+==========
 
 **Available for**: |classes|, |algebraic datatypes|, |characteristic predicates|, |member predicates|, |non-member predicates|, |modules|
 
@@ -112,8 +112,8 @@ body must also be annotated with ``cached``, otherwise a compiler error is repor
 .. index:: deprecated
 .. _deprecated:
 
-deprecated
-==========
+``deprecated``
+==============
 
 **Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |fields|, |modules|, |aliases|
 
@@ -141,8 +141,8 @@ This QLDoc comment appears when you use the name ``DataFlowNode`` in a QL editor
 .. index:: external
 .. _external:
 
-external
-========
+``external``
+============
 
 **Available for**: |non-member predicates|
 
@@ -152,8 +152,8 @@ predicate. This is similar to a :ref:`database predicate <database-predicates>`.
 .. index:: transient
 .. _transient:
 
-transient
-=========
+``transient``
+=============
 **Available for**: |non-member predicates|
 
 The ``transient`` annotation is applied to non-member predicates that are also annotated with ``external``,
@@ -163,8 +163,8 @@ without ``external``, the compiler will report an error.
 .. index:: final
 .. _final:
 
-final
-=====
+``final``
+=========
 
 **Available for**: |classes|, |member predicates|, |fields|
 
@@ -185,8 +185,8 @@ change this definition. In this case, ``hasName`` should be final::
 
 .. _library:
 
-library
-=======
+``library``
+===========
 
 **Available for**: |classes|
 
@@ -202,8 +202,8 @@ compiler returns an error.
 .. index:: override
 .. _override:
 
-override
-========
+``override``
+============
 
 **Available for**: |member predicates|, |fields|
 
@@ -216,8 +216,8 @@ warning.
 .. index:: private
 .. _private:
 
-private
-=======
+``private``
+===========
 
 **Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|
 
@@ -229,8 +229,8 @@ module's :ref:`namespace <namespaces>`.
 
 .. _query:
 
-query
-=====
+``query``
+=========
 
 **Available for**: |non-member predicates|, |aliases|
 
@@ -265,16 +265,16 @@ and a call to that predicate ``... one(y) ...``. The QL optimizer may inline the
 You can use the following compiler pragma annotations to control the way the QL optimizer inlines 
 predicates.
 
-pragma[inline]
---------------
+``pragma[inline]``
+------------------
 
 The ``pragma[inline]`` annotation tells the QL optimizer to always inline the annotated predicate
 into the places where it is called. This can be useful when a predicate body is very expensive to 
 compute entirely, as it ensures that the predicate is evaluated with the other contextual information
 at the places where it is called.
 
-pragma[noinline]
-----------------
+``pragma[noinline]``
+--------------------
 
 The ``pragma[noinline]`` annotation is used to prevent a predicate from being inlined into the
 place where it is called. In practice, this annotation is useful when you've already grouped 
@@ -282,8 +282,8 @@ certain variables together in a "helper" predicate, to ensure that the relation
 in one piece. This can help to improve performance. The QL optimizer's inlining may undo the 
 work of the helper predicate, so it's a good idea to annotate it with ``pragma[noinline]``.
 
-pragma[nomagic]
----------------
+``pragma[nomagic]``
+-------------------
 
 The ``pragma[nomagic]`` annotation is used to prevent the QL optimizer from performing the "magic sets"
 optimization on a predicate. 
@@ -295,8 +295,8 @@ by Semmle.
 
 Note that ``nomagic`` implies ``noinline``.
 
-pragma[noopt]
--------------
+``pragma[noopt]``
+-----------------
 
 The ``pragma[noopt]`` annotation is used to prevent the QL optimizer from optimizing a
 predicate, except when it's absolutely necessary for compilation and evaluation to work.
@@ -352,8 +352,8 @@ Language pragmas
 
 **Available for**: |classes|, |characteristic predicates|, |member predicates|, |non-member predicates|
 
-language[monotonicAggregates]
------------------------------
+``language[monotonicAggregates]``
+---------------------------------
 
 This annotation allows you to use **monotonic aggregates** instead of the standard QL
 :ref:`aggregates <aggregations>`.
@@ -367,8 +367,8 @@ Binding sets
 
 **Available for**: |characteristic predicates|, |member predicates|, |non-member predicates|
 
-bindingset[...]
----------------
+``bindingset[...]``
+-------------------
 
 You can use this annotation to explicitly state the binding sets for a predicate. A binding set
 is a subset of the predicate's arguments such that, if those arguments are constrained to a

docs/ql-documentation/ql-handbook/expressions.rst

@@ -4,7 +4,7 @@ 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".
+evaluates to the integer ``3`` and the expression ``"QL"`` evaluates to the string ``"QL"``.
 
 A valid expression also has a :ref:`type <types>`. 
 In the above examples, ``1 + 2`` has type ``int`` and ``"QL"`` has type ``string``.
@@ -61,7 +61,7 @@ You can express certain values directly in QL, such as numbers, booleans, and st
     
   Note: there is no "date literal" in QL. Instead, to specify a :ref:`date <date>`, you should
   convert a string to the date that it represents using the ``toDate()`` predicate. For example,
-  ``"2016-04-03".toDate()`` is the date 03/04/2016, and ``"2000-01-01 00:00:01".toDate()`` is the
+  ``"2016-04-03".toDate()`` is the date April 3, 2016, and ``"2000-01-01 00:00:01".toDate()`` is the
   point in time one second after New Year 2000.
   
   The following string formats are recognized as dates:
@@ -274,7 +274,7 @@ The following aggregates are available in QL:
 .. index:: strictconcat, strictcount, strictsum
 
 - ``strictconcat``, ``strictcount``, and ``strictsum``: These aggregates work like ``concat``,
-  ``count``, and ``sum`` respectively, except that they are "strict". That is, if there are no
+  ``count``, and ``sum`` respectively, except that they are *strict*. That is, if there are no
   possible assignments to the aggregation variables that satisfy the formula, then the entire aggregation fails and
   evaluates to the empty set (instead of defaulting to ``0`` or the empty string).
   This is useful if you're only interested in results where the aggregation body is non-trivial.

docs/ql-documentation/ql-handbook/formulas.rst

@@ -7,7 +7,7 @@ Formulas define logical relations between the :ref:`free variables <free-variabl
 :ref:`expressions <expressions>`.
 
 Depending on the values assigned to those free variables, a formula can be true or false.
-When a formula is true, we often say that the formula "holds".
+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``. 
 Some formulas don't have any free variables. For example ``1 < 2`` always holds, and ``1 > 2`` 
@@ -185,8 +185,8 @@ mathematical logic.
 
 .. index:: exists
 
-exists
-------
+``exists``
+----------
 
 This quantifier has the following syntax::
 
@@ -203,8 +203,8 @@ type ``int`` and holds if any value of that variable has type ``OneTwoThree``.
 
 .. index:: forall 
 
-forall
-------
+``forall``
+----------
 
 This quantifier has the following syntax::
 
@@ -223,8 +223,8 @@ logically the same as ``not exists(<vars> | <formula 1> | not <formula 2>)``.
 
 .. index:: forex
 
-forex
------
+``forex``
+---------
 
 This quantifier has the following syntax::
 
@@ -250,7 +250,7 @@ useful shorthand.
 Implicit quantifiers
 ====================
 
-Implicity quantified variables can be introduced using "don't care expressions". These are used 
+Implicitly quantified variables can be introduced using "don't care expressions." These are used 
 when you need to introduce a variable to use as an argument to a predicate call, but don't care 
 about its value. For further information, see :ref:`Don't-care expressions <dont-care>`.
 
@@ -287,8 +287,8 @@ languages. Here is a brief overview:
 .. index:: not, negation
 .. _negation:
 
-not
-===
+``not``
+=======
 
 You can use the keyword ``not`` before a formula. The resulting formula is called a negation.
 
@@ -311,8 +311,8 @@ The following query selects files that are not HTML files.
 .. index:: if, then, else
 .. _conditional:
 
-if ... then ... else
-====================
+``if ... then ... else``
+========================
 
 You can use these keywords to write a conditional formula. This is another way to simplify
 notation: ``if A then B else C`` is the same as writing ``(A and B) or ((not A) and C)``.
@@ -331,8 +331,8 @@ a public class and returns ``"private"`` otherwise::
 .. index:: and, conjunction
 .. _conjunction:
 
-and
-===
+``and``
+=======
 
 You can use the keyword ``and`` between two formulas. The resulting formula is called a 
 conjunction. 
@@ -352,8 +352,8 @@ than 200 lines of code::
 .. index:: or, disjunction
 .. _disjunction:
 
-or
-==
+``or``
+======
 
 You can use the keyword ``or`` between two formulas. The resulting formula is called a 
 disjunction. 
@@ -375,8 +375,8 @@ With the following definition, an integer is in the class ``OneTwoThree`` if it
 .. index:: implies
 .. _implication:
 
-implies
-=======
+``implies``
+===========
 
 You can use the keyword ``implies`` between two formulas. The resulting formula is called an 
 implication. This is just a simplified notation: ``A implies B`` is the same as writing ``(not A) or B``.

docs/ql-documentation/ql-handbook/modules.rst

@@ -3,7 +3,7 @@
 Modules
 #######
    
-Modules provide a way of organizing QL code by grouping together related types, predicates and other modules. 
+Modules provide a way of organizing QL code by grouping together related types, predicates, and other modules. 
 
 You can import modules into other files, which avoids duplication, and helps 
 structure your code into more manageable pieces.

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

@@ -193,7 +193,7 @@ In addition to the global module, type, and predicate namespaces, each module de
 module, type, and predicate namespaces.
 
 For a module ``M``, it's useful to distinguish between its **declared**, **exported**, and **imported** namespaces. 
-(These are described generically, but remember that there is always one for each of modules, types and predicates.)
+(These are described generically, but remember that there is always one for each of modules, types, and predicates.)
 
     - The **declared** namespaces contain any names that are declared—that is, defined—in ``M``.
     - The **imported** namespaces contain any names exported by the modules that are imported into ``M`` using an 

docs/ql-documentation/ql-handbook/queries.rst

@@ -5,7 +5,7 @@ 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".
+often refer to the whole QL program as a *query*.
 
 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.

docs/ql-documentation/ql-handbook/recursion.rst

@@ -127,7 +127,7 @@ The following examples illustrate common mistakes that lead to invalid recursion
 Empty recursion
 ===============
 
-Firstly, a valid recursive definition must have a starting point or "base case".
+Firstly, a valid recursive definition must have a starting point or *base case*.
 If a recursive predicate evaluates to the empty set of values, there is usually something
 wrong.
 

docs/ql-documentation/ql-handbook/types.rst

@@ -375,7 +375,7 @@ An algebraic datatype is another form of user-defined type, declared with the ke
 Algebraic datatypes are used for creating new values that are neither primitive values nor entities from
 the database. One example is to model flow nodes when analyzing data flow through a program.
 
-An algebraic datatype consists of a number of mutually disjoint "branches", that each define
+An algebraic datatype consists of a number of mutually disjoint *branches*, that each define
 a branch type. The algebraic datatype itself is the union of all the branch types.
 A branch can have arguments and a body. A new value of the branch type is produced for each set
 of values that satisfy the argument types and the body.

docs/ql-documentation/vale-styles/Semmle/ignore.txt

@@ -14,12 +14,16 @@ callee
 callees
 cyclomatic
 Datalog
+datatype
+datatypes
 declarator
 declarators
 dereferenced
 destructor
 destructors
 destructuring
+disjunct
+disjuncts
 downcasting
 downcasts
 enum
@@ -35,6 +39,8 @@ Gradle
 initializer
 initializers
 inline
+inlined
+inlines
 inlining
 interprocedural
 interprocedurally