Merge pull request #1653 from felicity-semmle/learn-ql/SD-3690-vale-corrections

Learn QL: corrections for issues found using Vale

Author: jf205

docs/ql-documentation/learn-ql/advanced/abstract-classes.rst

@@ -10,7 +10,7 @@ A classic example where this approach is useful is when modeling ASTs (Abstract
 
 Each value in a concrete class satisfies a particular logical property - the *characteristic predicate* (or *character* for short) of that class. This characteristic predicate consists of the conjunction (``and``) of its own body (if any) and the characteristic predicates of its superclasses.
 
-For example, we could derive a subclass ``MainMethod`` from the standard QL class ``Method`` that contains precisely those Java functions called "main":
+For example, we could derive a subclass ``MainMethod`` from the standard QL class ``Method`` that contains precisely those Java functions called ``"main"``:
 
 .. code-block:: ql
 
@@ -33,7 +33,7 @@ Letting ``cp(C)`` denote the characteristic predicate of class ``C``, it is clea
 
    cp(MainMethod) = cp(Method) and hasName("main")
 
-That is, entities are "main" methods if and only if they are methods that are also called "main".
+That is, entities are *main* methods if and only if they are methods that are also called ``"main"``.
 
 Abstract classes
 ----------------

docs/ql-documentation/learn-ql/advanced/folding-predicates.rst

@@ -16,7 +16,7 @@ Example
        e1.getLocation().getStartLine() = e2.getLocation().getStartLine()
    }
 
-Here we are doing some lookups on ``Element``\ s. Going from ``Element -> File`` and ``Element -> Location -> StartLine`` are linear: there is only one ``File`` for each ``Element``, and one ``Location`` for each ``Element``, etc. However, as written it is difficult for the optimizer to pick out the best ordering here. We want to do the quick, linear parts first, and then join on the resultant larger tables, rather than joining first and then doing the linear lookups. We can precipitate this kind of ordering by rewriting the above predicate as follows:
+Here we explore some lookups on ``Element``\ s. Going from ``Element -> File`` and ``Element -> Location -> StartLine`` are linear: there is only one ``File`` for each ``Element``, and one ``Location`` for each ``Element``, etc. However, as written it is difficult for the optimizer to pick out the best ordering here. We want to do the quick, linear parts first, and then join on the resultant larger tables, rather than joining first and then doing the linear lookups. We can precipitate this kind of ordering by rewriting the above predicate as follows:
 
 .. code-block:: ql
 

docs/ql-documentation/learn-ql/advanced/monotonic-aggregates.rst

@@ -42,7 +42,7 @@ For most usages, aggregates have very straightforward behavior. They can be thou
 
    For every combination of values for the declared **variables**, for which the **range** holds, take one value of the **expression** and apply the **aggregation function** to the resulting values.
 
-How does this work? Let us take the simple example given above of calculating the sum of your employees' salaries. Suppose that your employees are Alice, Ben and Charles, whose salaries are $30k, $40k, and $50k respectively. Then to calculate ``result``, we follow our recipe:
+How does this work? Let us take the simple example given above of calculating the sum of your employees' salaries. Suppose that your employees are Alice, Ben, and Charles, whose salaries are $30k, $40k, and $50k respectively. Then to calculate ``result``, we follow our recipe:
 
 +----------------------------------------------------------------+-------------------------------------+
 | For every combination of values for the declared **variables** | Alice, Ben, Charles, Denis, Edna... |
@@ -192,7 +192,7 @@ Rank is a slightly unusual aggregate. It takes the possible values of the expres
    where salary = rank[salaryRank](Employee e | managedByMe(e) | e.getSalary())
    select salary, salaryRank
 
-assigns, for each of my managees, their salary to ``salary``, and the rank of their salary to ``salaryRank``. In our running example, the results would be:
+assigns, for each person I manage, their salary to ``salary``, and the rank of their salary to ``salaryRank``. In our running example, the results would be:
 
 +------------+----------------+
 | ``salary`` | ``salaryRank`` |

docs/ql-documentation/learn-ql/beginner/find-thief-1.rst

@@ -45,7 +45,7 @@ There is too much information to search through by hand, so you decide to use yo
 #. Select a language and a demo project. For this tutorial, any language and project will do.
 #. Delete the default code ``import <language> select "hello world"``.
 
-QL Libraries
+QL libraries
 ------------
 
 We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.

docs/ql-documentation/learn-ql/beginner/find-thief-2.rst

@@ -1,7 +1,7 @@
 Find the thief: Start the search
 ================================
 
-The villagers answered "yes" to the question "Is the thief taller than 150cm?". To use this information, you can write the following query to list all villagers taller than 150cm. These are all possible suspects.
+The villagers answered "yes" to the question "Is the thief taller than 150cm?" To use this information, you can write the following query to list all villagers taller than 150cm. These are all possible suspects.
 
 .. code-block:: ql
 

docs/ql-documentation/learn-ql/beginner/fire-1.rst

@@ -55,7 +55,7 @@ The expression ``southern(this)`` defines the logical property represented by th
 
    Note
 
-   If you are familiar with object-oriented programming languages, you might be tempted to think of the characteristic predicate as a "constructor". However, this is **not** the case - it is a logical property which does not create any objects.
+   If you are familiar with object-oriented programming languages, you might be tempted to think of the characteristic predicate as a *constructor*. However, this is **not** the case - it is a logical property which does not create any objects.
 
 You always need to define a class in QL in terms of an existing (larger) class. In our example, a ``Southerner`` is a special kind of ``Person``, so we say that ``Southerner`` *extends* ("is a subset of") ``Person``.
 

docs/ql-documentation/learn-ql/beginner/heir.rst

@@ -89,7 +89,7 @@ This is getting complicated. Ideally, you want to define a predicate ``relativeO
 
 How could you do that?
 
-It helps to think of a precise definition of "relative". A possible definition is that two people are related if they have a common ancestor.
+It helps to think of a precise definition of *relative*. A possible definition is that two people are related if they have a common ancestor.
 
 You can introduce a predicate ``ancestorOf(Person p)`` that lists all ancestors of ``p``. An ancestor of ``p`` is just a parent of ``p``, or a parent of a parent of ``p``, or a parent of a parent of a parent of ``p``, and so on. Unfortunately, this leads to an endless list of parents. You can't write an infinite QL query, so there must be an easier approach.
 

docs/ql-documentation/learn-ql/cpp/dataflow.rst

@@ -12,7 +12,7 @@ For a more general introduction to modeling data flow in QL, see :doc:`Introduct
 Local data flow
 ---------------
 
-Local data flow is data flow within a single function. Local data flow is usually easier, faster and more precise than global data flow, and is sufficient for many queries.
+Local data flow is data flow within a single function. Local data flow is usually easier, faster, and more precise than global data flow, and is sufficient for many queries.
 
 Using local data flow
 ~~~~~~~~~~~~~~~~~~~~~

docs/ql-documentation/learn-ql/cpp/expressions-types.rst

@@ -4,7 +4,7 @@ Tutorial: Expressions, types and statements
 Overview
 --------
 
-This topic contains worked examples of how to write queries using the standard QL library classes for C/C++ expressions, types and statements.
+This topic contains worked examples of how to write queries using the standard QL library classes for C/C++ expressions, types, and statements.
 
 Expressions and types
 ---------------------

docs/ql-documentation/learn-ql/cpp/introduce-libraries-cpp.rst

@@ -49,7 +49,7 @@ Symbol table
    -  ``TypedefType`` — typedefs
    -  ``ArrayType`` — arrays
    -  ``PointerType`` — pointers
-   -  ``SpecifiedType`` — qualifiers such as const, volatile, or restrict
+   -  ``SpecifiedType`` — qualifiers such as ``const``, ``volatile``, or ``restrict``
 
 -  ``Namespace`` — namespaces (defined in the `Namespace.qll <https://help.semmle.com/qldoc/cpp/semmle/code/cpp/Namespace.qll/module.Namespace.html>`__ library)