杂项
这些命令提供与文档视觉外观和文档生成过程有关的杂项功能。
\注释列表
注释列表（annotatedlist）命令可以展开一个组的成员列表，每个成员都有简短的文字说明。下面是 Qt 参考文档中的一个例子：
/*! ... \section1 Drag and Drop Classes These classes deal with drag and drop and the necessary mime type encoding and decoding. \annotatedlist draganddrop */
这会生成draganddrop组中所有 C++ 类和/或 QML 类型的列表。draganddrop组中的 C++ 类或 QML 类型的\class或\qmltype注释中将包含 \ingroup draganddrop。
根据用户可见的名称或标题，组内成员按升序排序。自 QDoc 6.8 起，annotatedlist 和 \generatelist也支持自定义排序。
另请参见 \generatelist和排序组成员。
\cmakepackage
使用 \cmakepackage 命令为类和命名空间添加 CMake 软件包信息。这些信息将出现在类或命名空间文档页面顶部的表格中。例如
/*!
\namespace Foo
\inheaderfile Bar
\cmakepackage Baz
\brief A namespace.
...
*/
QDoc 将输出为
Foo 命名空间
命名空间。更多
页眉： #include <Bar> (包含 <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> (包含 <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> (包含 <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> (包含 <Bar>) CMake： find_package(Qt6 REQUIRED COMPONENTS Baz)
\Qtcmaketargetitem
使用 \qtcmaketargetitem 命令覆盖 CMaketarget_link_libraries 信息中添加到类和命名空间的项目部分。该命令必须与\module和\qtcmakepackage} 命令结合使用。
另请参阅 \module和\qtcmakepackage} 命令。
\生成列表
\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
*/
这将生成所有类（All Classes）页面。该命令接受以下参数：
<group-name>
如果组名是唯一的参数，QDoc 会列出使用\ingroup <group-name> 命令的所有实体。
分组成员排序
生成群组成员列表时，会根据用户可见的名称或标题按升序排序。自 QDoc 6.8 起，可修改默认排序顺序：
\generatelist [descending] changelogs
假设更新日志组由详细说明不同版本中的更改的页面组成，则会以降序（最新版本在前）生成列表。
排序键
自 QDoc 6.8 起，可使用 \meta命令为一个或多个组成员指定自定义排序键：
\meta sortkey {sort key}
然后，排序（升序或降序）将根据这些键而不是用户可见的标题进行。
注意： 有排序键的组员会排在没有键的组员之前（默认升序）。这样可以将个别组员提升到列表顶部。
annotatedclasses
annotatedclasses 参数提供了一个包含所有类别名称和每个类别描述的表格。每个类名都是该类参考文档的链接。例如
使用\class命令记录一个 C++ 类。类的注释取自类注释的\brief命令的参数。
annotatedexamples
annotatedexamples 参数以表格的形式提供了所有示例的完整列表，其中包含所有示例的标题和每个示例的描述。每个标题都是指向示例文档的链接。
如果模块定义了 navigation.landingpage 配置变量，则会为每个模块（拥有文档示例）生成单独的表格。landingpage变量将用作每个表格前的标题。
annotatedattributions
annotatedattributions 参数提供了所有属性的完整列表，它是一组表格，包含所有属性的标题和每个属性的描述。每个标题都是指向归因页面的链接。
只要模块定义了 navigation.landingpage 配置变量，就会为每个模块（有归属）生成单独的表格。landingpage变量将用作每个表格前的标题。
classes <prefix>
classes 参数提供了一个按字母顺序排列的完整类列表。第二个参数<prefix> 是类名称的通用前缀。类名将根据公共前缀后面的字符排序，例如 Qt 类的公共前缀是Q 。公共前缀参数是可选的。如果没有提供公共前缀，类名将按其第一个字符排序。
每个类名都将成为指向该类参考文档的链接。该命令用于以这种方式生成 "所有类"（All Classes）页面：
/*!
\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
*/
使用\class命令记录一个 C++ 类。
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 值类型）。
注意： QDoc 5.6 引入了对该参数的支持。
qmlvaluetypesbymodule
与qmltypesbymodule 参数类似，但列出的是 QML 值类型。
注： QDoc 6.7 中引入了对该参数的支持。
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 命令和相应的 \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、定义和falsehoods。
\else
如果\if命令中的条件为假，则 \else 命令指定了一个替代条件。
\else 命令只能在 \if...\endif命令中使用，但在只有两个选择时非常有用。
\包含
include命令将其第一个参数指定的全部或部分文件发送到QDoc输入流中，作为QDoc注释片段处理。
当某些命令或文本片段要在文档中的多个地方使用时，该命令非常有用。使用 \include 命令可以在文档中插入片段。包含要包含的片段的文件必须位于sourcedirs或exampledirsQDoc 配置变量中列出的路径下。它可以是 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 filename snippet-identifier
为每一个要在文档中多处使用的 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 输入流。您甚至可以嵌套片段。
注意： 片段标识符在文档注释（/*! .. */）块中也同样有效，因此不必使用单独的.qdocinc 文件。处理注释块时，QDoc 会从生成的输出中删除任何//! 注释行。
额外参数
自 QDoc 6.3 起，传递给 \include 命令的任何其他参数都将用于将字符串注入到包含的内容中。要将字符串注入内容中的特定位置，请在反斜杠后添加一个数字（1...9）。数字与参数列表的顺序相对应。用大括号括起参数，以确保 QDoc 按照您的期望渲染整个参数，包括可能的空白字符。
重要： 每个附加参数（包括片段 ID）都必须用大括号括起来。如果要包含整个文件，请使用空的片段 ID：{}.
例如，给定文件includes.qdocinc 中的以下片段 ：
//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]
那么，下面的 \include 行：
\include includes.qdocinc {usage} {detailed output} {Verbose}
渲染
要启用详细输出，请选择Verbose >Enable 。
\参数
\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 会根据示例的标题和模块名称生成示例标签。这些标签会显示在Qt Creator 的欢迎模式中，帮助用户浏览示例列表。
可以使用\meta {tag} {tag1} 或\meta {tags} {tag1,[tag2,...]} 创建其他标签。例如
/*!
\example helloworld
\title Hello World Example
\meta {tags} {tutorial,basic}
*/
这将产生以下标记：tutorial,basic,hello,world。例子等常用词将被忽略。
排除示例
标记示例已损坏将从生成的清单文件中排除该示例，从而有效地将其从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}
*/
另请参阅状态相关命令。
\noautolist
\noautolist 命令表示应该省略 C++ 或 QML 模块页面底部自动生成的 C++ 类或 QML 类型的注释列表，因为这些类或类型已经手工列出。这条命令也可以与\group命令一起使用，以省略手动列出的组成员名单。
该命令必须独立成行。请参阅 Qt Quick Controls QML Types查看示例。该页面由qtquickcontrols2-qmlmodule.qdoc 生成。您可以在其中找到一条 QDoc 注释，其中包含用于QtQuick.Controls 模块的\qmlmodule 命令。该注释还包含一条\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 (avoid!)
\raw 命令和相应的 \endraw 命令为原始标记语言代码块定界。
该命令需要一个指定代码格式的参数。
QDoc 仅在生成用户指定的格式时才会生成给定的代码。
例如，"\raw HTML "只会在 QDoc 生成 HTML 文档时生成代码。
注意： 使用 QDoc 命令往往可以达到预期目的，同时减少出错或内容无法维护的机会。
\sincelist
sincelist命令会扩展到一个指定版本的文档化应用程序接口新包含内容的详细分类。使用示例
/*! \page newclasses69.html \title New Classes and Functions in 6.9 \brief A comprehensive list of new classes and functions in 6.9. \sincelist 6.9 */
\sincelist 接受一个参数，即版本字符串。生成的输出包括所有用\since命令或与版本字符串匹配的since 子句标记的功能。
\独码
使用 \unicode 命令可以在文档中插入任意 Unicode 字符。
该命令的参数是一个整数。默认情况下，除非指定 "0x "或 "0 "前缀（分别表示基数 16 和 8），否则将假定基数为 10。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
