From 050b15103e158b80c1305aae9a73a0c45b35d1c0 Mon Sep 17 00:00:00 2001 From: Shati Patel <42641846+shati-patel@users.noreply.github.com> Date: Wed, 23 Dec 2020 17:13:24 +0000 Subject: [PATCH] Convert remaining notes to pull-quote directives --- docs/codeql/codeql-cli/creating-codeql-query-suites.rst | 4 ++-- .../hash-consing-and-value-numbering.rst | 4 ++-- docs/codeql/ql-language-reference/annotations.rst | 3 ++- .../ql-language-reference/evaluation-of-ql-programs.rst | 4 +++- docs/codeql/ql-language-reference/expressions.rst | 3 ++- docs/codeql/ql-language-reference/formulas.rst | 3 ++- docs/codeql/ql-language-reference/predicates.rst | 3 ++- docs/codeql/ql-language-reference/types.rst | 8 ++++++-- 8 files changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/codeql/codeql-cli/creating-codeql-query-suites.rst b/docs/codeql/codeql-cli/creating-codeql-query-suites.rst index 2ded0522cc9..9c3579acd4a 100644 --- a/docs/codeql/codeql-cli/creating-codeql-query-suites.rst +++ b/docs/codeql/codeql-cli/creating-codeql-query-suites.rst @@ -16,7 +16,7 @@ mapping with (usually) a single key. The instructions are executed in the order they appear in the query suite definition. After all the instructions in the suite definition have been executed, the result is a set of selected queries. -.. note:: +.. pull-quote:: Note Any custom queries that you want to add to a query suite must be in a :doc:`QL pack ` and contain the correct query metadata. @@ -54,7 +54,7 @@ queries using: - qlpack: -.. note:: +.. pull-quote:: Note When pathnames appear in query suite definitions, they must always be given with a forward slash, ``/``, as a directory separator. diff --git a/docs/codeql/codeql-language-guides/hash-consing-and-value-numbering.rst b/docs/codeql/codeql-language-guides/hash-consing-and-value-numbering.rst index 80f063386b8..8afa51e3e53 100644 --- a/docs/codeql/codeql-language-guides/hash-consing-and-value-numbering.rst +++ b/docs/codeql/codeql-language-guides/hash-consing-and-value-numbering.rst @@ -54,7 +54,7 @@ The value numbering library exposes its interface primarily through the ``GVN`` To get the ``GVN`` of an ``Expr``, use the ``globalValueNumber`` predicate. -.. note:: +.. pull-quote:: Note While the ``GVN`` class has ``toString`` and ``getLocation`` methods, these are only provided as debugging aids. They give the ``toString`` and ``getLocation`` of an arbitrary ``Expr`` within the set. @@ -90,7 +90,7 @@ 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:: +.. pull-quote:: Note While the ``HashCons`` class has ``toString`` and ``getLocation`` methods, these are only provided as debugging aids. They give the ``toString`` and ``getLocation`` of an arbitrary ``Expr`` within the set. diff --git a/docs/codeql/ql-language-reference/annotations.rst b/docs/codeql/ql-language-reference/annotations.rst index cd9f2c72860..cbd06220e6c 100644 --- a/docs/codeql/ql-language-reference/annotations.rst +++ b/docs/codeql/ql-language-reference/annotations.rst @@ -203,7 +203,8 @@ change this definition. In this case, ``hasName`` should be final: **Available for**: |classes| -.. important:: +.. pull-quote:: Important + This annotation is deprecated. Instead of annotating a name with ``library``, put it in a private (or privately imported) module. diff --git a/docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst b/docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst index 507c1456582..c7a8698b0cd 100644 --- a/docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst +++ b/docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst @@ -96,7 +96,9 @@ To do this, you can use the following mechanisms: :ref:`binds ` all its arguments. Therefore, if you :ref:`call ` a predicate on a variable, the variable becomes bound. - .. important:: If a predicate uses non-standard binding sets, then it does **not** always bind + .. pull-quote:: Important + + If a predicate uses non-standard binding sets, then it does **not** always bind all its arguments. In such a case, whether the predicate call binds a specific argument depends on which other arguments are bound, and what the binding sets say about the argument in question. For more information, see ":ref:`binding-sets`." diff --git a/docs/codeql/ql-language-reference/expressions.rst b/docs/codeql/ql-language-reference/expressions.rst index 2bd89d8ab8d..683487a8277 100644 --- a/docs/codeql/ql-language-reference/expressions.rst +++ b/docs/codeql/ql-language-reference/expressions.rst @@ -552,7 +552,8 @@ The following table lists some examples of different forms of ``any`` expression | ``any(int i | i = [0 .. 3] | i * i)`` | the integers ``0``, ``1``, ``4``, and ``9`` | +------------------------------------------+-------------------------------------------------+ -.. note:: +.. pull-quote:: Note + There is also a `built-in predicate `_ ``any()``. This is a predicate that always holds. diff --git a/docs/codeql/ql-language-reference/formulas.rst b/docs/codeql/ql-language-reference/formulas.rst index 1354f087d0d..0da70a00790 100644 --- a/docs/codeql/ql-language-reference/formulas.rst +++ b/docs/codeql/ql-language-reference/formulas.rst @@ -318,7 +318,8 @@ The following query selects files that are not HTML files. where not f.getFileType().isHtml() select f -.. note:: +.. pull-quote:: Note + You should be careful when using ``not`` in a recursive definition, as this could lead to non-monotonic recursion. For more information, ":ref:`non-monotonic-recursion`." diff --git a/docs/codeql/ql-language-reference/predicates.rst b/docs/codeql/ql-language-reference/predicates.rst index 520d5a29216..a66f0ff1279 100644 --- a/docs/codeql/ql-language-reference/predicates.rst +++ b/docs/codeql/ql-language-reference/predicates.rst @@ -55,7 +55,8 @@ When defining a predicate, you should specify: argument type and an identifier for the argument variable. #. The predicate body itself. This is a logical formula enclosed in braces. -.. note:: +.. pull-quote:: Note + An :ref:`abstract` or :ref:`external` predicate has no body. To define such a predicate, end the predicate definition with a semicolon (``;``) instead. diff --git a/docs/codeql/ql-language-reference/types.rst b/docs/codeql/ql-language-reference/types.rst index a8c8c4bd5bc..5ae49c7745f 100644 --- a/docs/codeql/ql-language-reference/types.rst +++ b/docs/codeql/ql-language-reference/types.rst @@ -366,7 +366,9 @@ value, namely 2. It inherits member predicates from ``OneTwo`` and ``TwoThree``. It also (indirectly) inherits from ``OneTwoThree`` and ``int``. -.. note:: If a subclass inherits multiple definitions for the same predicate name, then it +.. pull-quote:: Note + + If a subclass inherits multiple definitions for the same predicate name, then it must :ref:`override ` those definitions to avoid ambiguity. :ref:`Super expressions ` are often useful in this situation. @@ -397,7 +399,9 @@ in the characteristic predicate of a class. Algebraic datatypes ******************* -.. note:: The syntax for algebraic datatypes is considered experimental and is subject to +.. pull-quote:: Note + + The syntax for algebraic datatypes is considered experimental and is subject to change. However, they appear in the `standard QL libraries `_ so the following sections should help you understand those examples.