docs: refine some article titles

james · james · commit edc5d36274ce · 2020-05-20T16:16:14.000+01:00
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,9 @@
-Classes for working with Java code
-==================================
+Abstract syntax tree classes for working with Java programs
+===========================================================
 
-CodeQL has a large selection of classes for working with Java statements and expressions.
+CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.
+
+.. include:: ../../reusables/abstract-syntax-tree.rst
 
 .. _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/expressions-statements.rst b/docs/language/learn-ql/java/expressions-statements.rst
@@ -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. For a full list, see :doc:`Classes for working with Java code <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:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`.
 
 Initial query
 -------------
diff --git a/docs/language/learn-ql/java/introduce-libraries-java.rst b/docs/language/learn-ql/java/introduce-libraries-java.rst
@@ -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``). 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>`.
+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:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`.
 
 Both ``Expr`` and ``Stmt`` provide member predicates for exploring the abstract syntax tree of a program:
 
diff --git a/docs/language/learn-ql/java/ql-for-java.rst b/docs/language/learn-ql/java/ql-for-java.rst
@@ -34,5 +34,5 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 
 -  :doc:`Working with source locations <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.
 
--  :doc:`Classes for working with Java code <ast-class-reference>`: CodeQL has a large selection of classes for working with Java statements and expressions.
+-  :doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.
 
diff --git a/docs/language/learn-ql/javascript/ast-class-reference.rst b/docs/language/learn-ql/javascript/ast-class-reference.rst
@@ -1,7 +1,9 @@
-Abstract syntax tree classes for JavaScript and TypeScript
-==========================================================
+Abstract syntax tree classes for working with JavaScript and TypeScript programs
+================================================================================
 
-CodeQL has a large selection of classes for working with JavaScript and TypeScript statements and expressions.
+CodeQL has a large selection of classes for representing the abstract syntax tree of JavaScript and TypeScript programs.
+
+.. include:: ../../reusables/abstract-syntax-tree.rst
 
 Statement classes
 -----------------
diff --git a/docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst b/docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst
@@ -142,7 +142,7 @@ Files
 AST nodes
 ---------
 
-See also: :doc:`Abstract syntax tree classes for JavaScript and TypeScript <ast-class-reference>`.
+See also: :doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <ast-class-reference>`.
 
 Conversion between DataFlow and AST nodes:
 
diff --git a/docs/language/learn-ql/javascript/ql-for-javascript.rst b/docs/language/learn-ql/javascript/ql-for-javascript.rst
@@ -26,6 +26,6 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 
 -  :doc:`Using type tracking for API modeling <type-tracking>`: You can track data through an API by creating a model using the CodeQL type-tracking library for JavaScript.
 
--  :doc:`Abstract syntax tree classes for JavaScript and TypeScript <ast-class-reference>`: CodeQL has a large selection of classes for working with JavaScript and TypeScript statements and expressions.
+-  :doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of JavaScript and TypeScript programs.
 
 -  :doc:`Data flow cheat sheet for JavaScript <dataflow-cheat-sheet>`: This article describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.
diff --git a/docs/language/reusables/abstract-syntax-tree.rst b/docs/language/reusables/abstract-syntax-tree.rst
@@ -0,0 +1 @@
+The `abstract syntax tree (AST) <https://en.wikipedia.org/wiki/Abstract_syntax_tree>`__ represents the syntactic structure of a program. Nodes on the AST represent elements such as statements and expressions.

Original file line number	Diff line number	Diff line change
`@@ -34,5 +34,5 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat`
`34`	`34`
`35`	`35`	- :doc:`Working with source locations <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.
`36`	`36`
`37`		-- :doc:`Classes for working with Java code <ast-class-reference>`: CodeQL has a large selection of classes for working with Java statements and expressions.
	`37`	+- :doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.
`38`	`38`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+The `abstract syntax tree (AST) <https://en.wikipedia.org/wiki/Abstract_syntax_tree>`__ represents the syntactic structure of a program. Nodes on the AST represent elements such as statements and expressions.