QDoc 警告的故障排除

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

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

在为 QML 属性组生成文档时，注释块中列出的所有属性必须属于同一个 QML 类型。

该项目已生成 <file>

在为项目生成文档时，QDoc 会记录已生成的文件名称。当 QDoc 打开文件进行写入时，如果系统已知该文件在当前执行过程中曾被生成过，则会发出警告。如果 \page 命令使用的名称与 \group 。

您可以设置环境变量QDOC_ALL_OVERWRITES_ARE_WARNINGS ，以便对所有此类事件无条件地发出警告。这在追踪问题定义时可能会很有用。

\brief 语句末尾未以句号结尾

\brief 命令的参数是一句话，用于概括所记录的主题，因此应以句号结尾。此外，该描述应简明扼要。

无法链接到 <target>

当文档中某一部分（在警告消息中已指明）试图引用另一部分，但未正确指定该部分（即链接的目标）时，QDoc 会发出此警告。 这可能是因为引用时输入有误，或者目标已更改名称（对于函数或类型）或标题（对于其他章节）。

这可能由多种原因导致：

• 链接目标未通过 QDoc 主题命令进行定义，例如 {title-command}{\title} <target>。
• <target> 中存在拼写错误。
• 包含该链接目标的文档未被编译。
• 包含该链接目标的文档所在的模块未包含在编译路径中。
• 链接目标位于另一个模块中，且配置中未设置对该模块的依赖，或者 QDoc 无法定位该依赖的索引文件。

请在源代码中搜索该特定链接目标。如果未找到结果，请逐步放宽搜索条件，直到找到匹配项。

如果链接目标看起来像一个类型或函数的名称，这还可能是由于：

• 文档中使用的名称（对于函数，若已指定则为签名）与其声明中使用的名称不匹配。
• 链接目标被标记为 \internal ，而链接文本未被标记。

无法在 <类> 中找到 <方法> 的基类方法

当使用\reimp 对方法进行文档说明（作为对虚拟方法的重写）时，如果基类中不存在具有给定名称和签名的虚拟方法，QDoc会生成此警告。这可能是因为被重写的方法已更改了其签名，或者不再是虚拟方法。

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

这意味着 QDoc 无法在任何头文件中找到 <name> 的声明，但发现了一条声称对其进行文档说明的注释。

示例：

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

某条文档注释声称描述了一个枚举，但 QDoc 未在任何头文件中找到该枚举的定义。

这还可能由以下原因导致：

• <name> 或 <command> 中存在拼写错误
• 缺少命名空间或类前缀
• <name> 已移动到另一个命名空间或类中

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

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

无法找到用于引用代码片段的文件

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

以下是解决此问题的实用步骤：

• 检查代码片段文件名是否正确。QDoc 会将代码片段文件名附加到搜索路径中指定的每个目录后，以此生成待查找文件的路径名。当这些候选文件均不存在时，就会产生此错误。
• 检查代码片段的搜索路径，该路径由*.qdocconf 文件中的exampledirs 配置变量指定。您可能需要向该路径添加一项，或修正现有条目。
• 检查代码片段文件是否存在，或者是否已被移动、重命名或删除——当 QDoc 尝试引用的源代码发生更改时，可能会出现这种情况。

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

QDoc 无法在命令中指定的路径中找到名为 <filename> 的包含文件。QDoc 会搜索搜索路径中列出的每个目录。如果这些目录中均不存在该名称的文件，或者搜索到的文件不可读，QDoc 将发出此警告。 请检查搜索路径与 <filename> 的组合拼写是否正确，并确保您对该文件拥有读取权限。

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

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

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

示例：

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

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

无法嵌套 <command> 命令

此警告涉及以下格式化命令：bold、italic、index、link、span、subscript、superscript、teletype、uicontrol、underline。格式化命令不能在其所应用的文本内部使用。例如：

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'”。

无法打开要引用内容的文件：<filename>

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

QDoc 无法找到命令中指定的文件（例如 \quotefromfile, \snippet, \include），该命令用于指示其从指定文件中检索内容。它会搜索搜索路径中列出的每个目录。如果这些目录中均不存在该名称的文件，或者文件虽被找到但不可读，QDoc 将发出此警告。 请检查搜索路径与 <filename> 的组合拼写是否正确，并确保您对该文件具有读取权限。

无法将此文档与任何内容关联

QDoc 发现了一个 /*! ... */ 注释，其中没有主题命令，且无法将紧跟在该注释后面的声明或定义与任何已记录的实体相关联。 如果注释后没有声明或定义，或者 QDoc 无法看到该实体（例如，当声明位于 QDoc 不会评估的预处理器条件语句之后时），可能会发生这种情况。

<class> 试图继承自身

\inherits 命令用于记录某个 QML 类型继承了其他 QML 类型。如果该其他 QML 类型与被记录的 QML 类型相同，则会触发此警告。

示例：

\qmltype Foo
\inherits Foo

命令 <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将发出此警告。

不允许在 QML 属性命令中使用 <command> 命令

示例：

\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>。任何其他主题命令都会触发此警告。

无法解析类型 <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

循环类型继承：<type>

当一个 QML 类型从一个基类继承，而该基类本身又从原始类型继承时，就会发生循环继承。这种情况可能发生在两个相互继承的类型之间，也可能在它们之间存在中间类型。

此警告指示在继承层次结构中检测到循环的位置。您应检查该类型的 \inherits 该类型的命令，并沿基类路径向上追溯，直至找到一个继承自您先前已遇到类型的基类。随后，您应通过修正其中一个已识别类型的错误 \inherits 命令，从而打破该循环。

已指定依赖模块，但未设置索引目录。

QDoc 期望在命令行上看到一个或多个 –indexdir 参数。如果没有这些参数，QDoc 将无法定位由 'depends' 配置变量定义的任何依赖项的索引文件。

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

预期应提供有效的 Qt Help 配置，但该项目的 .qdocconf 文件中未提供。

另请参阅《创建帮助项目文件》和“qhp”。

目标名称 <target> 重复

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

<file> 中存在空的 qdoc 代码片段 <tag>

在 \snippet <file> 中发现了片段 <tag>，但该片段为空。

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

当 Clang 在执行 \fn 命令后面的函数签名时，会将其与头文件中的声明进行比对。如果 Clang 发现不一致之处，就会发出此警告信息。

该签名必须是完全限定的。常见问题包括缺少或错误的模板参数、返回类型，或const 等限定符。

无法找到 qhp.<project>.subprojects.<subproject>.indexTitle

QDoc 无法找到 Qt Help 项目配置中指定为 <SUBPROJECT> 索引页的页面标题。

子项目的索引标题必须属于当前文档项目。使用作为依赖项加载的来自其他项目的页面标题也会导致此警告。

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

无法以写入模式打开 <file>

此警告明确表示无法打开文件进行写入，可能是由于路径错误，或缺乏某个目录的写入权限。

在表格中发现位于表格项之外的\target 命令

如果 QDoc 在\table...\endtable 代码块内遇到一个\target 命令，而该命令前面未跟有\li 命令，则会发出此警告。警告后会显示提示文本：“将\target 移至\li 内以解决此警告。”

\generatelist <group> 为空

以下简要概述了 \generatelist：

• \generatelist annotatedexamples
• \generatelist 带注释的归属
• \generatelist 类 <前缀>
• \generatelist 按模块分类的类 <模块名称>
• \generatelist 按模块分类的 QML 类型 <模块名称>
• \generatelist 函数索引
• \generatelist 法律术语
• \generatelist 概述
• \generatelist 归属声明
• \generatelist 相关

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

\generatelist <group> 没有此组

如果 \generatelist 的参数为一个不存在的组时，会发出此警告。

示例：

\generatelist draganddrop

该语句会生成 draganddrop 组中类或 QML 类型的列表。类或 QML 类型是通过\l {ingroup-command}{\ingroup} draganddrop 命令，在它们的 \class 或 \qmltype 注释中通过xml-ph-0000@deepl.internal命令添加到draganddrop组中的。

如果没有任何实体包含此\ingroup draganddrop 语句，QDoc将发出此警告信息。

没有\inmodule 命令

如果 QDoc 注释未通过 \inmodule 。

如果 QDoc 注释描述的实体不属于其他实体（通常是命名空间或类），则应使用 \relates 或 \inmodule 来将其与更广泛的上下文关联。若未如此操作，则会触发此警告。

非法的\reimp ；<command> 没有已记录的虚函数

QDoc 尝试创建指向该函数所重写的函数的链接，但未能找到链接目标，这很可能是因为该函数未被文档化。如果没有任何基类具有同名且签名相同的虚拟方法，也会引发此警告；这可能是由于重命名、签名更改或基类不再将其声明为虚拟所致。

无效的 QML 属性类型

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

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

无效的正则表达式 <regex>

某些 QDoc 命令将正则表达式作为参数。当作为此类参数提供的文本不是有效的正则表达式时，QDoc 会发出此警告，通常是因为其中包含在正则表达式中具有特殊含义的字符，而这些字符本应进行转义。

示例：

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

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

无效的正则表达式：

\printuntil /^})$/

有效的正则表达式：

\printuntil /^\}\)$/

\printuntil 命令会持续输出，直到遇到仅由右大括号后跟右圆括号组成的行。在这种情况下，由于大括号和圆括号在正则表达式中具有特殊含义，因此需要对其进行转义。

宏不能同时包含格式特定定义和 qdoc 语法定义

一个 \macro 若指定了输出格式，则不能同时具有通用定义。

以下配置示例会触发此警告：

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

宏 <command> 没有默认定义

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

示例：

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

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

宏 <macro> 调用的参数过少（预期 <many>，实际 <few>）

给定的宏所需的参数数量多于实际提供的数量。有关详细信息，请参阅配置中的宏定义。

在\sa

为 \sa 应使用逗号分隔。

在\raw

该 \raw 命令和相应的 \endraw 命令共同界定了一段原始标记语言代码块。\raw 命令后必须跟上格式名称。

缺少图像：<imagefile>

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

<inner> 前缺少 <outer>

示例：

• 该 \li 命令只能在 \list 或 \row 中 \table中使用。
• 该 \row 和 \header 命令只能在 \table中使用。

<name> 缺少属性类型

对 \qmlproperty 的声明缺少属性类型。

\qmlproperty 命令要求其后跟属性类型，然后是属性的完全限定名称（即在所属类名后使用 ::- 连接的名称）。

错误：

\qmlproperty MyWidget::count

正确：

\qmlproperty int MyWidget::count

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

将 <indexfile> 用作依赖项 <depend> 的索引文件

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

通常，此警告表明存在来自先前文档构建的构建产物。

<function> 存在多个主要重载定义

当多个同名函数被标记为\overload primary 时，QDoc会发出此警告。在重载组中，应仅将其中一个函数指定为主重载。

该警告包含函数签名及其源代码位置，以帮助识别所有相互冲突的主重载。QDoc 将通过在标记为主重载的函数之间进行字典序比较（即按函数签名的字母顺序排序）来确定实际的主重载。

要解决此警告，请从重载组中所有\overload primary 命令中移除primary 参数，仅保留其中一个。

触发此警告的示例：

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload primary
    Does something with a parameter.
*/
void doSomething(int value);

正确做法——仅保留一个主要重载：

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload doSomething()
    Does something with a parameter.
*/
void doSomething(int value);

<名称> 被多次文档化

当 QDoc 发现两个注释描述了同一项内容时，会发出此警告。警告详情中会提供先前发现的注释的位置。

例如，当一个函数在定义前有一个文档注释，而在其他地方又有另一个\fn 注释时，您会看到此警告。

<name> 已有文档，但命名空间 <namespace> 在任何模块中均未被文档化

虽然找到了<name>的文档，但<name>是在未记录的命名空间下声明的，或者 QDoc 无法找到该命名空间的文档。

要解决此问题，可以为<namespace> 编写文档；如果该命名空间已在另一个模块中记录，则需确保此模块对其具有依赖关系。

另请参阅depends和indexes。

命名空间 <name> 被文档化多次

此警告表示，某文档集包含两条注释，其中 \namespace 具有相同参数 <name> 的命令。

\nativetype 仅允许在\qmltype

该 \nativetype 该命令仅可在用于描述 QML 类型的 QDoc 注释中使用。

<name> 没有文档

示例：

Warning "No documentation for QNativeInterface."

QDoc 在头文件中检测到了命名空间QNativeInterface 的声明，但未找到对该命名空间进行文档说明的 QDoc 注释。

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

QDoc 成功将函数<name>的文档与其声明进行了匹配，但由于该函数声明在全局命名空间中，因此未生成任何输出。

请使用 \relates 命令将该函数与已文档化的类型、命名空间或头文件关联。随后，该函数将在关联的参考页面上作为相关非成员函数列出。

由于 <parent> 未被文档化，因此未为 <entity> 生成输出

当 QDoc 解析类成员等 API 实体的文档注释时，如果关联的父级（类）未被文档化，则会发出此警告，且无法生成任何输出。请确保父级已被文档化，并且 QDoc 已配置为解析包含该文档注释的源文件。

如果已记录的成员属于一个不应被记录的类，请将该类标记为 \internal ，或使用 \dontdocument 命令。

<class> 中不存在名为 <name> 的枚举项

示例：

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

当 QDoc 发现 \value 指令时，会发出此警告 \enum 注释中发现指令时，该指令命名的值在声明该枚举类型的头文件中未找到。

没有这样的参数

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

QML <模块> 中不存在此 <类型>

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

如果定义了 QML 模块标识符，则必须与 \inqmlmodule QML 类型文档中的参数。在大多数情况下，QDoc 即使没有模块标识符也能定位到 QML 类型。

覆盖了先前的文档

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

QML 属性被多次文档化：<标识符>

当 QDoc 发现两条 QDoc 注释描述了同一个 QML 属性时（无论是出现在该属性的定义之前，还是使用了 \qmlproperty 命令。

QML 类型 <TypeName> 的文档中将其原生类型标注为 <ClassName>。将 <ClassName> 替换为 <OtherClass>

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

未安装 QtDeclarative；无法解析 QML

如果 QDoc 在编译时未启用对 QML 解析的支持，则会发出此警告。除非您使用了自定义构建的 QDoc，否则不应出现此情况。

<name> 的\sa 命令中存在冗余的自引用链接

某份文档在其 \sa 命令中定义的引用中包含指向自身的链接。

当存在一组相互引用的相关属性或方法，且这些属性或方法之间复制了\sa 命令时，往往会出现此问题，如下例所示：

\fn void Items::append(const Item &)
...
\sa append(), count(), insert(), remove()

建议将这种自引用链接替换为指向另一个相关属性或方法的链接。

此外，链接可能不够具体，导致 QDoc 无法解析，如下例所示：

\fn void MyPicture::setSize(int)
...
\sa setSize()

在这种情况下，本意可能是引用一个接受double 参数的重载方法：

\fn void MyPicture::setSize(int)
...
\sa setSize(double)

内容过长

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.]

此页面标题在多个文件中存在

\title 命令用于设置页面的标题。

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

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

此 qdoc 注释中未包含主题命令（例如：\module 、\page ）

如果 QDoc 注释中不包含主题命令，QDoc 将无法识别该注释所记录的内容，并会发出此警告。这与“无法将此文档与任何内容关联”非常相似，但仅针对不在 C++ 或 QML 文件中的注释。

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

在某些特定用例下，QDoc 允许在单个文档注释中使用多个 topic 命令。若使用来自不同类别的多个 topic 命令，系统将显示此警告，且该 topic 不会生成任何输出。

类型被定义为自身的基类：<type>

该 QML 类型被错误地定义为自身的基类，可能是使用了 \inherits 命令。

无法解析 QML 代码片段：<code>，位于第 <y> 行，第 <x> 列

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 命令替换为\code...\endcode 来抑制此警告。

<text> 中括号不匹配

指出了一个没有对应 ')' 的 '('，反之亦然。

<enum list> 中存在未记录的枚举项 <enum>

<enum list>中的 \value 或 \omitvalue 条目中未包含<enum>，而该枚举在头文件中 <enum list> 的声明中被命名。

未记录的参数

QDoc 要求函数或方法的文档中必须描述每个参数。它通过以下方式识别这一点：每个参数名称（如在头文件中声明函数或方法时所指定）都应出现在 \a 命令之后出现。

对于函数重载的文档，只要该重载已使用 \overload 命令，并且存在一个具有相同名称且已完整记录的函数。

未记录的属性 '<name>'

此警告表明某个 C++ 类中的Q_PROPERTY 声明缺少文档。属性是类公共 API 的一部分，必须使用\property 命令编写文档，以描述其用途、有效值和行为。

<type> 或其成员引用的未记录 QML <module>

如果 QDoc 无法根据传递给 \inqmlmodule 或 \qmlproperty 命令，则会发出此警告。

这意味着 \qmlmodule 的文档缺失，或者在\qmlproperty 、\qmlmethod 或\qmlsignal 命令中使用了错误的模块标识符。

未记录的返回值

对于返回类型不是 void 的函数，QDoc 会检查其返回值是否已记录在文档中。如果函数或方法的文档中不包含以“return”开头的词，则会发出此警告。

意外的 <end_command>

例如，如果出现 \endlist ，但前面没有 \list。此规则适用于所有成对出现的命令（例如 startFoo/endFoo）。

意外的\snippet

如果 QDoc 无法找到 \snippet 中引用的代码片段文件时，会发出此警告。

QML 类型 <type> 的基类 <name> 未知

作为 QML 类型基类声明的类型名称未找到，或者该类型未通过 \inherits 命令中进行声明。

未知命令 <name>

当 QDoc 注释中使用反斜杠后跟一个既非 QDoc 内置命令、也未被定义为自定义命令宏的标记时，QDoc 会生成此警告。请检查命令名称的拼写，并检查您的 QDoc 配置中是否包含本应定义该命令的内容（如果是自定义命令的话）。

此警告也可能由 QDoc 注释中的代码被引号包围引起，例如作者可能引用了 C 字符串终止符'\0' 或'\n' 等其他 C 字符串转义序列，却未对反斜杠进行转义。 若要在文档中包含字面上的反斜杠，请将其转义为\ ；或者将代码片段用\c{...} 括起来，这样可以抑制将反斜杠解释为引入 QDoc 命令。

未知宏

当 QDoc 遇到反斜杠（\ ）后紧跟一个它无法识别为内置命令或用户定义宏名称的标记时，会发出此警告。在引用包含字符转义序列的代码时，应将代码用\c{...} 括起来，以避免因转义序列而触发此警告。

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

传递给 \qmlproperty 或 \qmlmethod 传递的参数中包含 qmlModule::qmlType::标识符的组合，而该组合在任何地方均未定义。

示例：

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

DragHandler 没有名为 DragAxis 的属性。

未识别的列表样式 <name>

\list可以接受一个可选参数：一个用于修改列表样式的单个数字或字符。更多详细信息请参阅 {list-command}{\list} 文档。若使用未被识别的参数，QDoc 会发出此警告。

未识别的标记语言

当为\code 命令指定了 QDoc 不识别的编程语言时，会出现此警告。例如，以下 QML 代码块被指定了无效的“QL”语言：

\code [QL]
Item {
    id: my_item
}
\endcode