docs: 'What's new' -> 'Further reading'

2026-04-28 02:05:14 +02:00 · 2020-03-27 07:38:05 +00:00
parent deb657acdb
commit 76f344638e
15 changed files with 41 additions and 32 deletions
--- a/docs/language/learn-ql/beginner/ql-tutorials.rst
+++ b/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.
--- a/docs/language/learn-ql/cobol/introduce-libraries-cobol.rst
+++ b/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>`__.
--- a/docs/language/learn-ql/cpp/conversions-classes.rst
+++ b/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.
--- a/docs/language/learn-ql/cpp/dataflow.rst
+++ b/docs/language/learn-ql/cpp/dataflow.rst
@@ -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>`__.
--- a/docs/language/learn-ql/cpp/expressions-types.rst
+++ b/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.
--- a/docs/language/learn-ql/cpp/function-classes.rst
+++ b/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>`.
--- a/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
+++ b/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>`__.
--- a/docs/language/learn-ql/cpp/private-field-initialization.rst
+++ b/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>`__.
--- a/docs/language/learn-ql/cpp/zero-space-terminator.rst
+++ b/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>`__.
--- a/docs/language/learn-ql/csharp/dataflow.rst
+++ b/docs/language/learn-ql/csharp/dataflow.rst
@@ -8,7 +8,6 @@ About this article

 This article describes how data flow analysis is implemented in the CodeQL libraries for C# and includes examples to help you write your own data flow queries.
 The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
-
 For a more general introduction to modeling data flow, see :doc:`About data flow analysis <../intro-to-data-flow>`.

 Local data flow
--- a/docs/language/learn-ql/java/dataflow.rst
+++ b/docs/language/learn-ql/java/dataflow.rst
@@ -253,8 +253,8 @@ Exercise 3: Write a class that represents flow sources from ``java.lang.System.g

 Exercise 4: Using the answers from 2 and 3, write a query which finds all global data flows from ``getenv`` to ``java.net.URL``. (`Answer <#exercise-4>`__)

-What next?
----------
+Further reading
+---------------

 -  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>`__.
--- a/docs/language/learn-ql/javascript/dataflow.rst
+++ b/docs/language/learn-ql/javascript/dataflow.rst
@@ -464,8 +464,8 @@ Hint: array indices are properties with numeric names; you can use regular expre
 Exercise 4: Using the answers from 2 and 3, write a query which finds all global data flows from array elements of the result of a call to the ``tagName`` argument to the
 ``createElement`` function. (`Answer <#exercise-4>`__)

-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>`__.
--- a/docs/language/learn-ql/javascript/type-tracking.rst
+++ b/docs/language/learn-ql/javascript/type-tracking.rst
@@ -518,8 +518,8 @@ Type tracking is used in a few places in the standard libraries:
 - The `Firebase <https://help.semmle.com/qldoc/javascript/semmle/javascript/frameworks/Firebase.qll/module.Firebase$Firebase.html>`__ and
  `Socket.io <https://help.semmle.com/qldoc/javascript/semmle/javascript/frameworks/SocketIO.qll/module.SocketIO$SocketIO.html>`__ models use type tracking to track objects coming from their respective APIs.

-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>`__.
--- a/docs/language/learn-ql/writing-queries/query-metadata.rst
+++ b/docs/language/learn-ql/writing-queries/query-metadata.rst
@@ -1,7 +1,7 @@
 Metadata for CodeQL queries
 ===========================

-Metadata is used to tell users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
+Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.

 About query metadata
 --------------------
--- a/docs/language/learn-ql/writing-queries/writing-queries.rst
+++ b/docs/language/learn-ql/writing-queries/writing-queries.rst
@@ -4,7 +4,7 @@ CodeQL queries
 CodeQL queries are used in code scanning analyses to find problems in source code, including potential security vulnerabilities.

 .. toctree::
-   :maxdepth: 1
+   :hidden:

   introduction-to-queries
   query-metadata
@@ -13,4 +13,13 @@ CodeQL queries are used in code scanning analyses to find problems in source cod
   ../locations
   ../intro-to-data-flow
   path-queries
-   debugging-queries
+   debugging-queries
+
+- :doc:`About CodeQL queries <introduction-to-queries>`: CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability. 
+- :doc:`Metadata for CodeQL queries <query-metadata>`: Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
+- :doc:`Query help files <query-help>`: Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.
+- :doc:`Defining the results of a query <select-statement>`: You can control how analysis results are displayed in source code by modifying a query's ``select`` statement.
+- :doc:`Providing locations in CodeQL queries <../locations>`: CodeQL includes mechanisms for extracting the location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
+- :doc:`About data flow analysis <../intro-to-data-flow>`: Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
+- :doc:`Creating path queries <path-queries>`: You can create path queries to visualize the flow of information through a codebase.
+- :doc:`trouble shooting query performance <debugging-queries>`: Improve the performance of your CodeQL queries by following a few simple guidelines.