Query help reference ******************** This topic provides detailed information on the structure of query help files. For more information about how to write useful query help in a style that is consistent with Semmle's built-in queries, see the `Query help style guide `__ on GitHub. .. pull-quote:: Note You can access the query help for Semmle's built-in queries by visiting the `Built-in query pages `__. You can also access the raw query help files in the `Semmle/ql GitHub repository `__. For example, the `JavaScript security queries `__ and `C/C++ critical queries `__. For queries run by default on LGTM, there are several different ways to access the query help. For further information, see `Where do I see the query help for a query on LGTM? `__ in the LGTM user help. Overview ======== Each query help file provides detailed information about the purpose and use of a query. When you write your own queries, we recommend that you also write query help files so that other users know what the queries do, and how they work. Structure ========= Query help files are written using an XML format called Qhelp (``.qhelp``). Query help files must have the same base name as the query they describe, and must be located in the same directory. The basic structure is as follows: .. code-block:: xml CONTAINS one or more section-level elements The header and single top-level ``qhelp`` element are both mandatory. The following sections explain additional elements that you may include in your query help files. Section-level elements ====================== Section-level elements are used to group the information in the help file into sections. Many sections have a heading, either defined by a ``title`` attribute or a default value. The following section-level elements are optional child elements of the ``qhelp`` element. +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | Element | Attributes | Children | Purpose of section | +====================+====================================+========================+===============================================================================================================================================+ | ``example`` | None | Any block element | Demonstrate an example of code that violates the rule implemented by the query with guidance on how to fix it. Default heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``fragment`` | None | Any block element | See :ref:`Qhelp inclusion ` below. No heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``hr`` | None | None | A horizontal rule. No heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``include`` | ``src`` The Qhelp file to include. | None | Include a Qhelp file at the location of this element. See :ref:`Qhelp inclusion ` below. No heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``overview`` | None | Any block element | Overview of the purpose of the query. Typically this is the first section in a query document. No heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``recommendation`` | None | Any block element | Recommend how to address any alerts that this query identifies. Default heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``references`` | None | ``li`` elements | Reference list. Typically this is the last section in a query document. Default heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``section`` | ``title`` Title of the section | Any block element | General-purpose section with a heading defined by the ``title`` attribute. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``semmleNotes`` | None | Any block element | Semmle-specific notes about the query. This section is used only for queries that implement a rule defined by a third party. Default heading. | +--------------------+------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ Block elements ============== The following elements are optional child elements of the ``section``, ``example``, ``fragment``, ``recommendation``, ``overview`` and ``semmleNotes`` elements. .. table:: :widths: 7 20 10 25 +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Element | Attributes | Children | Purpose of block | +================+==========================================================+====================+===========================================================================================================================================================================================================================================================================================================+ | ``blockquote`` | None | Any block element | Display a quoted paragraph. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``img`` | | ``src`` The image file to include. | None | Display an image. The content of the image is in a separate image file. | | | | ``alt`` Text for the image's alt text. | | | | | | ``height`` Optional, height of the image. | | | | | | ``width`` Optional, the width of the image. | | | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``include`` | ``src`` The Qhelp file to include. | None | Include a Qhelp file at the location of this element. See :ref:`Qhelp inclusion ` below for more information. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``ol`` | None | ``li`` | Display an ordered list. See List elements below. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``p`` | None | Any inline content | Display a paragraph, used as in HTML files. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``pre`` | None | Text | Display text in a monospaced font with preformatted whitespace. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``sample`` | | ``language`` The language of the in-line code sample. | Text | Display sample code either defined as nested text in the ``sample`` element or defined in the ``src`` file specified. When ``src`` is specified, the language is inferred from the file extension. If ``src`` is omitted, then language must be provided and the sample code provided as nested text. | | | | ``src`` Optional, the file containing the sample code. | | | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``table`` | None | ``tbody`` | Display a table. See Tables below. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``ul`` | None | ``li`` | Display an unordered list. See List elements below. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``warning`` | None | Text | Display a warning that will be displayed very visibly on the resulting page. Such warnings are sometimes used on queries that are known to have low precision for many code bases; such queries are often disabled by default. | +----------------+----------------------------------------------------------+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ List elements ============= Qhelp files support two types of block elements for lists: ``ul`` and ``ol``. Both block elements support only one child elements of the type ``li``. Each ``li`` element contains either inline content or a block element. Table elements ============== The ``table`` block element is used to include a table in a Qhelp file. Each table includes a number of rows, each of which includes a number of cells. The data in the cells will be rendered as a grid. +-----------+------------+--------------------+-------------------------------------------+ | Element | Attributes | Children | Purpose | +===========+============+====================+===========================================+ | ``tbody`` | None | ``tr`` | Defines the top-level element of a table. | +-----------+------------+--------------------+-------------------------------------------+ | ``tr`` | None | | ``th`` | Defines one row of a table. | | | | | ``td`` | | +-----------+------------+--------------------+-------------------------------------------+ | ``td`` | None | Any inline content | Defines one cell of a table row. | +-----------+------------+--------------------+-------------------------------------------+ | ``th`` | None | Any inline content | Defines one header cell of a table row. | +-----------+------------+--------------------+-------------------------------------------+ Inline content ============== Inline content is used to define the content for paragraphs, list items, table cells, and similar elements. Inline content includes text in addition to the inline elements defined below: +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | Element | Attributes | Children | Purpose | +============+======================================+================+==================================================================================================+ | ``a`` | ``href`` The URL of the link. | text | Defines hyperlink. When a user selects the child text, they will be redirected to the given URL. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``b`` | None | Inline content | Defines content that should be displayed as bold face. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``code`` | None | Inline content | Defines content representing code. It is typically shown in a monospace font. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``em`` | None | Inline content | Defines content that should be emphasized, typically by italicizing it. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``i`` | None | Inline content | Defines content that should be displayed as italics. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``img`` | | ``src``  | None | Display an image. See the description above in Block elements. | | | | ``alt`` | | | | | | ``height`` | | | | | | ``width`` | | | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``strong`` | None | Inline content | Defines content that should be rendered more strongly, typically using bold face. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``sub`` | None | Inline content | Defines content that should be rendered as subscript. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``sup`` | None | Inline content | Defines content that should be rendered as superscript. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ | ``tt`` | None | Inline content | Defines content that should be displayed with a monospace font. | +------------+--------------------------------------+----------------+--------------------------------------------------------------------------------------------------+ .. _qhelp-inclusion: Qhelp inclusion =============== To enable the reuse of content between different help topics, shared content can be stored in one Qhelp file and then included in a number of other Qhelp files using the ``include`` element. The shared content can stored either in the same directory as the including files, or in ``SEMMLE_DIST/docs/include``. The ``include`` element can be used as a section or block element, the content of the Qhelp file defined by the ``src`` attribute must contain elements that are appropriate to the location of the ``include`` element. Section-level include elements ------------------------------ Section-level ``include`` elements can be located beneath the top-level ``qhelp`` element. For example, in `StoredXSS.qhelp `__, a full query help file is reused: .. code-block:: xml In this example, the `XSS.qhelp `__ file must conform to the standard for a full Qhelp file as described above. That is, the ``qhelp`` element may only contain non-``fragment``, section-level elements. Block-level include elements ---------------------------- Block-level ``include`` elements can be included beneath section-level elements. For example, an ``include`` element is used beneath the ``overview`` section in `ThreadUnsafeICryptoTransform.qhelp `__: .. code-block:: xml ... The included file, `ThreadUnsafeICryptoTransformOverview.qhelp `_, may only contain one or more ``fragment`` sections. For example: .. code-block:: xml

...

Further information =================== - To learn more about contributing to the standard QL queries and libraries, see our `Contributing guidelines `__ on GitHub. - To learn more about writing custom queries, and how to format your QL for clarity and consistency, see `Writing QL queries `__.