通用配置变量

通过通用的 QDoc 配置变量，您可以定义 QDoc 查找生成文档所需的各种源文件的位置，以及存放生成的文档的目录。您还可以对 QDoc 本身进行一些细微的调整，以控制其输出和处理行为。

codeindent

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

QDoc最初使用四个空格作为代码缩进的硬编码值，以确保代码片段能与周围文本轻松区分。由于我们可以使用样式表来调整某些类型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

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

在这种情况下，当 QDoc 处理 qtgui.qdocconf 文件中定义的源文件时，-D 选项可确保预处理器符号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 = *

另请参阅indexes、project 和url。

documentationinheaders

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

该功能随 Qt 6.9 引入 QDoc。

exampledirs

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

calculator.cpp QDoc 会检查 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

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.fileextensions。

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简体中文（大陆）

通过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

extraimages 变量用于指示QDoc将特定图片纳入生成的文档中。

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

其通用语法为 format.extraimages = image。

示例：

HTML.extraimages = images/qt-logo.png

另请参阅images和imagedirs。

虚假信息

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

该变量的取值为正则表达式（详情请参见QRegularExpression ）。如果某个预处理器符号未设置此变量，QDoc 会将其真值默认为 true。例外情况是 '0'，它始终被视为 false。

QDoc 将识别并能够评估以下预处理器语法：

#ifdef NOTYET
 ...
#endif

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

然而，遇到未知语法时，例如

#if NOTYET
    ...
#endif

QDoc 会默认将其评估为真，除非在 falsehoods 变量条目中指定了预处理器符号：

falsehoods = NOTYET

另请参阅defines。

generateindex

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

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

headerdirs

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中指定的源文件，以及位于xml-ph-0000@deepl.internal变量所指定的目录（包括所有子目录）中的源文件，从而构建类及其函数的内部结构。随后，它将读取 sourcedirs 变量中指定的目录（包括所有子目录）内的源文件，并将文档与从头文件中提取的结构进行合并。

如果同时定义了headers 和headerdirs 这两个变量，QDoc将依次读取这两个变量，首先 headersheaderdirs 。

在指定的目录中，QDoc 仅会读取与fileextensions 变量中指定的值相匹配的文件 headers.fileextensions 中指定的xml-ph-0000@deepl.internal文件。由 headers 中指定的文件将被读取，且不考虑其文件扩展名。

另请参阅headers和headers.fileextensions。

headers

headers 变量允许您在由 headerdirs 变量指定的目录之外，额外指定单个头文件。

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

在处理headers 变量时，QDoc 的行为与处理 headerdirs 变量时的处理方式完全相同。有关更多信息，请参阅 headerdirs 变量。

另请参阅headerdirs。

headers.fileextensions

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

在处理 headerdirs 中指定的头文件时，QDoc 只会读取文件扩展名为headers.fileextensions 变量中指定内容的文件。通过这种方式，QDoc 避免了花费时间读取无关文件。

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

这些扩展名采用标准的通配符表达式形式。您可以使用“+=”向过滤器中添加文件扩展名。例如：

header.fileextensions += *.H

另请参阅headerdirs。

includepaths

includepaths 变量用于向Clang解析器传递额外的包含路径，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

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

当 `showinternal` 设置为 `false `（默认值）时，这些实体将被排除在文档验证之外。当 `showinternal ` 设置为 `true` 时，它们将被包含在文档中，但仍保留其“内部”状态，从而允许生成器对其采用不同的样式（例如为内部 API 添加视觉标识）。

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

模式语法

这些模式支持两种语法：

• Shell 风格的通配符模式：简单的通配符，其中* 匹配任意字符，而? 匹配恰好一个字符。通配符模式仅与文件名进行匹配，而非完整路径，因此非常适合用于*_p.h 这样的模式。
• 正则表达式：对于基于路径的匹配，请使用正则表达式语法。任何包含正则表达式元字符（^$[]{}()|+\\. ）的模式都会被视为正则表达式，并针对完整的标准化文件路径进行匹配。

模式匹配时将正斜杠（/ ）视为目录分隔符。QDoc 会在内部对路径分隔符进行规范化处理，因此无论在何种平台上，模式中均应始终使用/ 。

当某个类因其文件位置而被标记为“Internal”时，“Internal”状态会通过节点层次结构自动传播到其所有成员。

示例——Qt 规范（glob）：

internalfilepatterns = *_p.h

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

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

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

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

示例——基于目录的匹配（正则表达式）：

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

匹配位于任意深度、任意internal 目录下的任何.h 文件。

示例——多个模式：

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

将通配符模式与正则表达式相结合，用于处理简单情况和复杂路径。

QDoc在Qt 6.11中引入了internalfilepatterns 。

另请参阅： excludedirs和excludefiles。

ignorewords

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

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

imagesoutputdir 的默认值为images。

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

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

imagesoutputdir = images/${project}

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

该变量随 Qt 6.11 引入 QDoc。

语言

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

language = Cpp

默认语言为 C++（Cpp），无需显式指定。如果文档中的代码片段主要由 QML 代码组成，请将 QML 设置为默认语言：

language = QML

另请参阅 \code。

locationinfo

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

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

将此变量设置为false 将禁用位置信息：

locationinfo = false

默认值为true 。

locationinfo 变量于 QDoc 5.15 版本中引入。

logwarnings

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。command仅限于字母和数字的组合，但不能包含连字符或下划线等特殊字符。definition需使用 QDoc 语法编写。

宏变量可被限制仅用于某一种输出生成类型。例如，在宏名称后附加.HTML ，该宏就仅在生成 HTML 输出时使用。

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

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

一个宏最多可接受七个参数：

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

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

有关详细信息，请参阅“清单元数据”一节。

moduleheader

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

对 C++ API 进行文档记录的项目需要一个模块级头文件，该文件应包含该模块的所有公共类、命名空间和头文件。QDoc 中的 Clang 解析器会使用该文件为该模块构建预编译头文件（PCH），以提高解析源文件的速度。

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

project = QtCore

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

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

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

对于不包含 C++ 文档的项目，请使用 parsecppcomments 变量来禁用 C++ 解析。将moduleheader 设置为空字符串具有相同的效果，且出于向后兼容性考虑，该设置受到支持：

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

另请参阅 parsecppcomments、includepaths 和project。

自然语言

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

naturallanguage = zh-Hans

默认情况下，为确保与旧版文档的兼容性，自然语言设置为en 。

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

另请参阅sourceencoding、outputencoding、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 中列出其标题，以便为目录中列出的所有页面自动生成导航（上一页和 下一页）链接。

QDoc 期望在每个目录页面上包含 \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 类似，前提是这三个 `What's new` 页面都属于同一个whatsnew 组。

另请参阅 \ingroup。

overloadedsignalstarget

默认值： 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
• 一个相对 URL：signals-guide.html#overloaded-signals
• 一个绝对 URL：https://example.com/docs/signals.html#overloaded-signals

另请参阅overloadedslotstarget。

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
• 一个相对 URL：signals-guide.html#overloaded-slots
• 一个绝对 URL：https://example.com/docs/slots.html#overloaded-slots

另请参阅overloadedsignalstarget。

outputdir

outputdir 变量指定了QDoc将生成的文档保存到的目录。

outputdir = $QTDIR/doc/html

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

$QTDIR/doc/html/qwidget.html

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

outputencoding

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

outputencoding = UTF-8

默认情况下，输出编码为ISO-8859-1 （Latin1），以确保与旧版文档的兼容性。在为某些语言（尤其是非欧洲语言）生成文档时，此编码可能无法满足需求，需要使用UTF-8等编码。

QDoc 将使用该编码对 HTML 进行编码，并生成正确的声明，以告知浏览器所使用的编码。还应指定 `naturallanguage` 配置变量，以便向浏览器提供完整的字符编码和语言信息。

另请参阅outputencoding和naturallanguage。

outputformats

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

outputprefixes 变量用于指定文件类型与生成的文档中输出文件名前缀之间的映射关系。

QDoc 支持为 QML 类型、C++ 类、命名空间以及头文件参考页面的文件名添加输出前缀。

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

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

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

outputsuffixes

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 中引入的。

parsecppcomments

parsecppcomments 变量用于控制 QDoc 是否使用基于 Clang 的 C++ 解析器来解析 C++ 源文件。

当设置为false 时，QDoc将跳过该项目的Clang解析和PCH生成，转而使用纯文档解析器来处理.cpp 文件。这对于仅需记录QML API的项目非常有用，因为此类项目的C++源文件中虽包含QDoc注释，但没有需要记录的C++实体。

默认值为true 。

parsecppcomments = false

parsecppcomments 变量是在 Qt 6.12 中引入到 QDoc 中的。

另请参阅 moduleheader。

qhp

qhp 子变量用于定义将写入Qt Help Project（qhp ）文件中的信息。

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

自 QDoc 6.6 起，将基础变量 `qhp ` 设置为 `true ` 意味着系统将期望存在一个有效的帮助项目配置：

qhp = true

此时，如果项目配置中未定义qhp.projects ，QDoc 将发出警告。这有助于确保所有使用共享顶级.qdocconf文件（如 Qt XML 中那样）的文档项目均配置正确。

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

showautogenerateddocs

布尔变量 `showautogenerateddocs ` 用于确定 QDoc 为显式设置了默认值或已被删除的特殊成员函数自动生成的文档是否出现在输出中。

当没有 \fn 代码块对该函数进行文档描述时，QDoc会生成此文档。使用 \fn 编写的文档始终优先于生成的文本，且不受此变量影响。

将此变量设置为false 将省略自动生成的文档：

showautogenerateddocs = false

默认值为true 。

showautogenerateddocs 变量是在 QDoc 6.12 中引入的。

sourcedirs

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

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

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

随后，它将遍历在 sources中指定的源文件，以及位于 sourcedirs 变量中指定的目录（包括所有子目录）中的源文件，并将文档与从头文件中提取的结构进行合并。

如果sources 和sourcedirs 这两个变量都已定义，QDoc将依次读取这两个变量，首先 sources ，然后是sourcedirs 。

fileextensions 在指定的目录中，QDoc 仅会读取与该 sources.fileextensions 中指定的xml-ph-0000@deepl.internal。由 sources 指定的文件将被读取，且不受其文件扩展名的限制。

另请参阅sources和sources.fileextensions。

sourceencoding

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、*.cpp、*.cxx、*.mm、*.qml 和 *.qdoc。

这些扩展名采用标准的通配符表达式形式。您可以使用“+=”向过滤器中添加文件扩展名。例如：

sources.fileextensions += *.CC

另请参阅sourcedirs和sources。

多余的

spurious 变量可将指定的QDoc警告从输出中排除。这些警告通过标准通配符表达式进行指定。

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

该变量可确保在运行 QDoc 时，与这些表达式中任意一个匹配的警告都不会出现在输出中。例如，以下警告是否会被从输出中省略：

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

syntaxhighlighting

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

syntaxhighlighting = true

将启用所有受支持编程语言的语法高亮功能。

tabsize

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

tabsize = 4

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

tagfile

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

version

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

version = 5.6.0

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

另请参阅versionsym。

versionsym

versionsym 变量指定了一个C++预处理器符号，该符号定义了所记录软件的版本号。

versionsym = QT_VERSION_STR

QT_VERSION_STR 在 qglobal.h 中定义如下

#define QT_VERSION_STR   "5.14.1"

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

另请参阅 \version。

warninglimit

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 中引入的。