通用配置变量

使用 QDoc 通用配置变量，您可以定义 QDoc 在何处找到生成文档所需的各种源文件，以及生成文档的存放目录。您还可以对 QDoc 本身进行一些小操作，控制其输出和处理行为。

代码缩进

codeindent 变量用于指定 QDoc 在编写代码片段时使用的缩进级别。

QDoc 最初使用的代码缩进硬编码值是 4 个空格，以确保代码片段可以很容易地与周围的文本区分开来。由于我们可以使用样式表来调整某些类型的 HTML 元素的外观，因此并不总是需要这种缩进级别。

代码语言

codelanguages 变量指定了一个 QDoc 无法识别的源代码语言列表，这些语言可在\code...\endcode 代码块中使用。这样就可以用 QDoc 无法解析的语言编写代码块，并生成可被其他工具高亮或处理的 HTML。

codelanguages = Python Rust Java Swift "C#"

由于 QDoc 可以处理 C++ (Cpp)、QML 和文本，因此无需在此列表中指定这些语言。包含特殊字符（如 C#）的语言名称在包含在此列表中时需要用双引号引出。

codelanguages 变量是在 QDoc 6.11 中引入的，目的是让在线 Qt 文档能对highlight.js 支持的语言子集使用语法高亮显示。

另请参见 \code.

代码前缀, 代码后缀

codeprefix 和codesuffix 变量指定了每个代码片段所包含的一对字符串。

定义

defines 变量指定 QDoc 将识别和响应的 C++ 预处理器符号。

当使用defines 变量指定预处理器符号时，您还可以使用 \if命令来封装只有在定义了预处理器符号时才会包含的文档。

defines = QT_GUI_LIB

这样可以确保 QDoc 处理需要定义这些符号的代码。例如

#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endif

您也可以使用 -D 选项在命令行上手动定义预处理器符号。例如

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

在本例中，-D 选项确保在 QDoc 处理 qtgui.qdocconf 文件中定义的源文件时，定义qtforpython 预处理器符号。

另请参阅falsehoods和 \if.

取决于

depends 变量定义了该项目依赖的其他文档项目的列表，用于解析类型继承的链接目标和文档需要链接的其他内容。

与 Qt 本身一样，Qt 文档也分布在多个模块中。在多模块文档项目中，单个模块的最小依赖关系集包括实际的构建依赖关系。此外，如果有一个文档项目（模块）作为整个文档集的顶级入口点并提供导航链接，则每个模块文档都应将其作为依赖项。

QDoc 在为项目生成文档时，还会生成一个.index 文件，其中包含指向项目中每个可链接实体的 URL。每个依赖项都是一个项目的名称（小写）。该名称必须与为该项目生成的索引文件的基本名称一致。

depends = \
    qtdoc \
    qtcore \
    qtquick

在有依赖项并使用depends 变量的项目上调用 QDoc 时，必须将一个或多个-indexdir 路径作为命令行选项传入。QDoc 会使用这些路径搜索依赖项的索引文件。

qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS

在上述情况下，QDoc 将搜索依赖项的文件$QT_INSTALL_DOCS/qtdoc/qtdoc.index 至qtdoc 。如果未找到依赖项的索引文件，QDoc 将输出警告。

depends 命令还接受一个特殊值 "*"。这将指示 QDoc 加载在指定索引目录中找到的所有索引文件；也就是说，"依赖于一切"。

depends = *

另请参阅索引、项目和url。

文件头

设置documentationinheaders = true 可指示 QDoc 在为基于 C++ 的项目生成文档时解析头文件中的文档注释。

QDoc 在 Qt 6.9 中引入了此功能。

示例

exampledirs 变量指定了包含示例文件源代码的目录。

examples和exampledirs变量由 \quotefromfile, \quotefile和 \example命令使用。如果examples和exampledirs变量都已定义，QDoc 将同时在这两个变量中搜索，先搜索examples，然后再搜索exampledirs。

QDoc 将按指定顺序搜索目录，并接受找到的第一个匹配文件。它只会在指定的目录中搜索，而不会在子目录中搜索。

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

处理时

\quotefromfile widgets/calculator/calculator.cpp

QDoc 将查看是否有一个名为calculator.cpp 的文件被列为变量的值。 examples变量的值。如果没有，它将搜索exampledirs 变量，首先查看是否存在名为

$QTDIR/doc/src/widgets/calculator/calculator.cpp

的文件，如果没有，QDoc 将继续查找名为

$QTDIR/examples/widgets/calculator/calculator.cpp

的文件，以此类推。

另请参阅示例。

例子

examples 变量允许您指定单个示例文件，而不是由 exampledirs变量指定的目录中的文件外，还可以指定单个示例文件。

examples 和 exampledirs变量被 \quotefromfile, \quotefile和 \example命令使用。如果同时定义了examples 和 exampledirs变量，QDoc 将在这两个变量中进行搜索，首先在examples 中，然后在 exampledirs.

QDoc 将按照指定顺序搜索examples 变量列出的值，并接受找到的第一个值。

有关详细示例，请参阅 exampledirs命令。但请注意，如果您知道文件列在examples 变量中，就不必指定其路径：

\quotefromfile calculator.cpp

另请参阅exampledirs。

示例安装路径

examplesinstallpath 变量用于设置已安装示例目录下本项目示例的根路径。

假设所有示例的根安装路径都是QT_INSTALL_EXAMPLES ，那么路径

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

将用于指代本文档项目中单个示例的路径。这些路径记录在示例清单文件中，由Qt Creator 读取。

为确保路径正确，examplesinstallpath 必须与exampledirs 中列出的目录之一相匹配。每个 \example命令作为参数传递的路径与exampledirs 中的路径相对。

例如

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

并给出以下\example 命令：

/*!
    \example basic/hello
    ...
*/

然后，路径mymodule/basic/hello 就会记录在本例的清单文件中。

另请参阅：exampledirs、 \example和 \meta.

文件扩展名

examples.fileextensions 变量用于指定 QDoc 在收集示例文件以便在文档中显示时要查找的文件扩展名。

默认扩展名为 *.cpp、*.h、*.js、*.xq、*.svg、*.xml 和 *.ui。

扩展名以标准通配符表达方式给出。您可以使用 "+="将文件扩展名添加到过滤器中。例如

examples.fileextensions += *.qrc

另请参阅headers.file-extensions。

examples.warnaboutmissingimages

在处理示例文档时，如果示例不包含任何图片，QDoc 可能会发出警告。可以通过在项目的 .qdocconf 文件中设置以下配置变量来禁用此警告：

examples.warnaboutmissingimages = false

该配置变量在 Qt 6.9 中引入 QDoc。

另请参阅examples.warnaboutmissingprojectfiles。

examples.warnaboutmissingprojectfiles

在处理示例文档时，如果示例不包含项目文件，QDoc 可能会发出警告。可以通过在项目的 .qdocconf 文件中设置以下配置变量来禁用此警告：

examples.warnaboutmissingprojectfiles = false

该配置变量在 Qt 6.9 中引入 QDoc。

另请参阅examples.warnaboutmissingimages。

excludedirs

excludedirs 变量用于列出 QDoc不应处理的目录，即使sourcedirs或headerdirs变量包含了相同的目录。

例如

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

执行时，QDoc 将不再考虑列出的目录。QDoc 将不会读取这些目录中的文件。

另请参阅excludefiles。

排除文件

excludefiles 变量允许您指定 QDoc不应处理的单个文件。

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

如果在 qtbase 的 qdocconf 文件中包含上述内容，则不会为QWidget 生成类文档。

自 Qt 5.6 起，excludefiles 也能识别简单的通配符（'*'和'?例如，若要排除所有私有 Qt 头文件的解析，请定义如下内容：

excludefiles += "*_p.h"

另请参阅excludedirs。

额外图像

extraimages 变量用于告诉 QDoc 在生成的文档中加入特定图像。

QDoc 会自动将图像文件从imagedirs复制到输出目录，如果该文件被 \image或 \inlineimage命令引用的图像文件，QDoc 会自动将该图像文件从 imagedirs 复制到输出目录。如果要复制其他图像，必须使用extraimages 变量来指定。

一般语法为 format.extraimages = image.

例如

HTML.extraimages = images/qt-logo.png

另请参阅图像和imagedirs。

谬误

falsehoods 变量将指定预处理器符号的真值定义为 false。

该变量的值是正则表达式（详见QRegularExpression ）。如果没有为预处理符号设置该变量，QDoc 将假定其真值为真。0 "是个例外，它总是假的。

QDoc 可以识别并评估以下预处理器语法：

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

然而，面对未知的语法，如

#if NOTYET
    ...
#endif

这样的未知语法时，除非在 falsehoods 变量条目中指定了预处理器符号，否则QDoc 默认会将其评估为 true：

falsehoods = NOTYET

另请参阅定义。

生成索引

generateindex 变量包含一个布尔值，用于指定在生成 HTML 文档时是否生成索引文件。

默认情况下，HTML 文档总是生成索引文件，因此该变量通常只在禁用该功能（将值设为false ）或启用 WebXML 输出索引生成功能（将值设为true ）时使用。

头文件

headerdirs 变量用于指定包含与文档中使用的.cpp 源文件相关的头文件的目录。

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

执行时，QDoc 将首先读取 headers变量中指定的头文件，以及headerdir 变量中指定的目录（包括所有子目录）中的头文件，构建类及其函数的内部结构。

然后，它将读取在 sources变量中指定的源代码（包括所有子目录）。 sourcedirs变量（包括所有子目录）中指定的源代码，将文档与从头文件中获取的结构合并。

如果同时定义了headers 和headerdirs 变量，QDoc 将同时读取这两个变量，先读取 headers然后是headerdirs 。

在指定的目录中，QDoc 将只读取fileextensions 变量中指定的文件。 headers.fileextensions变量指定的文件。所指定的文件。 headers指定的文件，而不考虑它们的文件扩展名。

另请参阅headers和headers.fileextensions。

文件头

headers 变量允许你指定单个头文件，而不是那些位于由 headerdirs变量指定的目录中的文件外，还可以指定单个头文件。

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

处理headers 变量时，QDoc 的行为与处理 headerdirs变量时的行为相同。有关详细信息，请参阅 headerdirs变量。

另请参阅headerdirs。

头文件扩展名

headers.fileextensions 变量指定头文件使用的扩展名。

在处理 headerdirs变量中指定的头文件时，QDoc 将只读取headers.fileextensions 变量中指定文件扩展名的文件。这样，QDoc 就可以避免花费时间读取无关文件。

默认扩展名为 *.ch、*.h、*.h++、*.hh、*.hpp 和 *.hxx。

扩展名以标准通配符表达方式给出。您可以使用 "+="将文件扩展名添加到过滤器中。例如

header.fileextensions += *.H

另请参阅headerdirs。

includepaths

includepaths 变量用于向 Clang 解析器传递额外的 include 路径，QDoc 使用该解析器解析 C++ 代码以获取文档注释。

该变量接受一系列路径，前缀为-I （包含路径）、-F （macOS 框架包含路径）或-isystem （系统包含路径）。如果省略前缀，则默认使用-I 。

与当前 .qdocconf 文件相对的路径会被解析为绝对路径。文件系统中不存在的路径将被忽略。

另请参阅moduleheader。

includeprivate

使用includeprivate 在文档中包含私有的 C++ 类成员。QDoc 通常会将私有函数、类型和变量排除在生成的文档之外。

要包含所有私有成员，请将includeprivate 设置为true ：

includeprivate = true

您还可以启用特定的成员类型：

# Include only private functions
includeprivate.functions = true

# Include only private types (classes, enums, typedefs)
includeprivate.types = true

# Include only private variables
includeprivate.variables = true

特定设置会覆盖全局设置。例如

includeprivate = true
includeprivate.types = false

此配置包括私有函数和变量，但不包括私有类型。

QDoc 在 Qt 6.11 中引入了includeprivate 。

内部文件格式

internalfilepatterns 变量指定了标识内部实现文件的文件路径模式。在符合这些模式的文件中声明的类及其所有成员（属性、函数、枚举、嵌套类型）都会自动标记为内部类。文件作用域中的自由函数、枚举和类型定义不受此设置的影响。

当 showinternal 为false （默认值）时，这些实体将被排除在文档验证之外。当showinternal 为true 时，这些实体将包含在文档中，但保留其内部状态，允许生成器以不同方式对其进行样式化（例如为内部 API 添加可视化指示符）。

这对于包含不属于已文档化公共接口的类的私有实现头非常有用。在 Qt XML 中，这包括以_p.h 结尾的私有头文件。

模式语法

模式支持两种语法：

• Shell 样式的 glob 模式：简单的通配符，其中* 可匹配任何字符，? 可精确匹配一个字符。全局模式只与文件名匹配，不与完整路径匹配，因此非常适合*_p.h 等模式。
• 正则表达式：对于基于路径的匹配，使用 regex 语法。任何包含 regex 元字符 (^$[]{}()|+\\.) 的模式都会被视为正则表达式，并与完整的规范化文件路径相匹配。

模式匹配时使用正斜线 (/) 作为目录分隔符。QDoc 在内部对路径分隔符进行了规范化处理，因此无论平台如何，在模式中始终使用/ 。

当一个类因其文件位置而被标记为 "内部 "时，"内部 "状态会通过节点层次结构自动传播给其所有成员。

示例 - Qt 公约（glob）：

internalfilepatterns = *_p.h

在任何目录深度匹配以_p.h 结尾的任何文件。

示例 - 多个文件名模式（glob）：

internalfilepatterns = *_p.h *_impl.h *_pch.h

匹配以_p.h 、_impl.h 或_pch.h 结尾的文件。

示例 - 基于目录的匹配（regex）：

internalfilepatterns = .*/internal/.*\.h

匹配internal 目录中任何深度的任何.h 文件。

示例 - 多重模式：

internalfilepatterns = *_p.h .*/private/.*\.h

将用于简单情况的 glob 模式与用于复杂路径的 regex 结合起来。

QDoc 在 Qt 6.11 中引入了internalfilepatterns 。

另请参见： excludedirs和excludefiles。

忽略单词

ignorewords 变量用于指定 QDoc 在解析超链接目标时将忽略的字符串列表。

QDoc 具有自动链接功能，会尝试链接与 C++ 或 QML 实体相似的单词。具体来说，如果字符串长度至少为三个字符，没有空白，并且

• 是camelCase单词，即至少包含一个大写字符，且索引大于零，或
• 包含子串() 或:: ，或
• 至少包含一个特殊字符@ 或_ 。

在ignorewords 中添加限定词会阻止 QDoc 自动链接该词。例如，如果单词OpenGL是一个有效的链接目标（一个部分、 \page或 \externalpage标题），则可以使用

ignorewords += OpenGL

显式链接 \l的方式明确链接，对被忽略的词语仍然有效。

ignorewords 变量是在 QDoc 5.14 中引入的。

ignoresince

ignoresince 变量用于设置传递给 \since命令传递的版本的截止值。所有定义的版本低于截止值的\since 命令都会被忽略，不会产生输出。

截断值取决于具体项目。项目名称可以定义为子变量。默认项目名称为Qt。例如

ignoresince      = 5.0
ignoresince.QDoc = 5.0

这些命令将忽略主版本为 4 或更低且项目为QDoc 或未定义的\since 命令。

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

ignoresince 变量在 QDoc 5.15 中引入。

另请参见 \since.

imagedirs

imagedirs 变量用于指定包含文档中使用的图片的目录。

和 images和imagedirs 变量被 \image和 \inlineimage命令使用。如果同时定义了 images和imagedirs 变量都已定义，QDoc 将在这两个变量中进行搜索。首先在 images中搜索，然后在imagedirs 中搜索。

QDoc 将按指定顺序搜索目录，并接受找到的第一个匹配文件。它只会在指定的目录中搜索，而不会在子目录中搜索。

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

处理时

\image calculator-example.png

QDoc 会查看images 变量中是否有名为 calculator-example.png 的文件。如果没有，它将在imagedirs 变量中搜索：

$QTDIR/doc/src/images/calculator-example.png

如果该文件不存在，QDoc 将查找名为

$QTDIR/examples/calculator-example.png

的文件

imagesoutputdir 变量控制 QDoc 用来存储图像的输出目录下的子目录名称。

imagesoutputdir 的默认值是images。

作为参数传递给 \image和 \inlineimage命令的参数传递的图像文件将被复制到此目录。

为图像设置自定义输出目录对于多模块文档构建非常有用，因为在多模块文档构建中，多个文档项目被配置为使用共享输出目录。例如，使用以下（共享）配置：

imagesoutputdir = images/${project}

构建中的每个文档项目都使用<outputdir>/images/<project name> 来存储图像，从而避免名称相同的图像文件相互覆盖。

QDoc 在 Qt 6.11 中引入了这个变量。

语言

language 变量用于指定文档中使用的源代码语言。具体来说，它定义了解析\code...\endcode 块中源代码的默认语言。

language = Cpp

默认语言是 C++ (Cpp)，无需明确指定。如果文档中的代码片段主要由 QML 代码组成，则将 QML 设置为默认语言：

language = QML

另请参见 \code.

位置信息

locationinfo 布尔变量决定是否将每个实体的详细位置信息写入.index-files 和.webxml-files（使用 WebXML 输出格式时）。

位置信息包括源代码中声明或文档注释块的完整路径和行号。

将此项设置为false 将关闭位置信息：

locationinfo = false

默认值为true 。

locationinfo 变量在 QDoc 5.15 中引入。

日志警告

logwarnings 布尔变量决定 QDoc 是否将警告信息写入除 stderr 之外的日志文件。

当设置为true 时，QDoc 会在输出目录中创建一个名为<project>-qdoc-warnings.log 的日志文件，并将所有警告信息写入该文件。警告信息仍会像往常一样写入 stderr。

日志文件包括一个包含项目信息的头文件，默认情况下还包括用于调用 QDoc 以进行重现的命令行参数。

将其设置为true 可启用警告日志：

logwarnings = true

默认值为false 。

此功能对大型文档集或 CI 环境非常有用，因为在这些环境中，警告可能很多，而且滚动速度太快，无法进行系统分析。

logwarnings 变量在 QDoc 6.11 中引入。

logwarnings.disablecliargs

logwarnings.disablecliargs 布尔型子变量控制是否从警告日志文件头省略 CLI 参数。

logwarnings.disablecliargs = true

当设置为true 时，命令行参数会从日志文件头中省略，从而使日志文件可在不同环境中移植。这对于命令行参数包含特定环境路径和临时目录的测试套件和 CI 系统非常有用。

默认值为false 。logwarnings.disablecliargs 变量在 QDoc 6.11 中引入。

宏

macro 变量用于创建您自己的简单 QDoc 命令。语法为 macro.command = definition.命令限于字母和数字字符的组合，但不能使用破折号或下划线等特殊字符。.定义使用 QDoc 语法编写。

宏变量可限制用于一种类型的输出生成。例如，在宏名后附加.HTML ，宏就只能在生成 HTML 输出时使用。

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

第一个宏定义\key 命令，使用粗体字体显示参数。第二个宏定义了\raisedaster 命令，以显示上标星号，但只在生成 HTML 时使用。

宏最多可包含 7 个参数：

macro.hello            = "Hello \1!"

向宏传递参数的方式与向其他命令传递参数的方式相同：

\hello World

当使用多个参数或参数中包含空白时，请用大括号将每个参数括起来：

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

可以添加一个特殊的宏选项match，以便对扩展宏进行额外的正则表达式模式匹配。

例如

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

创建一个宏\qtminorversion ，根据 QT_VER 环境变量扩展到次要版本。

定义了匹配模式的宏会输出连接在一起的所有捕获组（括号），如果模式不包含任何捕获组，则输出准确的匹配字符串。

有关预定义宏的更多信息，请参阅宏。

清单

manifestmeta 变量用于指定 QDoc 生成的示例清单文件的附加元内容。

更多信息，请参阅清单元内容部分。

模块头

moduleheader 变量定义文档化 C++ 模块的模块头名称。

记录 C++ 应用程序接口的项目需要一个模块级头文件，其中包括模块的所有公有类、命名空间和头文件。QDoc 中的 Clang 解析器会使用该文件为模块创建预编译头文件（PCH），以提高解析源文件的速度。

默认情况下，项目名称也被用作模块头文件的名称。

project = QtCore

使用上述项目名称，QDoc 会在所有已知包含路径中搜索模块头QtCore；首先使用作为命令行参数传递的路径，然后使用includepaths变量中列出的路径。

如果找不到模块头，QDoc 会发出警告。然后，它将尝试根据headerdirs变量中列出的头文件创建一个人工模块头文件。

对于 Qt 文档项目，只要project 变量设置正确，联编系统通常会为 QDoc 提供正确的包含路径，以定位模块头文件。moduleheader 变量提供了供 QDoc 搜索的替代文件名。

如果项目不包含 C++ 文档，则应通过将moduleheader 设置为空字符串来指示 QDoc 跳过生成 PCH：

# No C++ code to document in this project
moduleheader =

另请参阅includepaths和project。

自然语言

naturallanguage 变量用于指定 QDoc 生成的文档所使用的自然语言。

naturallanguage = zh-Hans

默认情况下，自然语言是en ，以便与传统文档兼容。

QDoc 会使用lang 和xml:lang 属性将自然语言信息添加到生成的 HTML 中。

另请参阅源编码、输出编码、C.7。lang 和 xml:lang 属性以及最佳实践 13：使用 Hans 和 Hant 编码。

导航

navigation 子变量（如果已定义）可设置主页、登陆页、C++ 类页面和 QML 类型页面，这些页面在每个页面生成的导航栏中可见。

在有多个子项目（如 Qt 模块）的项目中，每个子项目通常都会定义自己的登陆页面，而所有子项目都使用相同的主页。

子变量

例如

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

上述配置可生成Item QML 类型的导航栏：

Qt 5.10 > Qt Quick > QML Types > Item QML Type

目录和导航链接

如果有一个或多个页面充当目录 (TOC)，请在navigation.toctitles 中列出其标题，以便为 TOC 中列出的所有页面自动生成导航（上一页和下一页）链接。

QDoc 希望每个 TOC 页面都有 \list的链接。允许嵌套子列表。

例如

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
        \list
            \li \l {What's new in v1.3} {v1.3}
            \li \l {What's new in v1.2} {v1.2}
            \li \l {What's new in v1.1} {v1.1}
        \endlist
\endlist

自 QDoc 6.10 版起，还可以在目录列表中出现 \generatelist可以出现在目录列表中：

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
    \generatelist [descending] whatsnew
\endlist

这里的结果与第一个\list 类似，假设所有三个 "新内容 "页面都属于同一个whatsnew 组。

另请参见 \ingroup.

重载信号目标

默认值：connecting-overloaded-signals

overloadedsignalstarget 变量指定自动生成的超载信号注释中使用的链接目标。

当 QDoc 遇到过载信号时，它会生成一个注释，其中包含连接到过载信号的帮助文档链接。默认情况下，它会链接到名为connecting-overloaded-signals 的目标。

项目可对此进行自定义，以链接到自己的文档：

# Link to a target within the project
overloadedsignalstarget = signals-guide.html#overloaded-signals

# Link to external documentation
overloadedsignalstarget = https://example.com/docs/signals.html#overloaded-signals

目标可以是

• 一个简单的目标名称（用于 \target命令）：connecting-overloaded-signals
• 相对 URLsignals-guide.html#overloaded-signals
• 绝对 URLhttps://example.com/docs/signals.html#overloaded-signals

另请参阅overloadedslotstarget。

超载时隙目标

默认值：connecting-overloaded-slots

overloadedslotstarget 变量指定自动生成的超载槽注释中使用的链接目标。

当 QDoc 遇到一个超载槽时，它会生成一个注释，其中包含连接到超载槽的帮助文档链接。默认情况下，它会链接到名为connecting-overloaded-slots 的目标。

项目可对此进行自定义，以链接到自己的文档：

# Link to a target within the project
overloadedslotstarget = signals-guide.html#overloaded-slots

# Link to external documentation
overloadedslotstarget = https://example.com/docs/slots.html#overloaded-slots

目标可以是

• 一个简单的目标名称（用于 \target命令）：connecting-overloaded-slots
• 相对 URLsignals-guide.html#overloaded-slots
• 绝对 URLhttps://example.com/docs/slots.html#overloaded-slots

另请参阅重载信号目标。

输出目录

outputdir 变量用于指定 QDoc 生成文档的目录。

outputdir = $QTDIR/doc/html

将生成的 Qt 参考文档放在 $QTDIR/doc/html。例如，QWidget 类的文档位于

$QTDIR/doc/html/qwidget.html

相关图片将放在images 子目录中。

输出编码

outputencoding 变量用于指定 QDoc 生成的文档所使用的编码。

outputencoding = UTF-8

默认情况下，输出编码为ISO-8859-1 (Latin1)，以便与传统文档兼容。在为某些语言（尤其是非欧洲语言）生成文档时，这种编码是不够的，需要使用 UTF-8 等编码。

QDoc 将使用这种编码对 HTML 进行编码，并生成正确的声明，以向浏览器说明使用的是哪种编码。还应该指定naturallanguage配置变量，以便为浏览器提供一套完整的字符编码和语言信息。

另请参阅outputencoding和naturallanguage。

输出格式

outputformats 变量用于指定生成文档的格式。

自 Qt 5.11 起，QDoc 支持 HTML 和 WebXML 格式；自 Qt 5.15 起，它还能以 DocBook 格式生成文档。如果没有指定outputformats ，QDoc 将以 HTML（默认格式）生成文档。所有输出格式都可以指定，并有专门的输出目录和其他设置。例如

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

使用默认设置生成 HTML 文档，以及输出子目录webxml 中的 WebXML 文档。

输出前缀

outputprefixes 变量用于指定文件类型与输出文件名前缀之间的映射。

QDoc 支持为 QML 类型、C++ 类、命名空间和头文件引用页的文件名添加输出前缀。

outputprefixes     = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-

默认情况下，包含 QML 类型的 API 文档的文件以qml- 为前缀。在上例中，使用了uicomponents- 作为前缀。

同样，在上例中，C++ 类型文档页面的前缀是components- 。默认情况下，C++ 类型页面没有前缀。

输出前缀

outputsuffixes 变量用于指定文件类型与模块或类型名称后缀之间的映射，这些后缀会出现在输出文件名中。

QDoc 支持为模块页面、QML 类型、C++ 类、命名空间和头文件引用页面的文件名添加输出后缀。

默认情况下，不使用后缀。如果定义了 QML 输出后缀，它将作为模块名的后缀，出现在 QML 类型和 QML 模块页面的文件名中。

C++ 类型的文件名不包括模块名。如果定义了 CPP 输出后缀，它将作为后缀应用于类型名称。

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

根据上述定义，给定 QML 模块名FooBar和默认输出前缀(qml-)，为 QML 类型FooWidget生成的文件名是qml-foobar-tp-foowidget.html 。

同样，对于 C++ 类QFoobar，QDoc 生成的文件名是qfoobar-tp.html 。

outputsuffixes 变量是在 QDoc 5.6 中引入的。

qhp

qhp 子变量用于定义要写入Qt Help Project (qhp) 文件的信息。

有关此过程的信息，请参阅创建帮助项目文件一章。

自 QDoc 6.6 以来，将基础qhp 变量设置为true 意味着预计会有一个有效的帮助项目配置：

qhp = true

如果项目配置没有定义qhp.projects ，QDoc 会发出警告。这有助于确保所有共享顶层.qdocconf文件的文档项目（如 Qt）都配置正确。

要关闭警告，可将变量设置为false 。

源irs

sourcedirs 变量指定包含文档中使用的.cpp 或.qdoc 文件的目录。

sourcedirs  += .. \
               ../../../examples/gui/doc/src

执行时，QDoc 将首先读取 header变量中指定的头文件，以及headerdir 变量中指定的目录（包括所有子目录）中的头文件，建立类及其函数的内部结构。

然后，它将读取在 sources变量中指定的目录（包括所有子目录）中的源代码。 sourcedirs变量（包括所有子目录）中指定的源代码，将文档与从头文件中获取的结构合并。

如果同时定义了sources 和sourcedirs 变量，QDoc 将同时读取这两个变量，先读取 sources然后是sourcedirs 。

在指定的目录中，QDoc 将只读取fileextensions 变量中指定的文件。 sources.fileextensions变量指定的文件。变量指定的文件 sources指定的文件将被读取，与其文件扩展名无关。

另请参阅sources和sources.fileextensions。

源编码

sourceencoding 变量用于指定源代码和文档使用的编码。

sourceencoding = UTF-8

默认情况下，源代码编码为ISO-8859-1 (Latin1)，以便与传统文档兼容。对于某些语言，特别是非欧洲语言，这种编码是不够的，需要使用 UTF-8 等编码。

虽然 QDoc 会使用编码读取源代码和文档文件，但 C++ 编译器的限制可能会阻止您在源代码注释中使用非 ASCII 字符。在这种情况下，可以完全在文档文件中编写 API 文档。

另请参阅naturallanguage和outputencoding。

源代码

使用sources 变量，除了可以指定sourcedirs变量指定的目录中的源文件外，还可以指定单个源文件。

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

处理sources 变量时，QDoc 的行为与处理sourcedirs变量时的行为相同。更多信息，请参阅sourcedirs变量。

另请参阅sourcedirs。

sources.fileextensions

sources.fileextensions 变量用于过滤源代码目录中的文件。

在处理 sourcedirs变量中指定的源文件时，QDoc 将只读取sources.fileextensions 变量中指定的文件扩展名的文件。这样，QDoc 就可以避免花时间读取无关文件。

默认扩展名为 *.c++、*.cc、*.ppp、*.cxx、*.mm、*.qml 和 *.qdoc。

扩展名以标准通配符表达方式给出。您可以使用 "+="将文件扩展名添加到过滤器中。例如

sources.fileextensions += *.CC

另请参阅源代码和来源。

虚假

spurious 变量从输出中排除指定的 QDoc 警告。警告使用标准通配符表达式指定。

spurious = "Cannot find .*" \
"Missing .*"

确保在运行 QDoc 时，与这些表达式中任何一个匹配的警告都不会成为输出的一部分。例如，输出中将省略以下警告：

src/opengl/qgl_mac.cpp:156: Missing parameter name

语法高亮

syntaxhighlighting 变量用于指定 QDoc 是否要对其生成的文档中引用的源代码执行语法高亮显示。

syntaxhighlighting = true

将启用所有支持的编程语言的语法高亮显示。

制表符大小

tabsize 变量定义制表符的大小。

tabsize = 4

将使制表符的大小为 4 个空格。该变量的默认值为 8，无需指定。

标签文件

tagfile 变量用于指定生成 HTML 时要写入的 Doxygen 标记文件。

版本

version 变量指定文档软件的版本号。

version = 5.6.0

指定版本号时（使用 version或 versionsym.qdocconf 变量），就可以通过相应的\version 命令访问该版本号，以便在文档中使用。

另请参阅版本ym。

版本ym

versionsym 变量指定一个 C++ 预处理器符号，用于定义文档软件的版本号。

versionsym = QT_VERSION_STR

QT_VERSION_STR 在 qglobal.h 中的定义如下

#define QT_VERSION_STR   "5.14.1"

当指定版本号时（使用 version或 versionsym.qdocconf 变量）时，可通过相应的\version 命令访问该版本号，以便在文档中使用。

另请参见 \version.

警告限制

warninglimit 变量设置了允许的最大文档警告数。如果超过此限制，QDoc 将继续正常运行，但会以警告次数作为错误代码退出。如果未超过限制或未定义warninglimit ，QDoc 进程将以 0 退出，假定没有其他严重错误。

将warninglimit 设置为0 意味着任何警告都会失败。

例如

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

warninglimit 变量在 Qt 5.11 中引入。