Merge pull request #2160 from jf205/review-cpp-docs

docs: editorial suggestions to new C/C++ topics

Author: Robert Marsh

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

@@ -3,6 +3,7 @@ Using the guards library in C and C++
 
 Overview
 --------
+
 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,6 +21,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``.
 
 In the following code sample, the call to ``isValid`` controls the calls to ``performAction`` and ``logFailure`` but not the return statement.
@@ -35,7 +37,8 @@ In the following code sample, the call to ``isValid`` controls the calls to ``pe
     }
     return succeeded;
 
-In the following code sample, the call to `isValid` controls the body of the if and also the code after the if.
+In the following code sample, the call to ``isValid`` controls the body of the
+``if`` statement, and also the code after the ``if``.
 
 .. code-block:: cpp
 
@@ -48,14 +51,18 @@ In the following code sample, the call to `isValid` controls the body of the if
 
 The ``ensuresEq`` and ``ensuresLt`` predicates
 ----------------------------------------------
+
 The ``ensuresEq`` and ``ensuresLt`` predicates are the main way of determining what, if any, guarantees the ``GuardCondition`` provides for a given basic block.
 
 The ``ensuresEq`` predicate
 ***************************
+
+
 When ``ensuresEq(left, right, k, block, true)`` holds, then ``block`` is only executed if ``left`` was equal to ``right + k`` at their last evaluation. When ``ensuresEq(left, right, k, block, false)`` holds, then ``block`` is only executed if ``left`` was not equal to ``right + k`` at their last evaluation.
 
 The ``ensuresLt`` predicate
 ***************************
+
 When ``ensuresLt(left, right, k, block, true)`` holds, then ``block`` is only executed if ``left`` was strictly less than ``right + k`` at their last evaluation. When ``ensuresLt(left, right, k, block, false)`` holds, then ``block`` is only executed if ``left`` was greater than or equal to ``right + k`` at their last evaluation.
 
 In the following code sample, the comparison on the first line ensures that ``index`` is less than ``size`` in the "then" block, and that ``index`` is greater than or equal to ``size`` in the "else" block.
@@ -71,13 +78,16 @@ In the following code sample, the comparison on the first line ensures that ``in
 
 The ``comparesEq`` and ``comparesLt`` predicates
 ------------------------------------------------
+
 The ``comparesEq`` and ``comparesLt`` predicates help determine if the ``GuardCondition`` evaluates to true.
 
 The ``comparesEq`` predicate
 ****************************
+
 ``comparesEq(left, right, k, true, testIsTrue)`` holds if ``left`` equals ``right + k`` when the expression evaluates to ``testIsTrue``.
 
 The ``comparesLt`` predicate
 ****************************
+
 ``comparesLt(left, right, k, isLessThan, testIsTrue)`` holds if ``left < right + k`` evaluates to ``isLessThan`` when the expression evaluates to ``testIsTrue``.
 

docs/language/learn-ql/cpp/range-analysis.rst

@@ -3,20 +3,24 @@ Using range analysis for C and C++
 
 Overview
 --------
+
 Range analysis determines upper and lower bounds for an expression.
 
 The range analysis library (defined in ``semmle.code.cpp.rangeanalysis.SimpleRangeAnalysis``) provides a set of predicates for determining constant upper and lower bounds on expressions, as well as recognizing integer overflows. For performance, the library performs automatic widening and therefore may not provide the tightest possible bounds.
 
 Bounds predicates
 -----------------
+
 The ``upperBound`` and ``lowerBound`` predicates provide constant bounds on expressions. No conversions of the argument are included in the bound. In the common case that your query needs to take conversions into account, call them on the converted form, such as ``upperBound(expr.getFullyConverted())``.
 
 Overflow predicates
 -------------------
+
 ``exprMightOverflow`` and related predicates hold if the relevant expression might overflow, as determined by the range analysis library. The ``convertedExprMightOverflow`` family of predicates will take conversions into account.
 
 Example
 -------
+
 This query uses ``upperBound`` to determine whether the result of ``snprintf`` is checked when used in a loop.
 
 .. code-block:: ql

docs/language/learn-ql/cpp/value-numbering-hash-cons.rst

@@ -1,7 +1,9 @@
 Hash consing and value numbering
 =================================================
+
 Overview
 --------
+
 In C and C++ QL databases, each node in the abstract syntax tree is represented by a separate object. This allows both analysis and results display to refer to specific appearances of a piece of syntax. However, it is frequently useful to determine whether two expressions are equivalent, either syntactically or semantically.
 
 The `hash consing <https://en.wikipedia.org/wiki/Hash_consing>`__ library (defined in ``semmle.code.cpp.valuenumbering.HashCons``) provides a mechanism for identifying expressions that have the same syntactic structure. The `global value numbering <https://en.wikipedia.org/wiki/Value_numbering>`__ library (defined in ``semmle.code.cpp.valuenumbering.GlobalValueNumbering``) provides a mechanism for identifying expressions that compute the same value at runtime.
@@ -41,10 +43,12 @@ However, in the next example, the uses of ``x + y`` will have different value nu
 
 Value numbering
 ---------------
+
 The value numbering library (defined in ``semmle.code.cpp.valuenumbering.GlobalValueNumbering``) provides a mechanism for identifying expressions that compute the same value at runtime. Value numbering is useful when your primary concern is with the values being produced or the eventual machine code being run. For instance, value numbering might be used to determine whether a check is being done against the same value as the operation it is guarding.
 
 The value numbering API
 ~~~~~~~~~~~~~~~~~~~~~~~
+
 The value numbering library exposes its interface primarily through the ``GVN`` class. Each instance of ``GVN`` represents a set of expressions that will always evaluate to the same value. To get an expression in the set represented by a particular ``GVN``, use the ``getAnExpr()`` member predicate.
 
 To get the ``GVN`` of an ``Expr``, use the ``globalValueNumber`` predicate.
@@ -55,10 +59,11 @@ To get the ``GVN`` of an ``Expr``, use the ``globalValueNumber`` predicate.
 
 Why not a predicate?
 ~~~~~~~~~~~~~~~~~~~~
+
 The obvious interface for this library would be a predicate ``equivalent(Expr e1, Expr e2)``. However, this predicate would be very large, with a quadratic number of rows for each set of equivalent expressions. By using a class as an intermediate step, the number of rows can be kept linear, and therefore can be cached.
 
-Example Queries
-~~~~~~~~~~~~~~~
+Example query
+~~~~~~~~~~~~~
 
 This query uses the ``GVN`` class to identify calls to ``strncpy`` where the size argument is derived from the source rather than the destination
 
@@ -76,10 +81,12 @@ This query uses the ``GVN`` class to identify calls to ``strncpy`` where the siz
 
 Hash consing
 ------------
+
 The hash consing library (defined in ``semmle.code.cpp.valuenumbering.HashCons``) provides a mechanism for identifying expressions that have the same syntactic structure. Hash consing is useful when your primary concern is with the text of the code. For instance, hash consing might be used to detect duplicate code within a function.
 
 The hash consing API
 ~~~~~~~~~~~~~~~~~~~~
+
 The hash consing library exposes its interface primarily through the ``HashCons`` class. Each instance of ``HashCons`` represents a set of expressions within one function that have the same syntax (including referring to the same variables). To get an expression in the set represented by a particular ``HashCons``, use the ``getAnExpr()`` member predicate.
 
 .. note::
@@ -88,8 +95,8 @@ The hash consing library exposes its interface primarily through the ``HashCons`
 
 To get the ``HashCons`` of an ``Expr``, use the ``hashCons`` predicate.
 
-Examples
-~~~~~~~~
+Example query
+~~~~~~~~~~~~~
 
 .. TODO: prose explanations
 
@@ -104,3 +111,4 @@ Examples
       hashCons(outer.getCondition()) = hashCons(inner.getCondition())
     select inner.getCondition(), "The condition of this if statement duplicates the condition of $@",
       outer.getCondition(), "an enclosing if statement"
+