docs: tidy up 'codeql for x' pages

Manually construct tocs including intro text.
Fix a few intros and titles.

Author: james

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

@@ -1,7 +1,7 @@
 Analyzing data flow in C and C++
 ================================
 
-You can use data-flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
+You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
 
 About data flow
 ---------------

docs/language/learn-ql/cpp/ql-for-cpp.rst

@@ -1,11 +1,10 @@
-CodeQL for C/C++
-================
+CodeQL for C and C++
+====================
 
-
-Learn how to write queries using the standard CodeQL libraries for C and C++.
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C and C++ codebases.
 
 .. toctree::
-   :maxdepth: 1
+   :hidden:
 
    introduce-libraries-cpp
    function-classes
@@ -18,10 +17,25 @@ Learn how to write queries using the standard CodeQL libraries for C and C++.
    range-analysis
    value-numbering-hash-cons
 
-Other resources
----------------
 
-.. TODO: Rename the cookbooks: C/C++ cookbook, or C/C++ CodeQL cookbook, or CodeQL cookbook for C/C++, or...? 
+-  `Basic C/C++ query <https://lgtm.com/help/lgtm/console/ql-cpp-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
+
+-  :doc:`CodeQL library for C and C++ <introduce-libraries-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
+
+-  :doc:`Functions in C and C++ <function-classes>`: You can use CodeQL to explore functions in C and C++ code.
+
+-  :doc:`Expressions, types, and statements in C and C++ <expressions-types>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
+
+-  :doc:`Conversions and classes in C and C++ <conversions-classes>`: You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
+
+-  :doc:`Analyzing data flow in C and C++ <dataflow>`: You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
+
+-  :doc:`Refining a query to account for edge cases <private-field-initialization>`: You can improve the results generated by a CodeQL query by adding conditions to remove false positive results caused by common edge cases.
+
+-  :doc:`Detecting a potential buffer overflow <zero-space-terminator>`: You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
+
+Further reading
+---------------
 
 -  For examples of how to query common C/C++ elements, see the `C/C++ cookbook <https://help.semmle.com/wiki/display/CBCPP>`__.
 -  For the queries used in LGTM, display a `C/C++ query <https://lgtm.com/search?q=language%3Acpp&t=rules>`__ and click **Open in query console** to see the code used to find alerts.

docs/language/learn-ql/csharp/introduce-libraries-csharp.rst

@@ -1,7 +1,7 @@
-CodeQL libraries for C#
-=======================
+CodeQL library for C#
+=====================
 
-When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL libraries for C#.
+When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
 
 About the CodeQL libraries for C#
 ---------------------------------

docs/language/learn-ql/csharp/ql-for-csharp.rst

@@ -1,29 +1,21 @@
 CodeQL for C#
 =============
 
-You can use CodeQL to explore C# programs and quickly find variants of security vulnerabilities and bugs.
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C# codebases.
 
 .. toctree::
-   :glob:
    :hidden:
 
    introduce-libraries-csharp
    dataflow
 
-These topics provide an overview of the CodeQL libraries for C# and show examples of how to use them.
+-  `Basic C# query <https://lgtm.com/help/lgtm/console/ql-csharp-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
 
--  `Basic C# query <https://lgtm.com/help/lgtm/console/ql-csharp-basic-example>`__ describes how to write and run queries using LGTM.
+-  :doc:`CodeQL library for C# <introduce-libraries-csharp>`: When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
 
--  :doc:`Introducing the CodeQL libraries for C# <introduce-libraries-csharp>` introduces the standard libraries used to write queries for C# code.
+-  :doc:`Analyzing data flow in C# <dataflow>`: You can use CodeQL to track the flow of data through a C# program to its use.
 
-.. raw:: html
-
-   <!-- Working with generic types and methods(generics) - how to query generic types and methods. -->
-
--  :doc:`Analyzing data flow in C# <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for C#.
-
-
-Other resources
+Further reading
 ---------------
 
 -  For examples of how to query common C# elements, see the `C# cookbook <https://help.semmle.com/wiki/display/CBCSHARP>`__.

docs/language/learn-ql/go/ql-for-go.rst

@@ -1,10 +1,9 @@
 CodeQL for Go
 =============
 
-This page provides an overview of the CodeQL for Go documentation that is currently available.
-
--  `Basic Go query <https://lgtm.com/help/lgtm/console/ql-go-basic-example>`__ describes how to write and run queries using LGTM.
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Go codebases.
 
+-  `Basic Go query <https://lgtm.com/help/lgtm/console/ql-go-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
 
 Other resources
 ---------------

docs/language/learn-ql/java/ql-for-java.rst

@@ -1,10 +1,9 @@
 CodeQL for Java
 ===============
 
-You can use CodeQL to explore Java programs and quickly find variants of security vulnerabilities and bugs.
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java codebases.
 
 .. toctree::
-   :glob:
    :hidden:
 
    introduce-libraries-java
@@ -17,29 +16,28 @@ You can use CodeQL to explore Java programs and quickly find variants of securit
    source-locations
    ast-class-reference
 
-These topics provide an overview of the CodeQL libraries for Java and show examples of how to use them.
+-  `Basic Java query <https://lgtm.com/help/lgtm/console/ql-java-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
 
--  `Basic Java query <https://lgtm.com/help/lgtm/console/ql-java-basic-example>`__ describes how to write and run queries using LGTM.
+-  :doc:`CodeQL library for Java <introduce-libraries-java>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
 
--  :doc:`CodeQL libraries for Java <introduce-libraries-java>` introduces the standard libraries used to write queries for Java code.
+-  :doc:`Analyzing data flow in Java <dataflow>`: You can use CodeQL to track the flow of data through a Java program to its use. 
 
--  :doc:`Analyzing data flow in Java <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for Java.
+-  :doc:`Java types <types-class-hierarchy>`: 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.
 
--  :doc:`Types in Java <types-class-hierarchy>` introduces the classes for representing a program's class hierarchy by means of examples.
+-  :doc:`Overflow-prone comparisons in Java <expressions-statements>`: You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
 
--  :doc:`Expressions and statements in Java <expressions-statements>` introduces the classes for representing a program's syntactic structure by means of examples.
+-  :doc:`Navigating the call graph <call-graph>`: 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.
 
--  :doc:`Navigating the call graph <call-graph>` is a worked example of how to write a query that navigates a program's call graph to find unused methods.
+-  :doc:`Annotations in Java <annotations>`: CodeQL databases of Java projects contain information about all annotations attached to program elements.
 
--  :doc:`Annotations in Java <annotations>` introduces the classes for representing annotations by means of examples.
+-  :doc:`Javadoc <javadoc>`: You can use CodeQL to find errors in Javadoc comments in Java code.
 
--  :doc:`Javadoc <javadoc>` introduces the classes for representing Javadoc comments by means of examples.
+-  :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:`Working with source locations <source-locations>` is a worked example of how to write a query that uses the ___location information provided in the database for finding likely bugs.
+-  :doc:`lasses for working with Java code <ast-class-reference>`: CodeQL has a large selection of classes for working with Java statements and expressions.
 
--  :doc:`AST class reference <ast-class-reference>` gives an overview of all AST classes in the standard CodeQL library for Java.
 
-Other resources
+Further reading
 ---------------
 
 -  For examples of how to query common Java elements, see the `Java cookbook <https://help.semmle.com/wiki/display/CBJAVA>`__.

docs/language/learn-ql/javascript/introduce-libraries-js.rst

@@ -1,7 +1,7 @@
-CodeQL libraries for JavaScript
-===============================
+CodeQL library for JavaScript
+=============================
 
-You can use the extensive libraries described in this article to analyze databases generated from JavaScript codebases. Using these libraries makes it easier for you to write queries.
+When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
 
 Overview
 --------

docs/language/learn-ql/javascript/introduce-libraries-ts.rst

@@ -1,7 +1,7 @@
-CodeQL libraries for TypeScript
-===============================
+CodeQL library for TypeScript
+=============================
 
-You can use libraries to analyze databases generated from TypeScript codebases. Using these libraries makes it easier for you to write queries.
+When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
 
 Overview
 --------

docs/language/learn-ql/javascript/ql-for-javascript.rst

@@ -4,7 +4,6 @@ CodeQL for JavaScript
 Experiment and learn how to write effective and efficient queries for CodeQL databases generated from JavaScript codebases.
 
 .. toctree::
-   :glob:
    :hidden:
 
    introduce-libraries-js
@@ -15,21 +14,21 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
    ast-class-reference
    dataflow-cheat-sheet
 
-These documents provide an overview of the CodeQL libraries for JavaScript and TypeScript and show examples of how to use them.
+-  `Basic JavaScript query <https://lgtm.com/help/lgtm/console/ql-javascript-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
 
--  `Basic JavaScript query <https://lgtm.com/help/lgtm/console/ql-javascript-basic-example>`__ describes how to write and run queries using LGTM.
+-  :doc:`CodeQL library for JavaScript <introduce-libraries-js>`: When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
 
--  :doc:`CodeQL libraries for JavaScript <introduce-libraries-js>` introduces the standard libraries used to write queries for JavaScript code. There is an extensive CodeQL library for analyzing JavaScript code. This tutorial briefly summarizes the most important classes and predicates provided by this library.
+-  :doc:`CodeQL library for TypeScript <introduce-libraries-ts>`: When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
 
--  :doc:`CodeQL libraries for TypeScript <introduce-libraries-ts>` introduces the standard libraries used to write queries for TypeScript code.
+-  :doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`: This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
 
--  :doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for JavaScript/TypeScript.
+-  :doc:`Using flow labels for precise data flow analysis <flow-labels>`: You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.
 
--  :doc:`Using flow labels for precise data flow analysis <flow-labels>` shows a more advanced example of data flow analysis using flow labels.
+-  :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>` gives an overview of all AST classes in the standard CodeQL 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:`Data flow cheat sheet for JavaScript <dataflow-cheat-sheet>` lists parts of the CodeQL libraries that are commonly used for variant analysis and in data flow queries.
+-  :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.
 
 Further reading
 ---------------

docs/language/learn-ql/javascript/type-tracking.rst

@@ -1,8 +1,7 @@
 Using type tracking for API modeling
 ====================================
 
-You can track data through an API by creating a model 
-using the CodeQL type-tracking library for JavaScript.
+You can track data through an API by creating a model using the CodeQL type-tracking library for JavaScript.
 
 Overview
 --------