docs: update titles, some links, add intros

james · james · commit d3eb5334b82e · 2020-02-19T07:37:35.000Z
diff --git a/docs/language/learn-ql/cpp/conversions-classes.rst b/docs/language/learn-ql/cpp/conversions-classes.rst
@@ -1,10 +1,7 @@
-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
 -----------
@@ -227,7 +224,7 @@ 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>`__.
diff --git a/docs/language/learn-ql/cpp/dataflow.rst b/docs/language/learn-ql/cpp/dataflow.rst
@@ -1,8 +1,7 @@
-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 code base.
 
 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.
@@ -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>`__.
 
diff --git a/docs/language/learn-ql/cpp/expressions-types.rst b/docs/language/learn-ql/cpp/expressions-types.rst
@@ -1,8 +1,7 @@
-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.
 
@@ -136,6 +135,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>`__.
diff --git a/docs/language/learn-ql/cpp/function-classes.rst b/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>`__.
diff --git a/docs/language/learn-ql/cpp/guards.rst b/docs/language/learn-ql/cpp/guards.rst
@@ -1,6 +1,8 @@
 Using the guards library in C and C++
 =====================================
 
+You can use the CodeQL guards library to identify conditional expressions that control the execution of other code in C and C++ codebases. 
+
 Overview
 --------
 
diff --git a/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst b/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
@@ -1,18 +1,23 @@
-Introducing the CodeQL libraries for C/C++
-==========================================
+CodeQL libraries for C and C++
+==============================
+
+Explore the standard CodeQL libraries for C and C++.
 
 Overview
 --------
 
-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:
+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.
+.. pull-quote:: 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
 ------------------------------
@@ -522,6 +527,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>`__.
diff --git a/docs/language/learn-ql/cpp/private-field-initialization.rst b/docs/language/learn-ql/cpp/private-field-initialization.rst
@@ -1,5 +1,7 @@
-Example: Checking that constructors initialize all private fields
-=================================================================
+Refining a query to account for edge cases
+==========================================
+
+You can improve the results generated by a CodeQL query by adding conditions to remove false positives caused by common edge cases.
 
 Overview
 --------
@@ -147,6 +149,6 @@ Finally we can simplify the query by using the `transitive closure operator <htt
 What next?
 ----------
 
--  Take a look at another example: :doc:`Checking for allocations equal to 'strlen(string)' without space for a null terminator <zero-space-terminator>`.
+-  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>`__.
 -  Learn more about the query console in `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.
diff --git a/docs/language/learn-ql/cpp/range-analysis.rst b/docs/language/learn-ql/cpp/range-analysis.rst
@@ -1,6 +1,8 @@
 Using range analysis for C and C++
 ==================================
 
+You can use range analysis to determine the upper or lower bounds on an expression, or whether an expression could potentially over or underflow.
+
 Overview
 --------
 
diff --git a/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst b/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst
@@ -1,5 +1,7 @@
 Hash consing and value numbering
-=================================================
+================================
+
+You can use specialized CodeQL libraries to recognize expressions that are syntactically identical or compute the same value at runtime in C and C++ codebases.
 
 Overview
 --------
diff --git a/docs/language/learn-ql/cpp/zero-space-terminator.rst b/docs/language/learn-ql/cpp/zero-space-terminator.rst
@@ -1,5 +1,7 @@
-Example: Checking for allocations equal to ``strlen(string)`` without space for a null terminator
-=================================================================================================
+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
 --------
