文档类别

如何解决 QDoc 警告

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

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

在源代码中搜索特定的链接目标。如果没有结果，逐渐减少搜索的特定性，直到找到匹配项。

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

  • 在文档中使用的名称（对于函数，在指定的情况下，签名）与其声明中使用的名称不匹配。
  • 链接目标在链接文本中没有标记为 \内部 时被标记为内部。

在表格项外部找到 \target 命令

如果 QDoc 遇到一个 \target 命令，它不在 \table ... \endtable 区块内的 \li 命令之前，它会发出此警告。警告后面跟着文本 将 \target 移到 \li 以解决问题。

找不到引用的片段文件

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

纠正此问题的有用步骤

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

意外的 \snippet

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

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

当 QDoc 无法根据传递给 \inqmlmodule 或与 QML type 相关的 \qmlproperty 命令的标识符找到 QML 模块时，会发出此警告。

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

在 QML <module> 中未找到此类 <type>

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

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

未记录的返回值

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

未记录的参数

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

参数不存在

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

未知宏

当 QDoc 看到一个反斜杠，\，后面跟着它不认识作为内置命令或 用户定义宏 名称的标记时，将发出此警告。在引用包含字符转义序列的代码时，应将代码包围在 \c{...} 中，以防止对此转义序列发出警告。

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

当 Clang 解析一个在 \fn 后面的函数声明时，它会与头文件中的声明进行检查。如果 Clang 发现不符，它会发出此警告消息。

C++ 类 <ClassName> 未找到：\instantiates <ClassName>

如果您描述一个 QML 类型，您可以指定它实例化的类。请参阅 \instantiates 命令，位于 QDoc 指南 中。

当 QDoc 无法找到 C++ 类 <ClassName> 的文档时，会发出此警告。要么该类没有文档，要么它被标记为 \internal，或者它来自另一个文档模块，而 QDoc 没有找到对应依赖项的索引文件。

另请参阅 depends。

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

QDoc发现了一个无主题命令的<！– ... –>注释，这不是直接跟在类、函数或属性定义后面。因此，它不知道这个注释文档了什么。

这个qdoc注释包含没有主题命令（例如，模块、页）

如果一个QDoc注释不包含主题命令，QDoc不知道这个注释文档了什么，并发出此警告。这与无法将此文档与任何内容关联非常相似，但特定于不在C ++或QML文件中的注释。

<名称> 已多次文档化

当QDoc发现两个注释记录了同一项目时，QDoc会发出此警告。警告详细信息提供了之前看到的注释的位置。

例如，当您看到一个函数的定义之前有文档注释，并且在一个不同的地方有单独的\fn注释时，您将看到此警告。

命名空间 <名称> 已多次文档化

此警告意味着文档集中包含两个注释，包含相同的\namespace命令参数，<名称>。

<名称> 已文档化，但命名空间 <命名空间> 在任何模块中都没有文档化

找不到文档 <名称>，但是<名称>是在一个命名空间中声明的，该命名空间未记录或QDoc无法找到其文档。

可以通过记录<命名空间>来解决此问题，或者如果它在另一个模块中已记录，请确保此模块具有对其的依赖关系。

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

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

在解析\fn语句时，Clang将此与头文件中的函数声明进行比较。如果有差异，Clang会发出此警告。

没有\inmodule命令

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

如果QDoc注释描述的实体不是某些其他实体的成员（通常是命名空间或类），它应该使用\relates或\inmodule来将其与其更广泛的环境关联起来。如果没有这样做，将引发此警告。

在任何头文件中找不到使用\<command>指定名称的 <name>

这意味着QDoc无法在任何头文件中找不到名称的声明，但找到了声称对其进行文档化的注释。

示例

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/component qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler 没有名为 DragAxis 的属性。

<name> 缺少属性类型

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

\qmlproperty 命令期望后面跟属性类型，然后是完全限定的属性名（即归一化名称 :: 连接在所属类名之后）。

错误

\qmlproperty MyWidget::count

正确

\qmlproperty int MyWidget::count

QML 属性被多次记录：<identifier>

当 QDoc 在 QDoc 注释中发现两个注释记录了相同的 QML 属性，无论它出现在定义之前还是使用 \qmlproperty 命令时，它使用此警告。该属性。

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

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

当使用 \reimp 记录方法并作为重写虚拟方法时，遇到基类中没有给定名称和签名的虚拟方法的情况，QDoc 会生成此警告。这可能是因为要重写的方法已更改其签名，或不再为虚拟。

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

Qdoc 会尝试创建一个链接到实现此函数的函数，但无法找到链接目标，可能是该函数未记录。这也可能是因为没有基类具有此名称和签名的虚拟方法；这可能是由于重命名引起的，或签名发生变化或基类不再声明它为虚拟。

<class> 尝试继承自己

当使用 inherits 命令来记录 QMl 类型继承其他 QML 类型时，会发出此警告。如果该其他 QML 类型与记录的 QML 类型相同，则会发出此警告。

示例

\qmltype Foo
\inherits Foo

\instantiates 仅允许在 \qmltype 中使用

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

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

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

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

在示例的源目录中，QDoc 预期找到一个名为 CMakeLists.txt 的项目文件，或者一个具有 .pro、.qmlproject 或 .pyproject 扩展名的文件，其基本名称与示例目录匹配。例如，examples/mymodule/helloworld/helloworld.pro。

无法打开文件引用：<filename>

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

QDoc 无法在命令（如 \quotefromfile、\snippet、\include）中找到文件名，这些命令指示它从命名的文件检索内容。它会搜索搜索路径中命名的每个目录。如果这些目录中没有同名文件，或者文件存在但不能读取，QDoc 会发布此警告。请确保搜索路径与 <filename> 的组合拼写正确，并且您有文件的读取权限。

注意：<filename> 可能包含目录名前缀；整个 <filename> 将附加到搜索路径中的每个目录。

在 \raw 后缺少格式名称

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

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

指定输出格式的宏不能有通用定义。

触发此警告的配置示例

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

未知命令 <name>

当 QDoc 注释使用一个反斜杠后跟一个既不是 QDoc 内置命令也未定义为自定义命令（宏）的标记时，QDoc 会发布此警告。请检查命令名称的拼写，并检查您的 QDoc 配置是否不包括可能定义它的任何内容，如果它是自定义命令。

这还可能是因为在 QDoc 注释中引用了代码，例如，作者可能引用了 C 字符串终止字符 '\0' 或其他 C 字符串转义序列，如 '\n' 而未对反斜杠进行转义。将反斜杠作为 \ 转义以在文档中包含实际的反斜杠，或使用 \c{...} 将代码片段括起来，这会抑制将反斜杠解释为引入 QDoc 命令的解析。

重复的目标名称 <target>

如果您使用

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

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

注意：<filename> 可能包含目录名前缀；整个 <filename> 将附加到搜索路径中的每个目录。

在<file>中找不到<tag>

这意味着QDoc无法在<file>的<更强的><include>或{片段命令}<file>中找到标识符<id>。

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

在<file>中找到了&ldot;片段命令&ldot;的&ldot;标签&ldot;，但它为空。

<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警告“在‘\table’中不能使用‘\list’”。

<outer>之前缺少<inner>

一些例子

  • 只有在使用&ldot;列表命令&ldot;或&ldot;表&ldot;的&ldot;行&ldot;时，才能使用&ldots;li命令。
  • 只能在&ldot;表&ldot;中使用&ldots;行&ldots;和&ldots;标题&ldots;命令。

不期待的<end_command>启发式

如果在某些情况下，例如，您有一个没有先行&ldot;列表命令&ldot;的&ldot;结束列表&ldot;。它适用于所有成对出现的命令（例如，startFoo/endFoo）。

\sa中缺少逗号

&ldot;\sa命令&ldot;中列出的标题应使用逗号隔开。

<command>宏没有默认定义

QDoc试图展开一个宏，并期望该宏具有默认定义。一些宏可能只有格式特定的定义。

示例

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

然而，有时宏扩展需要一个格式无关的宏。例如，您可以在部分标题中使用宏，但它们必须具有默认定义。

使用太少的参数激活&ldot;<macro>&ldot;（预期&ldots;<many>，但得到&ldots;<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指令时，会发出此警告。

在\enum列表中未找到文档化的枚举项 <enum>

\value或\omitvalue条目未包含在头文件中命名的<enum>，它在头文件中<enum list>的声明中指定。

未找到索引：<filename>

示例

Failed to find index: path/to/QtCrator/appmanplugin/manual.index

在这种情况下，这显然意味着indexes变量中的索引文件路径存在拼写错误。

错误

indexes += path/to/QtCrator/appmanplugin/manual.index

正确

indexes += path/to/QtCreator/appmanplugin/manual.index

\generatelist <group>是空的

以下是\generatelist所有可能参数的简要概述

  • \generatelist annotatedexamples
  • \generatelist annotatedattributions
  • \generatelist classes <prefix>
  • \generatelist classesbymodule <module name>
  • \generatelist qmltypesbymodule <module name>
  • \generatelist functionindex
  • \generatelist legalese
  • \generatelist overviews
  • \generatelist attributions
  • \generatelist related

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

\generatelist <group> no such group

此警告会在\generatelist的参数是非存在的组时发出。

示例

\generatelist draganddrop

此语句生成拖放到拖放组中的类或QML类型的列表。类或QML类型通过它们的<class>或<qmltype>注释中的\l {ingroup-command}{\ingroup} 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
  \instantiates QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

正确

\qmltype ItemSelectionModel
\instantiates 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无法定位由 'depends' 配置变量定义的任何依赖项的索引文件。

覆盖了之前的文档

当QDoc发现两个注释看起来似乎描述了同一个实体时，它会发出此警告。警告细节中提供了先前看到的注释的位置。

未识别的列表样式 <name>

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

无法解析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 来抑制此警告。

示例

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

在这种情况下，警告意味着 \snippet 命令未能找到第二个标签 "mAh [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.]

注意： 由于过长的内容未完全解析，QDoc 可能会发出误报警告。在修复其他警告之前，解决此类警告的所有警告。

在全局范围内未为函数 <name> 生成文档

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

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

<project> 的文档配置没有定义帮助项目（qhp)

预期使用有效的 Qt 帮助配置，但该项目的 .qdocconf 文件中未提供。

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

已为此项目生成 FILE

在生成项目文档时，QDoc 会跟踪其生成的文件的文件名。如果 QDoc 在当前执行中已知已生成该文件，则在尝试打开文件进行写入时，QDoc 将发出警告。这可能会发生，如果在 \qdoccmd 页面命令中使用与 \qdoccmd 组相同的名称时。

您可以将环境变量 QDOC_ALL_OVERWRITES_ARE_WARNINGS 设置为无条件地警告此类事件。这在追踪有问题的定义时可能很有用。

另请参阅 无法找到 qdoc 包含文件 <filename> 和 无法打开用于引用的文件：<filename>。

文档类别

© 2024 The Qt Company Ltd. 本文档中包含的贡献文档归各自所有者版权所有。本提供文档受Free Software Foundation发布的GNU自由文档许可证版本1.3条款许可。Qt及其相关标志是The Qt Company Ltd.在芬兰和/或其他国家的商标。所有其他商标均属于其各自所有者。