QDoc 警告的故障排除

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

无法链接到 <target>

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

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

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

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

在表格中的表项外找到\target 命令

如果 QDoc 在\table...\endtable 块中遇到\target 命令，而该命令之前没有\li 命令，则会发出该警告。警告后有一段文字将\target 移至\li 内，以解决此警告。

找不到要引用的片段文件

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

一些有用的纠正步骤

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

意外\snippet

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

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

如果 QDoc 无法根据传递给 \inqmlmodule或 \qmlproperty命令关联的 QML 模块，QDoc 就会发出这个警告。

这意味着 \qmlmodule的文档丢失，或者在\qmlproperty,\qmlmethod, 或\qmlsignal 命令中使用了不正确的模块标识符。

QML <模块>中没有这样的 <类型>。

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

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

未注明的返回值

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

未记录的参数

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

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

无此类参数

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

未知宏

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

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

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

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

没有为 <实体> 生成输出，因为 <父类> 未被记录

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

如果文档化的成员属于不打算文档化的类，则将该类标记为 \internal或使用 \dontdocument命令。

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> 已记录超过一次

此警告表示文档集包含两个注释，其中包含 \namespace命令的两条注释。

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

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

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

另请参阅依赖和索引。

没有\inmodule 命令

如果 QDoc 注释没有将类、命名空间或头文件与带有 \inmodule命令将类、名称空间或头文件与模块联系起来，QDoc 将发出此警告。

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

无法在任何头文件中找到用 < 命令> 指定的 < 名称

这意味着 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

未注明的属性 '<name>'

此警告表明一个 C++ 类的Q_PROPERTY 声明缺少文档。属性是类的公共 API 的一部分，需要使用\property 命令来描述其目的、有效值和行为。

多次记录 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 将产生此警告。出现这种情况的原因可能是所编写的覆盖方法更改了签名，或不再是虚拟方法。

非法\reimp ；没有为 <command> 编写的虚函数文档

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);

<class> 尝试继承自身

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

例如

\qmltype Foo
\inherits Foo

\nativetype 只允许在\qmltype

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

一个组中的所有属性必须属于同一类型：<名称

记录 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 样式定义

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

触发此警告的配置示例：

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

未知命令 <名称

当 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文件> 中找到了片段 <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或 \row的 \table.
• 和 \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 发现一个 \value指令时，QDoc 会发出此警告。 \enum注释中的指令时，QDoc 会发出此警告，该指令命名的值在声明枚举类型文档的头文件中找不到。

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

<enum list> 的 \value或 \omitvalue条目中没有包含头文件中<enum list> 声明中命名的 <enum> 条目。

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

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

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

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

\generatelist <group> 为空

下面简要介绍了 \generatelist:

• \generatelist 注释示例
• \generatelist 注释属性
• \generatelist classes <前缀
• \generatelist classesbymodule <模块名> (前缀)
• \generatelist qmltypesbymodule <模块名
• \generatelist 函数索引
• \generatelist 法律条文
• \generatelist 概述
• \generatelist 属性
• \generatelist 相关

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

\generatelist <组> 无此组

如果 \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 命令替换为\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> 。

类型是它自己的基础类型：<type>（类型

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

循环类型继承：<type

当一个 QML 类型继承自一个基础类型，而这个基础类型又继承自原始类型时，就会发生循环或循环继承。这可能发生在两个相互继承的类型之间，也可能在它们之间有中间类型。

此警告表示已检测到继承层次中的循环。您应该检查 \inherits命令，并跟踪基类型，直到找到一个从以前遇到过的类型继承的类型。然后，您应通过修正错误的 \inherits命令，从而打破循环。

\sa <name> 命令中指向 self 的多余链接

一个文档在其命令中定义的引用中包含指向自身的链接。 \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)

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

未找到声明为 QML 类型的基本类型的类型名，或者它没有用 \inherits命令声明的。

未识别的标记语言

当为\code 命令指定了 QDoc 无法识别的编程语言时，就会出现此警告。例如，此 QML 代码块使用了无效的 "QL "语言：

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