如何解决 QDoc 警告

在生成文档集时，QDoc 可能会发出警告。本节将介绍这些警告的含义以及如何解决它们。本文档不描述由 Clang 生成的警告。

无法链接到 <target>

当文档的一部分（在警告消息中标识）试图引用另一部分，但没有正确指定该另一部分（即链接的目标）时，QDoc 就会发出该警告。出现这种情况的原因可能是对它的引用输入错误，或目标名称（函数或类型）或标题（另一部分）发生了变化。

在源代码中搜索该链接目标。如果没有结果，就逐渐降低搜索的具体程度，直到找到匹配的结果。

如果链接目标看起来像一个类型或函数的名称，也可能是由于以下原因造成的：

• 文档中使用的名称（或函数的签名）与声明中使用的名称不匹配。
• 链接目标被标记为\internal，而链接文本不是。

在表格中的表项外发现了一条 （target）命令

如果 QDoc 在表格... 中遇到了一条 target 命令，而它前面没有一条 li 命令，那么它就会发出问题。\endtable块中，它会发出这个警告。警告后面的文字是将 \target 移至 \li 内以解决此警告。

找不到要引用的片段文件

如果 QDoc 无法找到以\snippet或\quotefromfile命令命名的文件，它就会发出这个警告。

一些有用的纠正步骤

• 检查片段文件名是否正确。QDoc 会将片段文件名追加到搜索路径中给出的每个目录，以获得要查找的候选文件的路径名。如果这些候选文件都不存在，QDoc 就会产生此错误。
• 检查*.qdocconf 文件中exampledirs 配置变量给出的片段搜索路径。您可能需要在此路径中添加一个条目，或更正现有条目。
• 检查片段文件是否存在，或是否已被移动、重命名或删除，当 QDoc 试图引用的源代码发生变化时，可能会出现这种情况。

意外的片段

如果 QDoc 无法找到在\snippet命令中引用的片段文件，则会发出此警告。

无文档的 QML <module> 被 <type> 或其成员引用

如果 QDoc 无法根据传递给与 QML类型相关联的\inqmlmodule或\qmlproperty命令的标识符找到 QML 模块，它就会发出这个警告。

这意味着要么缺少\qmlmodule的文档，要么在 \qmlproperty、\qmlmethod 或 \qmlsignal 命令中使用了不正确的模块标识符。

在 QML <module> 中没有这样的 <type> 。

如果一个\qmlproperty、\qmlmethod 或 \qmlsignal命令参数使用了 QML 模块标识符，但相关的\qmltype不属于该模块，QDoc 就会发出这个警告。

如果定义了 QML 模块标识符，它必须与 QML 类型文档中的（inqmlmodule）参数相匹配。在大多数情况下，QDoc 能够在没有模块标识符的情况下找到 QML 类型。

未注明的返回值

对于返回类型不是 void 的函数，QDoc 会检查返回值是否有文档记录。如果函数或方法的文档不包含以 "return "开头的单词，则会发出该警告。

未记录的参数

QDoc 要求函数或方法的文档描述每个参数。QDoc 通过在\a命令之后出现的每个参数名称（在头文件中声明函数或方法时指定）来识别这一点。

对于函数重载文档，只要重载用 \overload命令标记了重载，并且存在同名的文档齐全的函数。

无此类参数

当\a命令后给出的参数名与头文件中正在文档化的函数或方法的声明中命名的任何参数不匹配时，QDoc 会发出此警告。

未知宏

当 QDoc 看到一个反斜杠（\ ）后跟了一个它无法识别为内置命令或用户定义宏名称的标记时，就会发出该警告。在引用包含字符转义序列的代码时，应以 \c{...}将代码括起来，以防止出现针对转义序列的警告。

解析 \fn <signature> 时找不到函数

当 Clang 解析一个跟随在 \fn命令后解析函数签名时，会对照头文件中的声明进行检查。如果 Clang 发现差异，会发出此警告信息。

签名必须是完全合格的。典型的问题包括缺少或不正确的模板参数、返回类型或限定符（如const）。

QML 类型 <TypeName> 以 <ClassName> 作为其本地类型。用 <OtherClass> 替换 <ClassName>

如果 \nativetype命令在属于同一个文档项目的多个 QML 类型文档注释中使用了相同的参数，QDoc 会发出这个警告。要解决这个问题，请确保每个 C++ 类只使用\nativetype 命令一次。

无法将此文档与任何内容绑定

QDoc 发现一个 /*！ ...*/ 注释，且没有主题命令，后面没有紧跟类、函数或属性定义。因此，它不知道该注释记录了什么。

该 qdoc 注释不包含主题命令（例如，\module, \page）

如果 QDoc 注释不包含主题命令，QDoc 就不知道该注释记录了什么，并发出该警告。与Cannot tie this documentation to anything（无法将此文档与任何内容绑定）非常相似，但专门针对不在 C++ 或 QML 文件中的注释。

<name> 文档不止一次

当 QDoc 发现有两条注释记录了同一个项目时，就会发出此警告。之前看到的注释的位置会在警告详情中提供。

例如，当一个函数在其定义之前有一个文档注释，而在其他地方有一个单独的 \fn 注释时，您就会看到这个警告。

<topic> 不能与其他主题命令混合使用

在某些使用情况下，QDoc 允许在单个文档注释中使用多个主题命令。使用来自不同类别的多个主题命令会打印出此警告，并且主题不会生成任何输出。

名称空间 <name> 已记录超过一次

该警告表示文档集包含两个注释，其中包含具有相同参数 <name> 的名称空间命令。

<name> 已有文档记录，但命名空间 <namespace> 在任何模块中都没有文档记录

找到了<name>的文档，但<name>是在一个命名空间下声明的，而该命名空间要么没有文档，要么 QDoc 无法找到其文档。

要解决这个问题，可以将<namespace> 文档化，或者如果它已经在另一个模块中文档化，则确保该模块与它有依赖关系。

另请参阅depends和 {indexes-variable}{indexes}。

没有 inmodule 命令

如果 QDoc 注释没有使用\inmodule命令将类、命名空间或头文件与模块相关联，QDoc 就会发出这个警告。

如果 QDoc 注释描述的实体不是其他实体（通常是命名空间或类）的成员，那么它应该使用\relates或\inmodule将其与更广泛的上下文关联起来。如果不这样做，就会发出警告。

无法在任何头文件中找到用 \<command> 指定的<name>。

这意味着 QDoc 在任何头文件中都找不到 <name> 的声明，但却找到了声称要记录它的注释。

举个例子：

Cannot find 'Color::Red' specified with '\enum' in any header file.

文档注释声称描述了一个枚举，但 QDoc 在头文件中没有找到该枚举的定义。

这也可能是由于

• <name> 或 <command> 中的错字
• 缺少命名空间或类前缀
• <name> 已转移到另一个命名空间或类中

无法识别 <identifier> 的 QML 模块/类型限定符

传递给\qmlproperty或\qmlmethod的参数包含 qmlModule::qmlType::identifier 的组合，而这个组合在任何地方都没有定义。

例如

Unrecognizable QML module/type qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler 没有名为 DragAxis 的属性。

缺少 <name> 的属性类型

一个\qmlproperty的声明缺少其属性类型。

\qmlproperty 命令的后面应该是属性类型，然后是属性的全称（即名称 ::-joined 在它所属类的名称之后）。

不正确：

\qmlproperty MyWidget::count

正确：

\qmlproperty int MyWidget::count

多次记录的 QML 属性：<identifier>（标识符

当 QDoc 发现有两个 QDoc 注释记录了相同的 QML 属性时，QDoc 会使用此警告，这两个注释可能出现在定义之前，也可能使用了\qmlproperty命令。

命令 <command> 不允许与 QML 属性命令一起使用

举例说明：

\qmlproperty real QtQuick.Controls::RangeSlider::first.value
\qmlproperty real QtQuick.Controls::RangeSlider::first.position
\qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
\qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
\qmlsignal void QtQuick.Controls::RangeSlider::second.moved()

错误信息：

Command '\\qmlsignal' not allowed with QML property commands

此警告专门针对属性组文档。QDoc 允许在单个文档注释中使用多个 qmlproperty 或 qmlattachedproperty 主题命令来记录属性组，其中路径中的最后一个元素是 <group>.<property>。任何其他主题命令都会触发此警告。

无法在 <class> 中找到 <method> 的基本函数

如果使用 \reimp 作为虚拟方法的覆盖来记录一个方法，而基类中没有具有给定名称和签名的虚拟方法，QDoc 将产生此警告。出现这种情况的原因可能是所写的覆盖方法改变了签名，或者不再是虚拟方法。

Illegal \reimp；no documented virtual function for <command> （非法的 \reimp；没有记录的 <command> 虚拟函数

Qdoc 尝试创建指向该函数的链接，但找不到链接目标，可能是因为该函数没有文档记录。如果基类中没有具有此名称和签名的虚拟方法，也会出现这种情况；出现这种情况的原因可能是重命名、签名更改或基类不再声明虚拟方法。

<类>试图继承自身

\inherits命令用于记录 QMl 类型继承了其他 QML 类型。如果其他 QML 类型与记录的 QML 类型相同，就会发出这个警告。

例如

\qmltype Foo
\inherits Foo

\nativetype 只允许在 \qmltype 中使用

\nativetype命令只能在记录 QML 类型的 QDoc 注释中使用。

组中的所有属性必须属于同一类型：<name>。

记录 QML 属性组时，注释块中列出的所有属性必须属于同一 QML 类型。

找不到示例 <name> 的项目文件

在示例的源代码目录中，QDoc 希望找到一个名为CMakeLists.txt 的项目文件，或一个扩展名为.pro 、.qmlproject 或.pyproject 的文件，其基本名称与示例目录中的名称一致。例如，examples/mymodule/helloworld/helloworld.pro 。

无法打开要引用的文件：<文件名

<filename> 的搜索路径由.qdocconf 文件中的以下变量定义：sources,sourcedirs, 和exampledirs 。

QDoc 无法找到命令（如\quotefromfile,\snippet, \include）中命名的文件，而该命令要求它从命名的文件中检索内容。它会搜索搜索路径中命名的每个目录。如果在这些目录中没有该文件名的文件，或者文件找到了但不可读，QDoc 就会发出警告。请检查搜索路径和 <filename> 的组合拼写是否正确，以及您是否拥有该文件的读取权限。

\raw 后缺少格式名称

\raw命令和相应的\endraw命令限定了一个原始标记语言代码块。\raw 命令后必须有格式名称。

宏不能同时具有格式定义和 qdoc 语法定义

指定输出格式的宏（macro）不能同时具有通用定义。

触发此警告的配置示例：

macro.gui = \b
macro.gui.HTML = "<b>\1</b>"

未知命令 <name

当 QDoc 注释中使用了反斜杠，而该反斜杠后面的标记既不是 QDoc 内置命令，也没有被定义为自定义命令宏时，QDoc 将产生此警告。请检查命令名称的拼写，如果是自定义命令，请检查您的 QDoc 配置是否不包括定义该命令的内容。

产生这种警告的原因还可能是 QDoc 注释中引用了代码，例如，作者可能引用了 C 字符串终止符'\0' 或其他 C 字符串转义序列（如'\n' ），但没有转义反斜杠。将反斜线转义为\ ，以便在文档中包含字面反斜线，或者将代码片段括入\c{...} ，这样就可以抑制将反斜线解释为引入 QDoc 命令。

目标名称 <target> 重复

如果使用\target或\keyword命令定义了两个参数相同的目标，则会发出该警告。作为这些命令参数的目标名称必须是唯一的。警告后面会出现 "上一次出现在这里：[位置]"，其中位置包含文件名和行号。

无法找到 qdoc 包含文件 <filename>

QDoc 无法找到命令中命名的包含文件。QDoc 会搜索搜索路径中命名的每个目录。如果在任何这些目录中都没有该文件名的文件，或者在搜索中找到的文件不可读，QDoc 就会发出此警告。请检查搜索路径和 <filename> 的组合拼写是否正确，以及是否有文件的读取权限。

无法在 <file> 中找到 <tag>

这意味着 QDoc 无法在\include<file> 或 {snippet-command}{\snippet} <file> 中找到标识符 <id>。

<file> 中的 qdoc 片段 <tag> 为空

在\snippet<file> 中找到了片段 <tag>，但它是空的。

无法嵌套 <command> 命令

该警告涉及格式化命令：粗体、斜体、索引、链接、span、下标、上标、电传、uicontrol、下划线。格式化命令不能在其适用的文本中使用。举例说明

There is \b{no \b{super-}bold}.
\encode

\section1 Can't use <inner> in <outer>

This warning is issued for commands that cannot be nested.

Example:
\badcode
    \list
        \li \table
            \row \li Hello \li Hi
            \endtable
    \endlist

结果出现 QDoc 警告 "不能在'\list'中使用'\table'"。

在 <inner> 前缺少 <outer>

一些例子：

• \li命令只能在\list或\table 的\row中使用。
• row和header命令只能在表（table）中使用。

意外的 <end_command>

例如，如果你有\endlist，但前面没有\list，就会发出该警告。它适用于所有成对的命令（如 startFoo/endFoo）。

\sa 中缺少逗号

为一个\sa命令列出的标题之间应该用逗号隔开。

宏 <command> 没有默认定义

QDoc 正在尝试展开一个宏，并希望该宏有一个默认定义。某些宏可能只有特定格式的定义。

举例说明

macro.pi.HTML = "π"    # encodes the pi symbol for HTML output format

但在某些情况下，宏扩展需要与格式无关的宏。例如，可以在章节标题中使用宏，但它们必须有默认定义。

调用宏 <macro> 时参数太少（预期 <many>，结果 <few>)

给定宏需要的参数比给定的多。有关详细信息，请参阅配置中宏的定义。

<text> 中的括号不平衡

指向'('，但没有相应的')'，反之亦然。

<name> 没有文档

举例说明：

Warning "No documentation for QNativeInterface."

QDoc 在头文件中检测到命名空间QNativeInterface 的声明，但未找到记录该命名空间的 QDoc 注释。

<class> 中没有 <name> 枚举项

示例：

Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
with \enum in any header file.

当 QDoc 在一个\enum注释中发现一个\value指令，而该指令命名的值在声明枚举类型的头文件中找不到，QDoc 就会发出这个警告。

<enum list> 中的未注明枚举项 <enum>

<enum list> 的\value或\omitvalue条目不包括<enum> 的一条，而 <enum> 在头文件中的 <enum list> 声明中被命名。

查找 qhp.<project>.subjects.<subproject>.indexTitle 失败

QDoc 未能为 Qt help 项目配置中指定为 <subproject> 索引页的页面找到标题。

子项目索引标题必须是当前文档项目的本地标题。使用作为依赖关系加载的其他项目的页面标题也会导致此警告。

有关详细信息，请参阅创建帮助项目文件。

\生成列表 <组> 为空

下面简要介绍了\generatelist 的所有可能参数：

• \注释示例
• \注释的属性
• \类<前缀
• \按模块分类的类 <模块名称
• \qmltypesbymodule <模块名> 。
• \生成列表 functionindex
• \生成法律文本
• \生成列表概述
• \生成列表属性
• \生成列表相关

如果您指定\generatelist <group> ，而该组不包含任何项目，或者如果您指定\generatelist <group> <pattern> ，而该组中没有项目与模式匹配，则 QDoc 会发出此警告。

\generatelist <group> 没有这样的组

如果\generatelist的参数是一个不存在的组，就会发出该警告。

举例说明：

\generatelist draganddrop

该语句生成 draganddrop 组中的类或 QML 类型列表。类或 QML 类型通过\l {ingroup-command}{\ingroup} draganddrop 命令添加到其\class或\qmltype注释中的 draganddrop 组。

如果没有实体有\ingroup draganddrop 语句，QDoc 会发出此警告信息。

缺少图像：<imagefile>。

图像的搜索路径错误，或者图像文件不存在。

无法链接到 <目标>。

这可能有多种原因：

• 未使用 QDoc 主题命令定义链接目标，例如 {title-command}\{title}.<target>。
• <target> 包含一个错字。
• 包含该链接目标的文档未被编译。
• 包含该链接目标的文档所在模块不在编译路径中。
• 链接目标位于另一个模块中，而该模块的依赖关系未在配置中设置，或 QDoc 无法找到依赖关系的索引文件。

无法解析类型 <name> 的 QML 导入语句

如果你记录了一个 QML 类型，但省略了\inqmlmodule命令，QDoc 就会发出这个警告。举例说明：

Could not resolve QML import statement for type 'ItemSelectionModel'
\encode

Incorrect:
  \badcode
  \qmltype ItemSelectionModel
  \nativetype QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

正确：

\qmltype ItemSelectionModel
\nativetype QItemSelectionModel
\inqmlmodule QtQml.Models
\since 5.5
\ingroup qtquick-models

\brief 语句没有以句号结束

\brief 命令的参数是一个总结所记录主题的句子，所以应该以句号结束。它还应该简短。

未安装 QtDeclarative；无法解析 QML

如果 QDoc 在编译时不支持 QML 解析，则会发出此警告。除非您定制了 QDoc，否则不会出现这种情况。

正则表达式 <regex> 无效

某些 QDoc 命令将正则表达式作为参数。当作为此类参数给出的文本不是有效的正则表达式时，QDoc 会给出此警告，这通常是由于它包含了在正则表达式中具有特殊含义的字符，而这些字符本应被转义。

示例

notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'

\quotefromfile webenginewidgets/notifications/data/index.html
\skipuntil resetPermission

无效正则表达式：

\printuntil /^})$/

有效的正则表达式：

\printuntil /^\}\)$/

\printuntil命令打印直到遇到一行仅由右大括号和右小括号组成。在这种情况下，大括号和小括号需要转义，因为它们在正则表达式中具有特殊含义。

为依赖关系 <indexfile>:<depend> 找到多个索引文件

使用 <indexfile> 作为依赖关系 <depend> 的索引文件

多个-indexdir 路径作为命令行选项传给了 QDoc，其中不止一个路径包含与依赖关系相匹配的.index 文件。QDoc 会自动选择具有最新时间戳的文件。

通常情况下，该警告表示以前的文档构建过程中留下了构建工件。

无法找到依赖项 <depend> 的索引文件

示例：

"QMake" Cannot locate index file for dependency "activeqt"

文档项目 QMake 无法在任何指定的索引目录中找到 activeqt.index。在这种情况下，指定的索引目录在 qmake.qdocconf 中指定。

指定了依赖模块，但没有设置索引目录。

QDoc 希望在命令行中看到一个或多个 -indexdir 参数。如果没有这些参数，QDoc 就无法找到用 "depend "配置变量定义的任何依赖模块的索引文件。

覆盖先前的文档

当 QDoc 发现两个注释似乎描述的是同一个实体时，它会发出此警告。警告详情中提供了之前看到的注释的位置。

未识别的列表样式 <name

\list 可以接受一个可选参数：修改列表样式的单个数字或字符。详情请参考 {list-command}{\list} 文档。如果你使用了一个无法识别的参数，QDoc 会发出警告。

无法解析 QML 代码段：<y> 行，<x> 列中的 <code> 。

QDoc 注释可以包含 QML 代码。这些代码可以在片段中找到，也可以在以\qml 和 {endqml-command}{\endqml} 分隔的 QDoc 注释中找到。

举例说明

如果 QML 代码中有语法错误，QDoc 会发出警告

Unable to parse QML snippet: Syntax error at line 97, column 42

片段也可以包含 QML，也会在那里检查代码。例如，如果代码中少了一个大括号，QDoc 就会发出警告

Unable to parse QML snippet: Expected token '{' at line 63, column 52

QDoc 经常无法解析不完整的 QML 片段；在这种情况下，通常可以将 \qml ... 替换为 \endqml 命令。\endqml 命令替换为 \code ...\endcode 来抑制这种警告。

命令 <command> 在文件 <filename> 结束时失败

举例说明：

Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".

在这种情况下，警告表示 snippet命令没有找到第二个标签"//！[2]" 标记片段结束。这也可能意味着它没有在这个片段文件中找到该片段标签。

再举一个例子：

Command '\skipto' failed at end of file 'styling/CMakeLists.txt".

\skipto+ <pattern> 会将光标移到包含该模式的下一行。如果 \skipto 没有找到，QDoc 会发出以下警告。

打开 <file> 以供书写失败

这个警告清楚地表明，它无法打开一个文件进行写入，可能是因为路径错误，或者在某个目录中没有写入权限。

该页面标题存在于多个文件中

title命令为页面设置标题。

\page activeqt-server.html
\title Building ActiveX servers in Qt

如果某个标题在不止一个页面中使用，QDoc 会发出此警告。

内容太长

QDoc 在标记源文件时使用固定大小的缓冲区。如果文件中任何单个标记的字符数超过最大限制，QDoc 就会发出此警告。

当 QDoc 继续解析文件时，只有适合放入缓冲区的标记部分才会被考虑，这意味着输出可能会被混淆。

要解决这个警告，必须缩小相关内容的大小，如果可能，可以将其拆分，或删除其中的部分内容。

例如，警告旁边会显示单个标记的最大字符数：

file.qdoc:71154: (qdoc) warning: The content is too long.

[The maximum amount of characters for this content is 524288.
Consider splitting it or reducing its size.]

未为全局作用域中的函数 <name> 生成文档

QDoc 能够将函数<name>的文档与其声明相匹配，但没有生成输出，因为该函数是在全局命名空间中声明的。

使用\relates命令将函数与文档中的类型、命名空间或头文件关联起来。然后，该函数就会作为相关非成员列在相关的参考页面上。

<project> 的文档配置未定义帮助项目 (qhp)

预计会有一个有效的 Qt 帮助配置，但在项目的 .qdocconf 文件中并未提供。

另请参阅创建帮助项目文件和qhp。

已为该项目生成 FILE

在为项目生成文档时，QDoc 会跟踪已生成文件的文件名。如果在当前执行过程中已知某个文件先前已生成，QDoc 在打开该文件进行编写时会发出警告。如果一条 \page命令与 \group例如

可以将环境变量QDOC_ALL_OVERWRITES_ARE_WARNINGS 设置为无条件警告所有此类事件。这在追踪违规定义时可能很有用。

无效的 QML 属性类型

用于声明 QML 属性的类型不是有效的QML 值类型或QML 对象类型，或者是 C++ 或 Qt 类型。

这种警告通常发生在开发人员引用用于实现 QML 类型的底层 Qt 类型时，如QStringList 而不是list<string> 。