From 3a4cef646de30c263d4fdc86c34b377cbe8129db Mon Sep 17 00:00:00 2001 From: james Date: Thu, 26 Sep 2019 16:04:01 +0100 Subject: [PATCH] docs: fix some formatting issues --- .../learn-ql/cpp/conversions-classes.rst | 2 +- docs/language/learn-ql/cpp/function-classes.rst | 4 ++++ .../learn-ql/cpp/introduce-libraries-cpp.rst | 4 ++++ .../learn-ql/cpp/zero-space-terminator.rst | 4 ++++ docs/language/learn-ql/csharp/ql-for-csharp.rst | 15 --------------- docs/language/learn-ql/java/call-graph.rst | 2 ++ .../learn-ql/java/expressions-statements.rst | 2 ++ .../learn-ql/java/introduce-libraries-java.rst | 10 +++++++++- .../learn-ql/java/types-class-hierarchy.rst | 2 ++ .../javascript/introduce-libraries-js.rst | 2 +- docs/language/learn-ql/python/functions.rst | 2 ++ .../python/introduce-libraries-python.rst | 16 ++++++++-------- .../learn-ql/python/pointsto-type-infer.rst | 9 +++++---- .../learn-ql/python/statements-expressions.rst | 8 ++++---- 14 files changed, 48 insertions(+), 34 deletions(-) diff --git a/docs/language/learn-ql/cpp/conversions-classes.rst b/docs/language/learn-ql/cpp/conversions-classes.rst index 512d967a53f9..28032a932d24 100644 --- 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 index 5dde2546995c..4b9db11351be 100644 --- 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 `__ 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 index 01f8b244684c..5c287bd7115a 100644 --- 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 index f2d0ae36dbdd..c5c578633e13 100644 --- 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 index 56d8f7ef0171..879d8c151078 100644 --- 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 ` introduces the standard libraries used to write queries for C# code. -.. raw:: html - - - - :doc:`Tutorial: Analyzing data flow in C# ` demonstrates how to write queries using the standard QL for C# data flow and taint tracking libraries. -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - Other resources --------------- diff --git a/docs/language/learn-ql/java/call-graph.rst b/docs/language/learn-ql/java/call-graph.rst index b0c721b1fd7b..3cea5294c0e3 100644 --- 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 `__. 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 index c8882c41792a..0034868f01a8 100644 --- 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 index 32863b099e0b..ef20dd47ccfe 100644 --- 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 `__. 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 `. diff --git a/docs/language/learn-ql/java/types-class-hierarchy.rst b/docs/language/learn-ql/java/types-class-hierarchy.rst index df50e600cf96..9855a0391b28 100644 --- 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 `__. 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 index 0e3a7e5acdd7..0858cbb5f8d8 100644 --- 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 `__, `Class `__ and `Function `__ 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 `__, `Class `__ and `Function `__, 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 `__. 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,7 +137,7 @@ 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 @@ -145,7 +145,7 @@ where ``ex`` is an ``ExceptStmt`` and ``Pass`` is the class representing ``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 index bcbab5204776..1b5817f85347 100644 --- 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 index 9f1a15a6d1af..622733ceb1bf 100644 --- 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: