这些命令提供了与文档外观以及文档生成过程相关的各种功能。

\annotatedlist

\annotatedlist 命令会展开为一个组的成员列表，每个成员都会附带其简短说明。以下是来自《Qt参考文档》的一个示例：

/*!
   ...
   \section1 Drag and Drop Classes

   These classes deal with drag and drop and the necessary mime type
   encoding and decoding.

   \annotatedlist draganddrop
*/

\ingroup 这将生成 draganddrop组中所有 C++ 类和/或 QML 类型的列表。 draganddrop组中的 C++ 类或 QML 类型，其 \class 或 \qmltype 注释中包含xml-ph-0000@deepl.internaldraganddrop。

组成员将根据用户可见的名称或标题按升序排列。自 QDoc 6.8 起，\annotatedlist 还 \generatelist 也支持自定义排序。

另请参阅 \generatelist 以及“排序组成员”。

\cmakepackage

使用\cmakepackage 命令向类和命名空间添加CMake包信息。该信息随后将显示在类或命名空间文档页顶部的表格中。例如：

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc 将输出如下内容：

Foo 命名空间

一个命名空间。更多...

头文件：	#include <Bar>
CMake：	find_package(Baz REQUIRED) target_link_libraries(mytarget PRIVATE Baz::Baz)

另请参阅\module 以及 \cmakecomponent}

\cmakecomponent

使用\cmakecomponent 命令向类和命名空间添加CMake组件信息。该信息随后将显示在类或命名空间文档页面顶部的表格中。例如：

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDoc 将输出如下内容：

Foo 命名空间

一个命名空间。更多...

头文件：	#include <Bar>
CMake：	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::Baz)

另请参阅\module 以及 \cmakepackage}

\cmaketargetitem

使用\cmaketargetitem 命令来覆盖添加到类和命名空间中的CMaketarget_link_libraries 信息中的项部分。该命令必须与 \module 和 \cmakecomponent 命令配合使用。例如：

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \cmaketargetitem Qt6::BazPrivate
    \brief A namespace.

    ...
*/

QDoc 将输出如下内容：

Foo 命名空间

一个命名空间。更多...

头文件：	#include <Bar>
CMake：	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)

另请参阅\module 以及 \cmakecomponent}

\qtcmakepackage

使用\qtcmakepackage 命令向类和命名空间添加CMake包信息。这些信息随后将显示在类或命名空间文档页面顶部的表格中。例如：

/*!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc 将将其输出为

Foo 命名空间

一个命名空间。更多...

头文件：	#include <Bar>
CMake：	find_package(Qt6 REQUIRED COMPONENTS Baz)

\qtcmaketargetitem

使用\qtcmaketargetitem 命令来覆盖添加到类和命名空间中的CMaketarget_link_libraries 信息中的item部分。该命令必须与 \module 和 \qtcmakepackage 命令配合使用。

另请参阅\module 和 \qtcmakepackage}

\generatelist

\generatelist 命令会展开为一组链接，这些链接指向由 \ingroup 命令分组，或是匹配下列任一参数的实体。以下是来自 Qt 参考文档的一个示例：

/*!
   \page classes.html
   \title All Classes

   For a shorter list that only includes the most
   frequently used classes, see \l{Qt's Main Classes}.

   \generatelist classes Q
*/

这将生成“所有类”页面。该命令支持以下参数：

<group-name>

若仅提供一个组名作为参数，QDoc 将列出所有使用 `\ingroup <group-name> ` 命令的实体。

对组成员进行排序

生成组成员列表时，这些成员会根据用户可见的名称或标题按升序排序。自 QDoc 6.8 起，可以修改默认的排序顺序：

\generatelist [descending] changelogs

假设“变更日志”组由详细记录不同版本变更的页面组成，则生成的列表将按降序排列（最新版本排在最前面）。

排序键

自 QDoc 6.8 起，可通过 \meta 命令：

\meta sortkey {sort key}

随后，排序（升序或降序）将基于这些键（而非用户可见的标题）进行。

annotatedclasses

annotatedclasses 参数提供了一个包含所有类名称及其描述的表格。每个类名都是指向该类参考文档的链接。例如：

C++ 类的文档由 \class 命令进行注释。该类的注释内容取自类注释的 \brief 命令的参数中提取。

annotatedexamples

annotatedexamples 参数提供了一个完整的示例列表，该列表以表格集的形式呈现，包含所有示例的标题以及每个示例的描述。每个标题都是指向该示例文档的链接。

对于每个（具有文档化示例的）模块，系统都会生成一个独立的表格，前提是该模块已定义了 navigation.landingpage 配置变量。landingpage变量将用作每个表格前面的标题。

annotatedattributions

annotatedattributions 参数会以一组表格的形式提供所有归属信息的完整列表，其中包含所有归属信息的标题以及每条归属信息的描述。每个标题都是指向该归属信息页面的链接。

只要模块定义了 `navigation.landingpage` 配置变量，系统就会为每个（带有归属信息的）模块生成一个独立的表格。`landingpage` 变量将用作每个表格前面的标题。

classes <prefix>

classes 参数提供按字母顺序排列的完整类列表。 第二个参数<prefix> 是类名的公共前缀。类名将根据公共前缀之后的字符进行排序。例如，Qt 类的公共前缀是Q 。公共前缀参数是可选的。如果未提供公共前缀，类名将按其首字符进行排序。

每个类名都会变成指向该类参考文档的链接。该命令用于按以下方式生成“所有类”页面：

/*!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
*/

C++ 类的文档通过 \class 命令来编写。

classesbymodule

使用此参数时，必须提供第二个参数，用于指定要列出其类的模块。QDoc 会生成一个包含这些类的表格。每个类都会以其 \brief 命令的文本。

例如，可以在模块页面上如下使用此命令：

/*!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

    ...
*/

指定模块中的每个类都必须在其 \inmodule\class 命令。

qmltypesbymodule

与classesbymodule 参数类似，但用于列出由第二个参数指定的QML模块中的QML类型（不包括QML值类型）。

qmlvaluetypesbymodule

与qmltypesbymodule 参数类似，但列出的则是QML值类型。

functionindex

functionindex 参数提供所有已文档化的成员函数的完整按字母顺序排列的列表。它通常仅用于生成Qt 函数索引页，方法如下：

/*!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
*/

legalese

legalese 参数会指示 QDoc 生成当前文档项目中的许可列表。每个许可都通过 \legalese 命令进行标识。

overviews

overviews 参数用于指示 QDoc 通过将所有 \group 页面的内容进行拼接，从而生成该列表。Qt 通过以下方式利用此功能生成“概述”页面：

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

attributions 参数用于指示QDoc在文档中生成一份致谢列表。

related

related 参数需与 \group 和 \ingroup 命令配合使用，以列出与指定组相关的所有概述。例如，“使用 Qt 编程”页面的文档就是通过这种方式生成的：

/*!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
*/

该组页面中列出的每个页面都包含以下命令：

\ingroup qt-basic-concepts

另请参阅 \annotatedlist。

\if

\if 命令及其对应的\endif 命令用于包裹QDoc注释中的部分内容，只有当命令参数指定的条件为真时，这些内容才会被包含。

该命令会读取该行的其余部分，并将其解析为 C++ #if 语句。

/*!
   \if defined(opensourceedition)

   \note This edition is for the development of
   \l{Qt Open Source Edition} {Free and Open Source}
   software only; see \l{Qt Commercial Editions}.

   \endif
*/

只有当预处理器符号 `opensourceedition ` 被定义，并且在配置文件的 `defines` 变量中指定了该符号（以使 QDoc 处理 `#ifdef` 和 `#endif` 之间的代码）时，该 QDoc 注释才会被渲染：

defines = opensourceedition

您也可以在命令行上手动定义该预处理器符号。有关更多信息，请参阅defines变量的文档。

另请参阅 \endif, \else、defines以及falsehoods。

\endif

\endif 命令及其对应的\if 命令会将QDoc注释中的部分内容包裹起来，如果 \if 命令的参数所指定的条件为真时，将包含该部分内容。

有关详细信息，请参阅 \if 的文档。

另请参阅 \if， \else、定义以及虚假陈述。

\else

\else 命令用于指定当 \if 命令中的条件为假时，指定一个替代方案。

\else 命令只能在\if ……\endif等命令中使用，但在只有两个备选方案时非常有用。

\include

\include 命令会将其第一个参数指定的文件全部或部分内容发送至QDoc输入流，以便作为QDoc注释片段进行处理。

当某些命令或文本片段需要在文档中的多处使用时，此命令非常有用。在您希望将片段插入文档的任何位置，均可使用\include 命令。包含待插入片段的文件必须位于 QDoc 配置变量sourcedirs或exampledirs中列出的路径下。 该文件可以是任何可被 QDoc 解析的源文件（甚至可以是使用 `\include ` 命令的同一文件），也可以是任何其他文本文件。若要将片段存储在单独的、不打算由 QDoc 解析的文件中，请使用未在 `sources.fileextensions` 中列出的文件扩展名；例如，.qdocinc 。

该命令可带一个或多个参数。第一个参数始终是文件名。文件内容必须是 QDoc 输入，即一串 QDoc 命令和文本，但不得包含 QDoc 注释的包围符/*! ...*/ 。若要包含指定文件的全部内容，请将第二个参数留空。 若仅需包含文件的一部分，请参阅下文中的双参数形式。以下是一个单参数形式的示例：

/*!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
*/

\include 文件名 片段标识符

对于那些希望在文档中多处使用的 QDoc 包含片段，为每个片段单独创建一个.qdocinc 文件是浪费时间，尤其是考虑到你可能还得在每个文件中都加入版权/许可声明。 如果你有多个需要包含的代码片段，可以将它们全部放在一个文件中，并用以下代码块包裹每个片段：

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

然后，你可以使用该命令的双参数形式：

\include examples/signalandslots.qdocinc snippet-id2
\include examples/objectmodel.qdocinc another-snippet-id

位于与第二个参数同名的两个标签之间的 QDoc 命令序列和文本将被发送到 QDoc 输入流。你甚至可以使用嵌套的代码片段。

额外参数

自 QDoc 6.3 起，传递给\include 命令的任何其他参数都将用于将字符串插入到包含的内容中。若要将字符串插入到内容中的特定位置，请在参数后添加反斜杠，后跟一个数字（1..9）。这些数字对应于参数列表的顺序。 请将参数用大括号括起来，以确保 QDoc 能按您的预期渲染整个参数，包括其中的空白字符。

例如，假设文件includes.qdocinc 中包含以下代码片段：

//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]

那么，以下\include 行：

\include includes.qdocinc {usage} {detailed output} {Verbose}

渲染

若要启用详细输出，请选择“Verbose ”>“Enable ”。

\meta

\meta 命令用于向文档中添加元数据。该命令有两个参数：第一个参数是元数据属性的名称，第二个参数是该属性的值。每个参数都应用大括号括起来，如下例所示：

/*!
    \example demos/coffee
    \title Coffee Machine
    \brief A Qt Quick application with a state-based custom user interface.

    \meta {tags} {quick,embedded,states,touch}
    \meta {category} {Application Examples}
*/

许多元数据属性都有特定的用途：

元数据示例

\meta 命令的另一个用途是在 \example 文档中。默认情况下，QDoc 会根据示例的 \title 和模块名称生成示例标签。这些标签会在Qt Creator 的“欢迎”模式中显示，帮助用户浏览示例列表。

可以通过\meta {tag} {tag1} 或\meta {tags} {tag1,[tag2,...]} 创建额外的标签。例如：

/*!
    \example helloworld
    \title Hello World Example
    \meta {tags} {tutorial,basic}
*/

这将生成以下标签：tutorial、basic、hello、world。诸如example之类的常用词将被忽略。

排除示例

将某个示例标记为“故障”将使其从生成的清单文件中排除，从而将其从Qt Creator 的“欢迎”模式中移除。

\meta {tag} {broken}

示例安装路径

\meta 命令结合参数installpath 可指定已安装示例的位置。该值将覆盖通过examplesinstallpath 配置变量设置的值。

/*!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
*/

另请参阅examplesinstallpath。

状态

\meta 命令的status 参数可为 \class 或 \qmltype。该描述随后将显示在类型参考页面顶部的表格中。

/*!
    \class QNativeInterface::QAndroidApplication
    \meta {status} {Android-specific}
*/

另请参阅与状态相关的命令。

文档元数据

\meta 命令的keywords 参数可将指定的关键词作为元数据添加到生成的文档中：

\meta {keywords} {reference, internal}

在HTML输出中，这些关键词将作为<meta name="keywords" content="..."> 元素生成。

\noautolist

\noautolist 命令表示应省略 C++ 或 QML 类或 QML 类型的注释列表（该列表通常会自动生成在 C++ 或 QML 模块页面的底部），因为这些类或类型已手动列出。该命令还可与 \group 命令配合使用，以省略已手动列出的组成员列表。

该命令必须单独成行。请参阅 Qt Quick Controls QML Types 中的示例。该页面由qtquickcontrols2-qmlmodule.qdoc 生成。在那里，您会发现一个包含\qmlmodule 命令的QDoc注释，该命令针对QtQuick.Controls模块。同一个注释中还包含一个\noautolist 命令，用于禁用自动列表生成，以及一个 \generatelist 用于在文档的特定章节中列出 QML 类型的指令。

该命令在 QDoc 5.6 中引入。

自 Qt 5.10 起，该命令也可应用于 \example 文档，此时会省略属于示例项目的自动生成的文件和图片列表。

\omit

\omit 命令及其对应的\endomit 命令用于划定您希望QDoc跳过的文档部分。例如：

/*!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
*/

\raw (请避免！)

\raw 命令及其对应的\endraw 命令用于限定一段原始标记语言代码。

该命令接受一个参数，用于指定代码的格式。

QDoc 仅在生成用户指定的格式时，才会生成该代码。

例如，“\raw HTML”仅在 QDoc 生成 HTML 文档时才会生成代码。

\sincelist

\sincelist 命令会展开为对指定版本中已文档化 API 新增内容的详细分解。使用示例：

/*!
   \page newclasses612.html
   \title New Classes and Functions in 6.12
   \brief A comprehensive list of new classes and functions in 6.12.

   \sincelist 6.12
*/

\sincelist该命令接受一个参数，即版本字符串。生成的输出包含所有标记了 \since 或与该版本字符串匹配的since 子句标记的所有功能。

\unicode

\unicode 命令允许您在文档中插入任意Unicode字符。

该命令接受一个以整数形式指定字符的参数。默认情况下，该整数采用十进制，除非指定了“0x”或“0”前缀（分别表示十六进制和八进制）。