Merge pull request github#2037 from jf205/python-docs-fixes

Felicity Chapman · web-flow · commit 91a8391c842f · 2019-09-27T08:47:49.000+01:00
docs: fix some formatting issues
diff --git a/docs/language/learn-ql/cpp/conversions-classes.rst b/docs/language/learn-ql/cpp/conversions-classes.rst
@@ -128,7 +128,7 @@ Unlike the earlier versions of the query, this query would return each side of t
 
    Note
    
-    In general, QL predicates named ``getAXxx`` exploit the ability to return multiple results (multiple instances of ``Xxx``) whereas plain ``getXxx`` predicates usually return at most one specific instance of ``Xxx``.
+   In general, QL predicates named ``getAXxx`` exploit the ability to return multiple results (multiple instances of ``Xxx``) whereas plain ``getXxx`` predicates usually return at most one specific instance of ``Xxx``.
 
 Classes
 -------
diff --git a/docs/language/learn-ql/cpp/function-classes.rst b/docs/language/learn-ql/cpp/function-classes.rst
@@ -60,6 +60,10 @@ This query returns fewer results. However, if you examine the results then you c
 
 For example, there is a more complicated LGTM `query <https://lgtm.com/rules/2152580467/>`__ that finds unused static functions. To see the QL code for this query, click **Open in query console** at the top of the page.
 
+.. pull-quote::
+
+   Tip
+
    You can explore the definition of an element in the standard QL libraries and see what predicates are available. Use the keyboard **F3** button to open the definition of any element. Alternatively, hover over the element and click **Jump to definition** in the tooltip displayed. The library file is opened in a new tab with the definition highlighted.
 
 Finding a specific function
diff --git a/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst b/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
@@ -12,6 +12,10 @@ There is an extensive QL library for analyzing C/C++ code. The QL classes in thi
 
 The rest of this topic briefly summarizes the most important QL classes and predicates provided by this library.
 
+.. pull-quote::
+
+   Tip
+
    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 (QL library files are opened in new tabs in the console).
 
 Summary of the library classes
diff --git a/docs/language/learn-ql/cpp/zero-space-terminator.rst b/docs/language/learn-ql/cpp/zero-space-terminator.rst
@@ -87,6 +87,10 @@ Now we can write a query using these classes:
 
 Note that there is no need to check whether anything is added to the ``strlen`` expression, as it would be in the corrected C code ``malloc(strlen(string) + 1)``. This is because the corrected code would in fact be an ``AddExpr`` containing a ``StrlenCall``, not an instance of ``StrlenCall`` itself. A side-effect of this approach is that we omit certain unlikely patterns such as ``malloc(strlen(string) + 0``). In practice we can always come back and extend our query to cover this pattern if it is a concern.
 
+.. pull-quote::
+
+   Tip
+
    For some projects, this query may not return any results. Possibly the project you are querying does not have any problems of this kind, but it is also important to make sure the query itself is working properly. One solution is to set up a test project with examples of correct and incorrect code to run the query against (the C code at the very top of this page makes a good starting point). Another approach is to test each part of the query individually to make sure everything is working.
 
 When you have defined the basic query then you can refine the query to include further coding patterns or to exclude false positives:
diff --git a/docs/language/learn-ql/csharp/ql-for-csharp.rst b/docs/language/learn-ql/csharp/ql-for-csharp.rst
@@ -14,23 +14,8 @@ These topics provide an overview of the QL C# libraries and show examples of how
 
 -  :doc:`Introducing the C# libraries <introduce-libraries-csharp>` introduces the standard libraries used to write queries for C# code.
 
-.. raw:: html
-
-   <!-- Working with generic types and methods(generics) - how to query generic types and methods. -->
-
 -  :doc:`Tutorial: Analyzing data flow in C# <dataflow>` demonstrates how to write queries using the standard QL for C# data flow and taint tracking libraries.
 
-.. raw:: html
-
-   <!-- Working with call graphs(call-graph) - how to construct and query call graphs, and work with dynamic and virtual dispatch. -->
-
-.. raw:: html
-
-   <!-- Working with control flow(control-flow) - how to query intra-procedural control flow. -->
-
-.. raw:: html
-
-   <!-- Working with comments(comments) - how to query comments and XML documentation. -->
 
 Other resources
 ---------------
diff --git a/docs/language/learn-ql/java/call-graph.rst b/docs/language/learn-ql/java/call-graph.rst
@@ -78,6 +78,8 @@ Given this API, we can easily write a query that finds methods that are not call
 
 ➤ `See this in the query console <https://lgtm.com/query/665280012/>`__. This simple query typically returns a large number of results.
 
+.. pull-quote::
+
    Note
 
    We have to use ``polyCalls`` instead of ``calls`` here: we want to be reasonably sure that ``callee`` is not called, either directly or via overriding.
diff --git a/docs/language/learn-ql/java/expressions-statements.rst b/docs/language/learn-ql/java/expressions-statements.rst
@@ -18,6 +18,8 @@ Specifically, consider the following code snippet:
 
 If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``int``), then this loop will never terminate: ``i`` will start at zero, being incremented all the way up to 2\ :sup:`31`\ - 1, which is still smaller than ``l``. When it is incremented once more, an arithmetic overflow occurs, and ``i`` becomes -2\ :sup:`31`\, which also is smaller than ``l``! Eventually, ``i`` will reach zero again, and the cycle repeats.
 
+.. pull-quote::   
+
    More about overflow
 
    All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value.
diff --git a/docs/language/learn-ql/java/introduce-libraries-java.rst b/docs/language/learn-ql/java/introduce-libraries-java.rst
@@ -14,6 +14,10 @@ The library is implemented as a set of QL modules, that is, files with the exten
 
 The rest of this topic briefly summarizes the most important QL classes and predicates provided by this library.
 
+.. pull-quote::
+
+   Note
+
    The example queries in this topic illustrate the types of results returned by different library classes. The results themselves are not interesting but can be used as the basis for developing a more complex query. The tutorial topics show how you can take a simple query and fine-tune it to find precisely the results you're interested in.
 
 Summary of the library classes
@@ -315,7 +319,11 @@ Class ``Javadoc`` represents an entire Javadoc comment as a tree of ``JavadocEle
 
 ➤ `See this in the query console <https://lgtm.com/query/670490015/>`__. None of the LGTM.com demo projects uses the ``@author`` tag on private fields.
 
-   Note that on line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment.
+.. pull-quote::
+
+   Note
+
+   On line 5 we used ``getParent+`` to capture tags that are nested at any depth within the Javadoc comment.
 
 For more information on working with Javadoc, see the :doc:`tutorial on Javadoc <javadoc>`.
 
diff --git a/docs/language/learn-ql/java/types-class-hierarchy.rst b/docs/language/learn-ql/java/types-class-hierarchy.rst
@@ -32,6 +32,8 @@ To determine ancestor types (including immediate super types, and also *their* s
 
 ➤ `See this in the query console <https://lgtm.com/query/674620010/>`__. If this query were run on the example snippet above, the query would return ``A``, ``I``, and ``java.lang.Object``.
 
+.. pull-quote::
+
    Tip
 
    If you want to see the ___location of ``B`` as well as ``A``, you can replace ``B.getASupertype+()`` with ``B.getASupertype*()`` and re-run the query.
diff --git a/docs/language/learn-ql/javascript/introduce-libraries-js.rst b/docs/language/learn-ql/javascript/introduce-libraries-js.rst
@@ -224,7 +224,7 @@ The `TopLevel <https://help.semmle.com/qldoc/javascript/semmle/javascript/AST.ql
 
 .. pull-quote::
 
-    Note
+   Note
 
    By default, LGTM filters out alerts in minified top-levels, since they are often hard to interpret. When writing your own queries in the LGTM query console, this filtering is *not* done automatically, so you may want to explicitly add a condition of the form ``and not e.getTopLevel().isMinified()`` or similar to your query to exclude results in minified code.
 
diff --git a/docs/language/learn-ql/python/functions.rst b/docs/language/learn-ql/python/functions.rst
@@ -10,6 +10,8 @@ In this example we look for all the "getters" in a program. Programmers moving t
 
 Using the member predicate ``Function.getName()``, we can list all of the getter functions in a snapshot:
 
+.. pull-quote::
+
    Tip
 
    Instead of copying this query, try typing the code. As you start to write a name that matches a library class, a pop-up is displayed making it easy for you to select the class that you want.
diff --git a/docs/language/learn-ql/python/introduce-libraries-python.rst b/docs/language/learn-ql/python/introduce-libraries-python.rst
@@ -33,7 +33,7 @@ This part of the library represents the Python source code. The ``Module``, ``Cl
 Scope
 ^^^^^
 
-A Python program is a group of modules. Technically a module is just a list of statements, but we often think of it as composed of classes and functions. These top-level entities, the module, class and function are represented by the three classes (`Module <https://help.semmle.com/qldoc/python/semmle/python/Module.qll/type.Module$Module.html>`__, `Class <https://help.semmle.com/qldoc/python/semmle/python/Class.qll/type.Class$Class.html>`__ and `Function <https://help.semmle.com/qldoc/python/semmle/python/Function.qll/type.Function$Function.html>`__ which are all subclasses of ``Scope``.
+A Python program is a group of modules. Technically a module is just a list of statements, but we often think of it as composed of classes and functions. These top-level entities, the module, class and function are represented by the three classes `Module <https://help.semmle.com/qldoc/python/semmle/python/Module.qll/type.Module$Module.html>`__, `Class <https://help.semmle.com/qldoc/python/semmle/python/Class.qll/type.Class$Class.html>`__ and `Function <https://help.semmle.com/qldoc/python/semmle/python/Function.qll/type.Function$Function.html>`__, which are all subclasses of ``Scope``.
 
 -  ``Scope``
 
@@ -110,12 +110,12 @@ Examples
 
 Each syntactic element in Python source is recorded in the snapshot. These can be queried via the corresponding class. Let us start with a couple of simple examples.
 
-1. Finding all finally blocks
-'''''''''''''''''''''''''''''
+1. Finding all ``finally`` blocks
+'''''''''''''''''''''''''''''''''
 
 For our first example, we can find all ``finally`` blocks by using the ``Try`` class:
 
-**Find all ``finally`` blocks**
+**Find all** ``finally`` **blocks**
 
 .. code-block:: ql
 
@@ -126,8 +126,8 @@ For our first example, we can find all ``finally`` blocks by using the ``Try`` c
 
 ➤ `See this in the query console <https://lgtm.com/query/659662193/>`__. Many projects include examples of this pattern.
 
-2. Finding 'except' blocks that do nothing
-''''''''''''''''''''''''''''''''''''''''''
+2. Finding ``except`` blocks that do nothing
+''''''''''''''''''''''''''''''''''''''''''''
 
 For our second example, we can use a simplified version of a query from the standard query set. We look for all ``except`` blocks that do nothing.
 
@@ -137,15 +137,15 @@ A block that does nothing is one that contains no statements except ``pass`` sta
 
    not exists(Stmt s | s = ex.getAStmt() | not s instanceof Pass)
 
-where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``pass`` statements. Instead of using the double negative, **"no**\ *statements that are*\ **not**\ *pass statements"*, this can also be expressed positively, "all statements must be pass statements." The positive form is expressed in QL using the ``forall`` quantifier:
+where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``pass`` statements. Instead of using the double negative, *no statements that are not pass statements*, this can also be expressed positively, *all statements must be pass statements*. The positive form is expressed in QL using the ``forall`` quantifier:
 
 .. code-block:: ql
 
    forall(Stmt s | s = ex.getAStmt() | s instanceof Pass)
 
 Both forms are equivalent. Using the positive QL expression, the whole query looks like this:
 
-**Find pass-only ``except`` blocks**
+**Find pass-only** ``except`` **blocks**
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/python/pointsto-type-infer.rst b/docs/language/learn-ql/python/pointsto-type-infer.rst
@@ -37,7 +37,8 @@ The predicate ``ControlFlowNode.pointsTo(...)`` shows which object a control flo
    predicate pointsTo(Context context, Value object, ControlFlowNode origin)
 
 ``object`` is an object that the control flow node refers to, and ``origin`` is where the object comes from, which is useful for displaying meaningful results.
- The third form includes the ``context`` in which the control flow node refers to the ``object``. This form can usually be ignored.
+
+The third form includes the ``context`` in which the control flow node refers to the ``object``. This form can usually be ignored.
 
 .. pull-quote::
 
@@ -62,7 +63,7 @@ We want to find ``except`` blocks in a ``try`` statement that are in the wrong o
 
 First we can write a query to find ordered pairs of ``except`` blocks for a ``try`` statement.
 
-**Ordered except blocks in same ``try`` statement**
+**Ordered except blocks in same** ``try`` **statement**
 
 .. code-block:: ql
 
@@ -81,7 +82,7 @@ Here ``ex1`` and ``ex2`` are both ``except`` handlers in the ``try`` statement `
 
 The results of this query need to be filtered to return only results where ``ex1`` is more general than ``ex2``. We can use the fact that an ``except`` block is more general than another block if the class it handles is a superclass of the other.
 
-**More general ``except`` block**
+**More general** ``except`` **block**
 
 .. code-block:: ql
 
@@ -102,7 +103,7 @@ ensures that ``cls1`` is a ``ClassValue`` that the ``except`` block would handle
 
 Combining the parts of the query we get this:
 
-**More general ``except`` block precedes more specific**
+**More general** ``except`` **block precedes more specific**
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/python/statements-expressions.rst b/docs/language/learn-ql/python/statements-expressions.rst
@@ -143,7 +143,7 @@ Python implementations commonly cache small integers and single character string
 
 We can check for these as follows:
 
-**Find comparisons to integer or string literals using ``is``**
+**Find comparisons to integer or string literals using** ``is``
 
 .. code-block:: ql
 
@@ -158,6 +158,8 @@ We can check for these as follows:
 
 The clause ``cmp.getOp(0) instanceof Is and cmp.getComparator(0) = literal`` checks that the first comparison operator is "is" and that the first comparator is a literal.
 
+.. pull-quote::
+
    Tip
 
    We have to use ``cmp.getOp(0)`` and ``cmp.getComparator(0)``\ as there is no ``cmp.getOp()`` or ``cmp.getComparator()``. The reason for this is that a ``Compare`` expression can have multiple operators. For example, the expression ``3 < x < 7`` has two operators and two comparators. You use ``cmp.getComparator(0)`` to get the first comparator (in this example the ``3``) and ``cmp.getComparator(1)`` to get the second comparator (in this example the ``7``).
@@ -253,9 +255,7 @@ checks that the value of the attribute (the expression to the left of the dot in
 Class and function definitions
 ------------------------------
 
-As Python is a dynamically typed language, class, and function definitions are executable statements. This means that a class statement is both a statement and a scope containing statements. To represent this cleanly the class definition is broken into a number of parts. At runtime, when a class definition is executed a class object is created and then assigned to a variable of the same name in the scope enclosing the class. This class is created from a code-object representing the source code for the body of the class. To represent this the ``ClassDef`` class (which represents a ``class`` statement) subclasses ``Assign``. The ``Class`` class, which represents the body of the class, can be accessed via the ``ClassDef.getDefinedClass()``
-
-``FunctionDef``, ``Function`` are handled similarly.
+As Python is a dynamically typed language, class, and function definitions are executable statements. This means that a class statement is both a statement and a scope containing statements. To represent this cleanly the class definition is broken into a number of parts. At runtime, when a class definition is executed a class object is created and then assigned to a variable of the same name in the scope enclosing the class. This class is created from a code-object representing the source code for the body of the class. To represent this the ``ClassDef`` class (which represents a ``class`` statement) subclasses ``Assign``. The ``Class`` class, which represents the body of the class, can be accessed via the ``ClassDef.getDefinedClass()``. ``FunctionDef`` and ``Function`` are handled similarly.
 
 Here is the relevant part of the class hierarchy:
 
