Merge pull request #2869 from jf205/codeql-migration-2163

CodeQL docs: update titles, add intros, and a few content updates

Author: jf205

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

@@ -1,15 +1,14 @@
-Tutorial: Conversions and classes
-=================================
+Conversions and classes in C and C++
+====================================
 
-Overview
---------
-
-This topic contains worked examples of how to write queries using the CodeQL library classes for C/C++ conversions and classes.
+You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
 
 Conversions
 -----------
 
-Let us take a look at the ``Conversion`` class in the standard library:
+In C and C++, conversions change the type of an expression. They may be implicit conversions generated by the compiler, or explicit conversions requested by the user.
+
+Let's take a look at the `Conversion <https://help.semmle.com/qldoc/cpp/semmle/code/cpp/exprs/Cast.qll/type.Cast$Conversion.html>`__ class in the standard library:
 
 -  ``Expr``
 
@@ -25,8 +24,6 @@ Let us take a look at the ``Conversion`` class in the standard library:
       -  ``ArrayToPointerConversion``
       -  ``VirtualMemberToFunctionPointerConversion``
 
-All conversions change the type of an expression. They may be implicit conversions (generated by the compiler) or explicit conversions (requested by the user).
-
 Exploring the subexpressions of an assignment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -221,13 +218,13 @@ Our last change is to use ``Function.isVirtual()`` to find cases where the base
 
 That completes the query.
 
-There is a similar built-in LGTM `query <https://lgtm.com/rules/2158670642/>`__ 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.
+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?
 ----------
 
 -  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/C++ <dataflow>` tutorial.
--  Try the worked examples in the following topics: :doc:`Example: Checking that constructors initialize all private fields <private-field-initialization>`, and :doc:`Example: Checking for allocations equal to 'strlen(string)' without space for a null terminator <zero-space-terminator>`.
+-  Take a look at the :doc:`Analyzing data flow in C and C++ <dataflow>` tutorial.
+-  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>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.

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

@@ -1,13 +1,12 @@
-Analyzing data flow in C/C++
-============================
+Analyzing data flow in C and C++
+================================
 
-Overview
---------
+You can use data-flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
 
-This topic describes how data flow analysis is implemented in the CodeQL libraries for C/C++ and includes examples to help you write your own data flow queries.
-The following sections describe how to utilize the libraries for local data flow, global data flow, and taint tracking.
+About data flow
+---------------
 
-For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
+Data flow analysis computes 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. In CodeQL, you can model both local data flow and global data flow. For more background information, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
 
 Local data flow
 ---------------
@@ -299,7 +298,7 @@ Exercise 4: Using the answers from 2 and 3, write a query which finds all global
 What next?
 ----------
 
--  Try the worked examples in the following topics: :doc:`Example: Checking that constructors initialize all private fields <private-field-initialization>` and :doc:`Example: Checking for allocations equal to 'strlen(string)' without space for a null terminator <zero-space-terminator>`.
+-  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>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.
 

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

@@ -1,13 +1,10 @@
-Tutorial: Expressions, types and statements
-===========================================
+Expressions, types, and statements in C and C++
+===============================================
 
-Overview
---------
+You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
 
-This topic contains worked examples of how to write queries using the standard CodeQL library classes for C/C++ expressions, types, and statements.
-
-Expressions and types
----------------------
+Expressions and types in CodeQL
+-------------------------------
 
 Each part of an expression in C becomes an instance of the ``Expr`` class. For example, the C code ``x = x + 1`` becomes an ``AssignExpr``, an ``AddExpr``, two instances of ``VariableAccess`` and a ``Literal``. All of these CodeQL classes extend ``Expr``.
 
@@ -34,7 +31,7 @@ It is also worth noting that the query above would find this C code:
 
    yPtr = NULL;
 
-This is because the database contains a representation of the code base after the preprocessor transforms have run (for more information, see `Database generation <https://lgtm.com/help/lgtm/generate-database>`__). This means that any macro invocations, such as the ``NULL`` define used here, are expanded during the creation of the database. If you want to write queries about macros then there are some special library classes that have been designed specifically for this purpose (for example, the ``Macro``, ``MacroInvocation`` classes and predicates like ``Element.isInMacroExpansion()``). In this case, it is good that macros are expanded, but we do not want to find assignments to pointers.
+This is because the database contains a representation of the code base after the preprocessor transforms have run. This means that any macro invocations, such as the ``NULL`` define used here, are expanded during the creation of the database. If you want to write queries about macros then there are some special library classes that have been designed specifically for this purpose (for example, the ``Macro``, ``MacroInvocation`` classes and predicates like ``Element.isInMacroExpansion()``). In this case, it is good that macros are expanded, but we do not want to find assignments to pointers. For more information, see `Database generation <https://lgtm.com/help/lgtm/generate-database>`__ on LGTM.com.
 
 Finding assignments of 0 to an integer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,8 +58,8 @@ This checks that the left side of the assignment has a type that is some kind of
 
    i = 0;
 
-Statements
-----------
+Statements in CodeQL
+--------------------
 
 We can refine the query further using statements. In this case we use the class ``ForStmt``:
 
@@ -136,6 +133,6 @@ What next?
 ----------
 
 -  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 <conversions-classes>` and :doc:`Analyzing data flow in C/C++ <dataflow>` tutorials.
+-  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.
 -  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>`__.

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

@@ -1,10 +1,12 @@
-Tutorial: Function classes
-==========================
+Functions in C and C++
+=======================
+
+You can use CodeQL to explore functions in C and C++ code.
 
 Overview
 --------
 
-The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`Introducing the C/C++ libraries <introduce-libraries-cpp>`).
+The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`CodeQL libraries for C and C++ <introduce-libraries-cpp>`).
 
 The example queries in this topic explore some of the most useful library predicates for querying functions.
 
@@ -26,7 +28,7 @@ This query is very general, so there are probably too many results to be interes
 Finding functions that are not called
 -------------------------------------
 
-It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`Introducing the C/C++ libraries <introduce-libraries-cpp>`). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
+It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`CodeQL libraries for C and C++ <introduce-libraries-cpp>`). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
 
 .. code-block:: ql
 
@@ -91,6 +93,6 @@ What next?
 ----------
 
 -  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 of the other tutorials: :doc:`Expressions, types and statements <expressions-types>`, :doc:`Conversions and classes <conversions-classes>`, and :doc:`Analyzing data flow in C/C++ <dataflow>`.
+-  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>`.
 -  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>`__.

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

@@ -1,8 +1,10 @@
 Using the guards library in C and C++
 =====================================
 
-Overview
---------
+You can use the CodeQL guards library to identify conditional expressions that control the execution of other parts of a program in C and C++ codebases. 
+
+About the guards library
+------------------------
 
 The guards library (defined in ``semmle.code.cpp.controlflow.Guards``) provides a class `GuardCondition <https://help.semmle.com/qldoc/cpp/semmle/code/cpp/controlflow/Guards.qll/type.Guards$GuardCondition.html>`__ representing Boolean values that are used to make control flow decisions.
 A ``GuardCondition`` is considered to guard a basic block if the block can only be reached if the ``GuardCondition`` is evaluated a certain way. For instance, in the following code, ``x < 10`` is a ``GuardCondition``, and it guards all the code before the return statement.
@@ -20,7 +22,7 @@ A ``GuardCondition`` is considered to guard a basic block if the block can only
 
 
 The ``controls`` predicate
-------------------------------------------------
+--------------------------
 
 The ``controls`` predicate helps determine which blocks are only run when the ``GuardCondition`` evaluates a certain way. ``guard.controls(block, testIsTrue)`` holds if ``block`` is only entered if the value of this condition is ``testIsTrue``.
 

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

@@ -1,20 +1,21 @@
-Introducing the CodeQL libraries for C/C++
-==========================================
+CodeQL library for C and C++
+============================
 
-Overview
---------
+When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
 
-There is an extensive library for analyzing CodeQL databases extracted from C/C++ 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.  The library is implemented as a set of QL modules, that is, files with the extension ``.qll``. The module ``cpp.qll`` imports all the core C/C++ library modules, so you can include the complete library by beginning your query with:
+About the CodeQL library for C and C++
+--------------------------------------
+
+There is an extensive library for analyzing CodeQL databases extracted from C/C++ 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. 
+The library is implemented as a set of QL modules, that is, files with the extension ``.qll``. The module ``cpp.qll`` imports all the core C/C++ library modules, so you can include the complete library by beginning your query with:
 
 .. code-block:: ql
 
    import cpp
 
 The rest of this topic summarizes the available CodeQL classes and corresponding C/C++ constructs.
 
-NOTE: You can find related classes and features using the query console's auto-complete feature.  You can also press *F3* to jump to the definition of any element; library files are opened in new tabs in the console.
-
-Summary of the library classes
+Commonly-used library classes
 ------------------------------
 
 The most commonly used standard library classes are listed below.  The listing is broken down by functionality. Each library class is annotated with a C/C++ construct it corresponds to.
@@ -522,6 +523,6 @@ This table lists `Preprocessor <https://help.semmle.com/qldoc/cpp/semmle/code/cp
 What next?
 ----------
 
--  Experiment with the worked examples in the CodeQL for C/C++ topics: :doc:`Function classes <function-classes>`, :doc:`Expressions, types and statements <expressions-types>`, :doc:`Conversions and classes <conversions-classes>`, and :doc:`Analyzing data flow in C/C++ <dataflow>`.
+-  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>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.