Make review comment changes

hubwriter · hubwriter · commit daf5a9693531 · 2020-03-02T15:07:30.000Z
diff --git a/docs/language/learn-ql/java/annotations.rst b/docs/language/learn-ql/java/annotations.rst
@@ -167,7 +167,7 @@ Now we can define a class for representing deprecated methods:
        }
    }
 
-Finally, we use these classes to find calls to deprecated methods, excluding calls that themselves appear in deprecated methods (see :doc:`Tutorial: Navigating the call graph <call-graph>` for more information on class ``Call``):
+Finally, we use these classes to find calls to deprecated methods, excluding calls that themselves appear in deprecated methods:
 
 .. code-block:: ql
 
@@ -178,7 +178,9 @@ Finally, we use these classes to find calls to deprecated methods, excluding cal
        and not call.getCaller() instanceof DeprecatedMethod
    select call, "This call invokes a deprecated method."
 
-On our example, this query flags the call to ``A.m`` in ``A.r``, but not the one in ``A.n``.
+In our example, this query flags the call to ``A.m`` in ``A.r``, but not the one in ``A.n``.
+
+For more information about the class ``Call``, see :doc:`Navigating the call graph <call-graph>`.
 
 Improvements
 ~~~~~~~~~~~~
@@ -238,6 +240,6 @@ Now we can extend our query to filter out calls in methods carrying a ``Suppress
 Further reading
 ---------------
 
--  Take a look at some of the other tutorials: :doc:`Tutorial: Javadoc <javadoc>` and :doc:`Tutorial: Working with source locations <source-locations>`.
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Take a look at some of the other articles in this section: :doc:`Javadoc <javadoc>` and :doc:`Working with source locations <source-locations>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
diff --git a/docs/language/learn-ql/java/ast-class-reference.rst b/docs/language/learn-ql/java/ast-class-reference.rst
@@ -1,7 +1,7 @@
-Abstract syntax tree classes in Java
-====================================
+Classes for working with Java code
+==================================
 
-CodeQL has a large selection of classes for working with Java code.
+CodeQL has a large selection of classes for working with Java statements and expressions.
 
 .. _Expr: https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Expr.html
 .. _Stmt: https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$Stmt.html
diff --git a/docs/language/learn-ql/java/call-graph.rst b/docs/language/learn-ql/java/call-graph.rst
@@ -1,10 +1,10 @@
 Navigating the call graph
 =========================
 
-CodeQL provides an API for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
+CodeQL has classes for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
 
-Call graph API
---------------
+Call graph classes
+------------------
 
 The CodeQL library for Java provides two abstract classes for representing a program's call graph: ``Callable`` and ``Call``. The former is simply the common superclass of ``Method`` and ``Constructor``, the latter is a common superclass of ``MethodAccess``, ``ClassInstanceExpression``, ``ThisConstructorInvocationStmt`` and ``SuperConstructorInvocationStmt``. Simply put, a ``Callable`` is something that can be invoked, and a ``Call`` is something that invokes a ``Callable``.
 
@@ -68,7 +68,7 @@ In our example, ``Client.main`` calls the constructor ``Sub(int)`` and the metho
 Example: Finding unused methods
 -------------------------------
 
-Given this API, we can easily write a query that finds methods that are not called by any other method:
+We can use the ``Callable`` class to write a query that finds methods that are not called by any other method:
 
 .. code-block:: ql
 
@@ -164,6 +164,6 @@ Finally, on many Java projects there are methods that are invoked indirectly by
 Further reading
 ---------------
 
--  Find out how to query metadata and white space: :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, and :doc:`Tutorial: Working with source locations <source-locations>`.
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Find out how to query metadata and white space: :doc:`Annotations in Java <annotations>`, :doc:`Javadoc <javadoc>`, and :doc:`Working with source locations <source-locations>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
diff --git a/docs/language/learn-ql/java/dataflow.rst b/docs/language/learn-ql/java/dataflow.rst
@@ -256,7 +256,7 @@ Exercise 4: Using the answers from 2 and 3, write a query which finds all global
 What next?
 ----------
 
--  Try the worked examples in these articles: :doc:`Tutorial: Navigating the call graph <call-graph>` and :doc:`Tutorial: Working with source locations <source-locations>`.
+-  Try the worked examples in these articles: :doc:`Navigating the call graph <call-graph>` and :doc:`Working with source locations <source-locations>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.
 
diff --git a/docs/language/learn-ql/java/expressions-statements.rst b/docs/language/learn-ql/java/expressions-statements.rst
@@ -1,4 +1,4 @@
-Expressions and statements in Java
+Overflow-prone comparisons in Java
 ==================================
 
 You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
@@ -26,7 +26,7 @@ If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``
 
    All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value.
 
-We're going to develop a query that finds code that looks like it might exhibit this kind of behavior. We'll be using several of the standard library classes for representing statements and functions, a full list of which can be found in the :doc:`AST class reference <ast-class-reference>`.
+We're going to develop a query that finds code that looks like it might exhibit this kind of behavior. We'll be using several of the standard library classes for representing statements and functions. For a full list, see :doc:`Classes for working with Java code <ast-class-reference>`.
 
 Initial query
 -------------
@@ -125,6 +125,6 @@ Now we rewrite our query to make use of these new classes:
 Further reading
 ---------------
 
--  Have a look at some of the other tutorials: :doc:`Tutorial: Types and the class hierarchy <types-class-hierarchy>`, :doc:`Tutorial: Navigating the call graph <call-graph>`, :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, and :doc:`Tutorial: Working with source locations <source-locations>`.
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Have a look at some of the other articles in this section: :doc:`Java types <types-class-hierarchy>`, :doc:`Navigating the call graph <call-graph>`, :doc:`Annotations in Java <annotations>`, :doc:`Javadoc <javadoc>`, and :doc:`Working with source locations <source-locations>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
diff --git a/docs/language/learn-ql/java/introduce-libraries-java.rst b/docs/language/learn-ql/java/introduce-libraries-java.rst
@@ -1,10 +1,10 @@
 CodeQL library for Java
 =======================
 
-When you need to analyze a Java program, you can make use of the large collection of classes in the Java library for CodeQL.
+When you're analyzing a Java program in {{ site.data.variables.product.prodname_dotcom }}, you can make use of the large collection of classes in the CodeQL library for Java.
 
-About the Java library
-----------------------
+About the CodeQL library for Java
+---------------------------------
 
 There is an extensive library for analyzing CodeQL databases extracted from Java projects. The classes in this library present the data from a database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.
 
@@ -14,13 +14,13 @@ The library is implemented as a set of QL modules, that is, files with the exten
 
    import java
 
-The rest of this topic briefly summarizes the most important classes and predicates provided by this library.
+The rest of this article briefly summarizes the most important classes and predicates provided by this library.
 
 .. pull-quote::
 
    Note
 
-   The example queries in this topic illustrate the types of results returned by different library classes. The results themselves are not interesting but can be used as the basis for developing a more complex query. The tutorial topics show how you can take a simple query and fine-tune it to find precisely the results you're interested in.
+   The example queries in this article illustrate the types of results returned by different library classes. The results themselves are not interesting but can be used as the basis for developing a more complex query. The other articles in this section of the help show how you can take a simple query and fine-tune it to find precisely the results you're interested in.
 
 Summary of the library classes
 ------------------------------
@@ -196,7 +196,7 @@ The wildcards ``? extends Number`` and ``? super Float`` are represented by clas
 
 For dealing with generic methods, there are classes ``GenericMethod``, ``ParameterizedMethod`` and ``RawMethod``, which are entirely analogous to the like-named classes for representing generic types.
 
-For more information on working with types, see the :doc:`tutorial on types and the class hierarchy <types-class-hierarchy>`.
+For more information on working with types, see the :doc:`article on Java types <types-class-hierarchy>`.
 
 Variables
 ~~~~~~~~~
@@ -210,7 +210,7 @@ Class ``Variable`` represents a variable `in the Java sense <http://docs.oracle.
 Abstract syntax tree
 --------------------
 
-Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). See the :doc:`AST class reference <ast-class-reference>` for an exhaustive list of all expression and statement types available in the standard QL library.
+Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). For a full list of expression and statement types available in the standard QL library, see :doc:`Classes for working with Java code <ast-class-reference>`.
 
 Both ``Expr`` and ``Stmt`` provide member predicates for exploring the abstract syntax tree of a program:
 
@@ -260,7 +260,7 @@ Finally, here is a query that finds method bodies:
 
 As these examples show, the parent node of an expression is not always an expression: it may also be a statement, for example, an ``IfStmt``. Similarly, the parent node of a statement is not always a statement: it may also be a method or a constructor. To capture this, the QL Java library provides two abstract class ``ExprParent`` and ``StmtParent``, the former representing any node that may be the parent node of an expression, and the latter any node that may be the parent node of a statement.
 
-For more information on working with AST classes, see the :doc:`tutorial on expressions and statements <expressions-statements>`.
+For more information on working with AST classes, see the :doc:`article on overflow-prone comparisons in Java <expressions-statements>`.
 
 Metadata
 --------
@@ -292,7 +292,7 @@ These annotations are represented by class ``Annotation``. An annotation is simp
 
 ➤ `See this in the query console <https://lgtm.com/query/659662167/>`__. Only constructors with the ``@deprecated`` annotation are reported this time.
 
-For more information on working with annotations, see the :doc:`tutorial on annotations <annotations>`.
+For more information on working with annotations, see the :doc:`article on annotations <annotations>`.
 
 For Javadoc, class ``Element`` has a member predicate ``getDoc`` that returns a delegate ``Documentable`` object, which can then be queried for its attached Javadoc comments. For example, the following query finds Javadoc comments on private fields:
 
@@ -327,7 +327,7 @@ Class ``Javadoc`` represents an entire Javadoc comment as a tree of ``JavadocEle
 
    On line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment.
 
-For more information on working with Javadoc, see the :doc:`tutorial on Javadoc <javadoc>`.
+For more information on working with Javadoc, see the :doc:`article on Javadoc <javadoc>`.
 
 Metrics
 -------
@@ -381,11 +381,11 @@ Conversely, ``Callable.getAReference`` returns a ``Call`` that refers to it. So
 
 ➤ `See this in the query console <https://lgtm.com/query/666680036/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see :doc:`Navigating the call graph <call-graph>`.
 
-For more information about callables and calls, see the :doc:`call graph tutorial <call-graph>`.
+For more information about callables and calls, see the :doc:`article on the call graph <call-graph>`.
 
 Further reading
 ---------------
 
--  Experiment with the worked examples in the CodeQL for Java tutorial topics: :doc:`Types and the class hierarchy <types-class-hierarchy>`, :doc:`Expressions and statements <expressions-statements>`, :doc:`Navigating the call graph <call-graph>`, :doc:`Annotations <annotations>`, :doc:`Javadoc <javadoc>` and :doc:`Working with source locations <source-locations>`.
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Experiment with the worked examples in the CodeQL for Java articles: :doc:`Java types <types-class-hierarchy>`, :doc:`Overflow-prone comparisons in Java <expressions-statements>`, :doc:`Navigating the call graph <call-graph>`, :doc:`Annotations in Java <annotations>`, :doc:`Javadoc <javadoc>` and :doc:`Working with source locations <source-locations>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
diff --git a/docs/language/learn-ql/java/javadoc.rst b/docs/language/learn-ql/java/javadoc.rst
@@ -221,6 +221,6 @@ Currently, ``visibleIn`` only considers single-type imports, but you could exten
 Further reading
 ---------------
 
--  Find out how you can use the location API to define queries on whitespace: :doc:`Tutorial: Working with source locations <source-locations>`.
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Find out how you can use the location API to define queries on whitespace: :doc:`Working with source locations <source-locations>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
diff --git a/docs/language/learn-ql/java/source-locations.rst b/docs/language/learn-ql/java/source-locations.rst
@@ -1,7 +1,7 @@
 Working with source locations
 =============================
 
-You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem. 
+You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
 
 About source locations
 ----------------------
@@ -186,5 +186,5 @@ Whitespace suggests that the programmer meant to toggle ``i`` between zero and o
 Further reading
 ---------------
 
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
diff --git a/docs/language/learn-ql/java/types-class-hierarchy.rst b/docs/language/learn-ql/java/types-class-hierarchy.rst
@@ -1,5 +1,5 @@
-Types in Java
-=============
+Java types
+==========
 
 You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
 
@@ -299,6 +299,6 @@ Adding these three improvements, our final query becomes:
 Further reading
 ---------------
 
--  Take a look at some of the other tutorials: :doc:`Tutorial: Expressions and statements <expressions-statements>`, :doc:`Tutorial: Navigating the call graph <call-graph>`, :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, and :doc:`Tutorial: Working with source locations <source-locations>`.
--  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
+-  Take a look at some of the other articles in this section: :doc:`Overflow-prone comparisons in Java <expressions-statements>`, :doc:`Navigating the call graph <call-graph>`, :doc:`Annotations in Java <annotations>`, :doc:`Javadoc <javadoc>`, and :doc:`Working with source locations <source-locations>`.
+-  Find out how specific classes in the AST are represented in the standard library for Java: :doc:`Classes for working with Java code <ast-class-reference>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
