查询帮助文件¶

查询帮助文件告诉用户查询的用途，并建议如何解决查询发现的潜在问题。

本主题提供了有关查询帮助文件结构的详细信息。有关如何以与标准 CodeQL 查询一致的风格编写有用的查询帮助的更多信息，请参阅 GitHub 上的查询帮助风格指南。

注意

您可以通过访问 CodeQL 查询帮助来访问 CodeQL 查询的查询帮助。您还可以访问 GitHub 存储库中的原始查询帮助文件。例如，请参阅 JavaScript/TypeScript 安全查询和 C/C++ 关键查询。

概述¶

每个查询帮助文件都提供有关查询的用途和用法的详细信息。在编写自己的查询时，我们建议您也编写查询帮助文件，以便其他用户了解查询的功能和工作原理。

结构¶

查询帮助文件使用自定义 XML 格式编写，并存储在扩展名为 .qhelp 的文件中。查询帮助文件必须与它们描述的查询具有相同的基名称，并且必须位于同一个目录中。基本结构如下

<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
<qhelp>
    CONTAINS one or more section-level elements
</qhelp>

标头和单个顶层 qhelp 元素都是必需的。以下部分将解释您可以在查询帮助文件中包含的其他元素。

代码扫描不会处理自定义 CodeQL 查询的 .qhelp 文件，因此要在代码扫描 UI 中显示自定义查询的查询帮助，您必须将 .qhelp 文件转换为 Markdown，然后将 Markdown 渲染的查询帮助包含在分析期间生成的 SARIF 文件中。有关更多信息，请参阅“使用 CodeQL CLI 分析数据库”。

节级元素¶

节级元素用于将帮助文件中的信息分组到节中。许多节都有标题，可以通过 title 属性或默认值来定义。以下节级元素是 qhelp 元素的可选子元素。

元素	属性	子元素	节的用途
`example`	无	任何块元素	演示违反查询实现的规则的代码示例，并提供有关如何修复它的指导。默认标题。
`fragment`	无	任何块元素	请参阅以下“查询帮助包含”。无标题。
`hr`	无	无	水平线。无标题。
`include`	`src` 要包含的查询帮助文件。	无	在该元素的位置包含一个查询帮助文件。请参阅以下“查询帮助包含”。无标题。
`overview`	无	任何块元素	查询目的的概述。通常这是查询文档中的第一个节。无标题。
`recommendation`	无	任何块元素	建议如何解决此查询标识的任何警报。默认标题。
`references`	无	`li` 元素	参考列表。通常这是查询文档中的最后一个节。默认标题。
`section`	`title` 节的标题	任何块元素	带有由 `title` 属性定义的标题的通用节。
`semmleNotes`	无	任何块元素	有关查询的实现说明。此节仅用于实现第三方定义的规则的查询。默认标题。

块元素¶

以下元素是 section、example、fragment、recommendation、overview 和 semmleNotes 元素的可选子元素。

元素	属性	子元素	块的用途
`blockquote`	无	任何块元素	显示带引号的段落。
`img`	`src` 要包含的图像文件。 `alt` 图像的替代文本。 `height` 可选，图像的高度。 `width` 可选，图像的宽度。	无	显示图像。图像的内容在单独的图像文件中。
`include`	`src` 要包含的查询帮助文件。	无	在该元素的位置包含一个查询帮助文件。请参阅以下查询帮助包含了解详细信息。
`ol`	无	`li`	显示有序列表。请参阅以下列表元素。
`p`	无	任何内联内容	显示段落，用作 HTML 文件中的段落。
`pre`	无	文本	以等宽字体显示文本，并使用预格式化的空白。
`sample`	`language` 内联代码示例的语言。 `src` 可选，包含示例代码的文件。	文本	显示示例代码，示例代码可以定义为 `sample` 元素中的嵌套文本，也可以定义为指定的 `src` 文件中。指定 `src` 时，将从文件扩展名推断语言。如果省略 `src`，则必须提供语言，并且示例代码应作为嵌套文本提供。
`table`	无	`tbody`	显示表格。请参阅以下表格。
`ul`	无	`li`	显示无序列表。请参阅以下列表元素。
`warning`	无	文本	显示一个警告，该警告将在结果页面上非常显眼地显示。此类警告有时用于已知在许多代码库中精度较低的查询；此类查询通常默认情况下处于禁用状态。

列表元素¶

查询帮助文件支持两种类型的用于列表的块元素：ul 和 ol。这两种块元素都只支持类型为 li 的一个子元素。每个 li 元素都包含内联内容或块元素。

表格元素¶

table 块元素用于在查询帮助文件中包含表格。每个表格都包含若干行，每行都包含若干个单元格。单元格中的数据将呈现为网格。

元素	属性	子元素	用途
`tbody`	无	`tr`	定义表格的顶层元素。
`tr`	无	`th` `td`	定义表格的一行。
`td`	无	任何内联内容	定义表格行的一个单元格。
`th`	无	任何内联内容	定义表格行的一个标题单元格。

内联内容¶

内联内容用于定义段落、列表项、表格单元格等元素的内容。内联内容包括文本以及以下定义的内联元素

元素	属性	子元素	用途
`a`	`href` 链接的 URL。	text	定义超链接。当用户选择子文本时，他们将被重定向到给定的 URL。
`b`	无	内联内容	定义应以粗体显示的内容。
`code`	无	内联内容	定义代表代码的内容。它通常显示在等宽字体中。
`em`	无	内联内容	定义应加重的内容，通常通过将其设置为斜体。
`i`	无	内联内容	定义应以斜体显示的内容。
`img`	`src` `alt` `height` `width`	无	显示图像。请参阅上面的块元素中的描述。
`strong`	无	内联内容	定义应以更强的样式呈现的内容，通常使用粗体。
`sub`	无	内联内容	定义应以下标形式呈现的内容。
`sup`	无	内联内容	定义应以上标形式呈现的内容。
`tt`	无	内联内容	定义应以等宽字体显示的内容。

查询帮助包含¶

要在不同的帮助主题之间重复使用内容，您可以将共享内容存储在一个查询帮助文件中，然后使用 include 元素将其包含在多个其他查询帮助文件中。共享内容可以存储在与包含文件相同的目录中，也可以存储在 SEMMLE_DIST/docs/include 中。当查询帮助文件仅被其他帮助文件包含，但不属于特定查询时，它应具有文件扩展名 .inc.qhelp。

include 元素可以用作节级或块级元素。由 src 属性定义的查询帮助文件的内容必须包含适合 include 元素位置的元素。

节级 include 元素¶

节级 include 元素可以位于顶层 qhelp 元素下方。例如，在 StoredXSS.qhelp 中，一个完整的查询帮助文件被重复使用

<qhelp>
    <include src="XSS.qhelp" />
</qhelp>

在此示例中，XSS.qhelp 文件必须符合上面描述的完整查询帮助文件的标准。也就是说，qhelp 元素只能包含非 fragment 的节级元素。

块级 include 元素¶

块级 include 元素可以包含在节级元素之下。例如，include 元素在 ThreadUnsafeICryptoTransform.qhelp 中的 overview 部分下使用。

<qhelp>
    <overview>
        <include src="ThreadUnsafeICryptoTransformOverview.inc.qhelp" />
    </overview>
    ...
</qhelp>

包含的文件，ThreadUnsafeICryptoTransformOverview.inc.qhelp，可能只包含一个或多个 fragment 部分。例如

<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
<qhelp>
   <fragment>
      <p>
         ...
      </p>
   </fragment>
</qhelp>