docs: further review comments

james · james · commit 24615f2bdbb7 · 2019-11-06T12:44:45.000Z
diff --git a/docs/language/ql-training/cpp/control-flow-cpp.rst b/docs/language/ql-training/cpp/control-flow-cpp.rst
@@ -89,7 +89,7 @@ Control flow graphs
 Modeling control flow
 =====================
 
-The control flow is modeled with a QL class, ``ControlFlowNode``. Examples of control flow nodes include statements and expressions.
+The control flow is modeled with a CodeQL class, ``ControlFlowNode``. Examples of control flow nodes include statements and expressions.
 
 - ``ControlFlowNode`` provides API for traversing the control flow graph:
 
diff --git a/docs/language/ql-training/cpp/intro-ql-cpp.rst b/docs/language/ql-training/cpp/intro-ql-cpp.rst
@@ -70,7 +70,7 @@ A simple CodeQL query
 
    A `query <https://help.semmle.com/QL/ql-handbook/queries.html>`__ consists of a “select” clause that indicates what results should be returned. Typically it will also provide a “from” clause to declare some variables, and a “where” clause to state conditions over those variables. For more information on the structure of query files (including links to useful topics in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__), see `Introduction to query files <https://help.semmle.com/QL/learn-ql/ql/writing-queries/introduction-to-queries.html>`__.
 
-   In our example here, the first line of the query imports the `CodeQL for C/C++ standard library <https://help.semmle.com/qldoc/cpp/>`__, which defines concepts like ``IfStmt`` and ``Block``.
+   In our example here, the first line of the query imports the `CodeQL library for C/C++ <https://help.semmle.com/qldoc/cpp/>`__, which defines concepts like ``IfStmt`` and ``Block``.
    The query proper starts by declaring two variables–ifStmt and block. These variables represent sets of values in the database, according to the type of each of the variables. For example, ifStmt has the type IfStmt, which means it represents the set of all if statements in the program.
 
    If we simply selected these two variables::
@@ -135,10 +135,10 @@ A predicate allows you to pull out and name parts of a query.
 
    You can imagine a predicate to be a self-contained from-where-select statement, that produces an intermediate relation, or table. In this case, the ``isEmpty`` predicate will be the set of all blocks which are empty.
 
-Classes
-=======
+Classes in QL
+=============
 
-A class allows you to name a set of values and define (member) predicates on them.
+A QL class allows you to name a set of values and define (member) predicates on them.
 
 A class has at least one supertype and optionally a **characteristic predicate**; it contains the values that belong to *all* supertypes *and* satisfy the characteristic predicate, if provided.
 
@@ -158,8 +158,8 @@ Member predicates are inherited and can be overridden.
 
   In the example, declaring a variable “EmptyBlock e” will allow it to range over only those blocks that have zero statements.
 
-Classes continued
-=================
+Classes in QL continued
+=======================
 
 .. container:: column-left
 
diff --git a/docs/language/ql-training/cpp/program-representation-cpp.rst b/docs/language/ql-training/cpp/program-representation-cpp.rst
@@ -21,16 +21,16 @@ Agenda
 
 .. resume slides
 
-AST classes
-===========
+AST CodeQL classes
+==================
 
-Important AST classes include:
+Important AST CodeQL classes include:
 
 - ``Expr``: expressions such as assignments, variable references, function calls, ...
 - ``Stmt``: statements such as conditionals, loops, try statements, ... 
 - ``DeclarationEntry``: places where functions, variables or types are declared and/or defined
 
-These three (and all other AST classes) are subclasses of ``Element``.
+These three (and all other AST CodeQL classes) are subclasses of ``Element``.
 
 Symbol table
 ============
@@ -64,7 +64,7 @@ Working with functions
 
 Functions are represented by the Function class. Each declaration or definition of a function is represented by a ``FunctionDeclarationEntry``.
 
-Calls to functions are modeled by class ``Call`` and its subclasses:
+Calls to functions are modeled by CodeQL class ``Call`` and its subclasses:
 
 - ``Call.getTarget()`` gets the declared target of the call; undefined for calls through function pointers
 - ``Function.getACallToThisFunction()`` gets a call to this function
diff --git a/docs/language/ql-training/java/intro-ql-java.rst b/docs/language/ql-training/java/intro-ql-java.rst
@@ -70,7 +70,7 @@ A simple CodeQL query
 
    A `query <https://help.semmle.com/QL/ql-handbook/queries.html>`__ consists of a “select” clause that indicates what results should be returned. Typically it will also provide a “from” clause to declare some variables, and a “where” clause to state conditions over those variables. For more information on the structure of query files (including links to useful topics in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__), see `Introduction to query files <https://help.semmle.com/QL/learn-ql/ql/writing-queries/introduction-to-queries.html>`__.
 
-   In our example here, the first line of the query imports the `CodeQL for Java library <https://help.semmle.com/qldoc/java/>`__, which defines concepts like ``IfStmt`` and ``Block``.
+   In our example here, the first line of the query imports the `CodeQL library for Java <https://help.semmle.com/qldoc/java/>`__, which defines concepts like ``IfStmt`` and ``Block``.
    The query proper starts by declaring two variables–ifStmt and block. These variables represent sets of values in the database, according to the type of each of the variables. For example, ``ifStmt`` has the type ``IfStmt``, which means it represents the set of all if statements in the program.
 
    If we simply selected these two variables::
@@ -135,10 +135,10 @@ A predicate allows you to pull out and name parts of a query.
    You can imagine a predicate to be a self-contained from-where-select statement, that produces an intermediate relation, or table. In this case, the ``isEmpty`` predicate will be the set of all blocks which are empty.
 
 
-Classes
-=======
+Classes in QL
+=============
 
-A class allows you to name a set of values and define (member) predicates on them.
+A QL class allows you to name a set of values and define (member) predicates on them.
 
 A class has at least one supertype and optionally a **characteristic predicate**; it contains the values that belong to *all* supertypes *and* satisfy the characteristic predicate, if provided.
 
@@ -158,7 +158,7 @@ Member predicates are inherited and can be overridden.
 
   In the example, declaring a variable “EmptyBlock e” will allow it to range over only those blocks that have zero statements.
 
-Classes continued
+Classes in QL continued
 =======================
 
 .. container:: column-left
diff --git a/docs/language/ql-training/java/program-representation-java.rst b/docs/language/ql-training/java/program-representation-java.rst
@@ -12,7 +12,7 @@ Agenda
 - Abstract syntax trees
 - Database representation
 - Program elements
-- AST classes
+- AST CodeQL classes
 
 .. insert abstract-syntax-tree.rst
 
@@ -23,15 +23,15 @@ Agenda
 Program elements
 ================
 
-- The QL class ``Element`` represents program elements with a name.
+- The CodeQL class ``Element`` represents program elements with a name.
 - This includes: packages (``Package``), compilation units (``CompilationUnit``), types (``Type``), methods (``Method``), constructors (``Constructor``), and variables (``Variable``).
 - It is often convenient to refer to an element that might either be a method or a constructor; the class ``Callable``, which is a common superclass of ``Method`` and ``Constructor``, can be used for this purpose.
 
 
 AST
 ===
 
-There are two primary AST classes, used within ``Callables``:
+There are two primary AST CodeQL classes, used within ``Callables``:
 
    - ``Expr``: expressions such as assignments, variable references, function calls, ...
    - ``Stmt``: statements such as conditionals, loops, try statements, ... 
@@ -47,7 +47,7 @@ Types
 
 The database also includes information about the types used in a program:
 
-- ``PrimitiveType`` represents a `primitive type <http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html>`__, that is, one of ``boolean``, ``byte``, ``char``, ``double``, ``float``, ``int``, ``long``, ``short``. QL also classifies ``void`` and ``<nulltype>`` (the type of the ``null`` literal) as primitive types.
+- ``PrimitiveType`` represents a `primitive type <http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html>`__, that is, one of ``boolean``, ``byte``, ``char``, ``double``, ``float``, ``int``, ``long``, ``short``. CodeQL also classifies ``void`` and ``<nulltype>`` (the type of the ``null`` literal) as primitive types.
 - ``RefType`` represents a reference type; it has several subclasses:
 
   - ``Class`` represents a Java class.
@@ -74,9 +74,9 @@ Working with variables
 Working with callables
 ======================
 
-Callables are represented by the ``Callable`` QL class. 
+Callables are represented by the ``Callable`` CodeQL class. 
 
-Calls to callables are modeled by the QL class ``Call`` and its subclasses:
+Calls to callables are modeled by the CodeQL class ``Call`` and its subclasses:
 
 - ``Call.getCallee()`` gets the declared target of the call
 - ``Call.getAReference()`` gets a call to this function
diff --git a/docs/language/ql-training/java/query-injection-java.rst b/docs/language/ql-training/java/query-injection-java.rst
@@ -77,14 +77,14 @@ Let’s start by looking for calls to methods with names of the form ``sparql*Qu
 
 .. note::
 
-  - When performing `variant analysis <https://semmle.com/  variant-analysis>`__, it is usually helpful to write a simple   query that finds the simple syntactic pattern, before trying to   go on to describe the cases where it goes wrong.
-  - In this case, we start by looking for all the method calls   which appear to run, before trying to refine the query to find   cases which are vulnerable to query injection.
+  - When performing `variant analysis <https://semmle.com/variant-analysis>`__, it is usually helpful to write a simple query that finds the simple syntactic pattern, before trying to go on to describe the cases where it goes wrong.
+  - In this case, we start by looking for all the method calls that appear to run, before trying to refine the query to find cases which are vulnerable to query injection.
   - The ``select`` clause defines what this query is looking for:
   
     - a ``MethodAccess``: the call to a SPARQL query method
     - a ``Method``: the SPARQL query method.
   
-  - The ``where`` part of the query ties these variables together using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ defined in the `standard CodeQL for   Java library <https://help.semmle.com/qldoc/java/>`__.
+  - The ``where`` part of the query ties these variables together using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ defined in the `standard CodeQL library for Java <https://help.semmle.com/qldoc/java/>`__.
 
 CodeQL query: find string concatenation
 =======================================
diff --git a/docs/language/ql-training/slide-snippets/local-data-flow.rst b/docs/language/ql-training/slide-snippets/local-data-flow.rst
@@ -70,7 +70,7 @@ Local vs global data flow
 
   For further information, see:
 
-  - `Introduction to data flow analysis in CodeQL <https://help.semmle.com/QL/learn-ql/ql/intro-to-data-flow.html>`__
+  - `Introduction to data flow analysis with CodeQL <https://help.semmle.com/QL/learn-ql/ql/intro-to-data-flow.html>`__
 
 .. rst-class:: background2
 
