Merge pull request github#3146 from jf205/tidy-up-docs-prep

CodeQL docs: tidy up 'docs-preparation' branch following pre-migration work

Author: jf205

docs/language/learn-ql/beginner/ql-tutorials.rst

@@ -6,8 +6,14 @@ Solve puzzles to learn the basics of QL before you analyze code with CodeQL. The
 Before starting these tutorials, you can read the :doc:`Introduction to QL <../introduction-to-ql>` for a description of the language and some simple examples.
 
 .. toctree::
+   :hidden:
 
    find-the-thief
    catch-the-fire-starter
    crown-the-rightful-heir
    cross-the-river
+
+-  :doc:`Find the thief <find-the-thief>`:Take on the role of a detective to find the thief in this fictional village. You will learn how to use logical connectives, quantifiers, and aggregates in QL along the way.
+-  :doc:`Catch the fire starter <catch-the-fire-starter>`: Learn about QL predicates and classes to solve your second mystery as a QL detective.
+-  :doc:`Crown the rightful heir <crown-the-rightful-heir>`: This is a QL detective puzzle that shows you how to use recursion in QL to write more complex queries.
+-  :doc:`Cross the river <cross-the-river>`: Use common QL features to write a query that finds a solution to the "River crossing" logic puzzle.

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

@@ -145,7 +145,7 @@ SQL
 Calls to the SQL system through ``EXEC SQL`` are represented by the class
 `SqlStmt <https://help.semmle.com/qldoc/cobol/semmle/cobol/Sql.qll/type.Sql$SqlStmt.html>`__ and its subclasses.
 
-What next?
-----------
+Further reading
+---------------
 
 -  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>`__.

docs/language/learn-ql/cpp/conversions-classes.rst

@@ -220,8 +220,8 @@ That completes the query.
 
 There is a similar built-in `query <https://lgtm.com/rules/2158670642/>`__ on LGTM.com that finds classes in a C/C++ project with virtual functions but no virtual destructor. You can take a look at the code for this query by clicking **Open in query console** at the top of that page.
 
-What next?
-----------
+Further reading
+---------------
 
 -  Explore other ways of querying classes using examples from the `C/C++ cookbook <https://help.semmle.com/wiki/label/CBCPP/class>`__.
 -  Take a look at the :doc:`Analyzing data flow in C and C++ <dataflow>` tutorial.

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
 ---------------
@@ -295,8 +295,8 @@ Exercise 3: Write a class that represents flow sources from ``getenv``. (`Answer
 
 Exercise 4: Using the answers from 2 and 3, write a query which finds all global data flows from ``getenv`` to ``gethostbyname``. (`Answer <#exercise-4>`__)
 
-What next?
-----------
+Further reading
+---------------
 
 -  Try the worked examples in the following topics: :doc:`Refining a query to account for edge cases <private-field-initialization>` and :doc:`Detecting a potential buffer overflow <zero-space-terminator>`.
 -  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>`__.

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

@@ -129,8 +129,8 @@ We can find assignments inside the loop body using similar code with the predica
 
 Note that we replaced ``e.getEnclosingStmt()`` with ``e.getEnclosingStmt().getParentStmt*()``, to find an assignment expression that is deeply nested inside the loop body. The transitive closure modifier ``*`` here indicates that ``Stmt.getParentStmt()`` may be followed zero or more times, rather than just once, giving us the statement, its parent statement, its parent's parent statement etc.
 
-What next?
-----------
+Further reading
+---------------
 
 -  Explore other ways of finding types and statements using examples from the C/C++ cookbook for `types <https://help.semmle.com/wiki/label/CBCPP/type>`__ and `statements <https://help.semmle.com/wiki/label/CBCPP/statement>`__.
 -  Take a look at the :doc:`Conversions and classes in C and C++ <conversions-classes>` and :doc:`Analyzing data flow in C and C++ <dataflow>` tutorials.

docs/language/learn-ql/cpp/function-classes.rst

@@ -89,8 +89,8 @@ Note that we could have used ``Declaration.getName()``, but ``Declaration.getQua
 
 The LGTM version of this query is considerably more complicated, but if you look carefully you will find that its structure is the same. See `Non-constant format string <https://lgtm.com/rules/2152810612/>`__ and click **Open in query console** at the top of the page.
 
-What next?
-----------
+Further reading
+---------------
 
 -  Explore other ways of finding functions using examples from the `C/C++ cookbook <https://help.semmle.com/wiki/label/CBCPP/function>`__.
 -  Take a look at some other tutorials: :doc:`Expressions, types and statements in C and C++ <introduce-libraries-cpp>`, :doc:`Conversions and classes in C and C++ <conversions-classes>`, and :doc:`Analyzing data flow in C and C++ <dataflow>`.

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

@@ -520,8 +520,8 @@ This table lists `Preprocessor <https://help.semmle.com/qldoc/cpp/semmle/code/cp
 +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 
-What next?
-----------
+Further reading
+---------------
 
 -  Experiment with the worked examples in the CodeQL for C/C++ topics: :doc:`Functions in C and C++ <function-classes>`, :doc:`Expressions, types, and statements in C and C++ <expressions-types>`, :doc:`Conversions and classes in C and C++ <conversions-classes>`, and :doc:`Analyzing data flow in C and C++ <dataflow>`.
 -  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>`__.

docs/language/learn-ql/cpp/private-field-initialization.rst

@@ -146,8 +146,8 @@ Finally we can simplify the query by using the transitive closure operator. In t
 
 ➤ `See this in the query console <https://lgtm.com/query/1505896968215/>`__
 
-What next?
-----------
+Further reading
+---------------
 
 -  Take a look at another example: :doc:`Detecting a potential buffer overflow <zero-space-terminator>`.
 -  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>`__.

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/cpp/zero-space-terminator.rst

@@ -1,12 +1,7 @@
 Detecting a potential buffer overflow
 =====================================
 
-You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
-
-Overview
---------
-
-This topic describes how a C/C++ query for detecting a potential buffer overflow was developed. For a full overview of the topics available for learning to write queries for C/C++ code, see :doc:`CodeQL for C/C++ <ql-for-cpp>`.
+You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++. This topic describes how a C/C++ query for detecting a potential buffer overflow was developed.
 
 Problem—detecting memory allocation that omits space for a null termination character
 -------------------------------------------------------------------------------------
@@ -226,8 +221,8 @@ The completed query will now identify cases where the result of ``strlen`` is st
    where malloc.getAllocatedSize() instanceof StrlenCall
    select malloc, "This allocation does not include space to null-terminate the string."
 
-What next?
-----------
+Further reading
+---------------
 
 -  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>`__.