What is the meaning of the //! [n] (n = 0, 1, 2 ...) markup in the C++/QML sources in the Qt sample projects?

For example:

QDoc 是否真的支持 DITAXML 文档？我能够创建 HTML 文档，但使用 DITAXML 会导致此错误。

在 .qdocconf 文件的以下行

我在这里看到官方文档提到它实际上是受支持的，但我无法创建 xml 文档。有没有人真正生成过 XML 文档？

一切都是有问题的，我在项目中提供了一个简单的 qdocconf 文件，但是当 qdocconf 位于项目的 files 属性中时，qbs 不会调用 qdoc。

项目.qbs

config.qdocconf：

项目目录层次结构：

PS：project.installInclude 是来自更高项目文件的开关集。

例如，我有两个函数 A 和 B，例如：

在函数声明前输入/**并按enter：

这是一个BUG吗？

操作系统：Windows 7 QtCreator 版本：3.1.2 和 4.3.1

好像我只是找不到 QDoc 可执行文件。

我下载了 Qt 5.11.1。

我需要单独下载 QDoc 吗？

我检查了文档，但它只说：要从命令行运行 qdoc，请为其指定配置文件的名称： $ ../../bin/qdoc ./config.qdocconf

这对查找文件本身没有多大帮助。

我最近搬到了 Qt 5.11.2。

当我尝试qdoc.exe从 Qt Creator 作为外部工具运行时：

具有以下论点：

在 General Message 面板中报告程序已执行并已结束。没有错误，但没有生成文档。

当我尝试qdoc.exe从命令提示符运行时，出现以下错误：

程序无法启动，因为您的计算机中缺少 api-ms-win-core-sysinfo-l1-2-0.dll。尝试重新安装程序以解决此问题。

我已经搜索了整个系统api-ms-win-core-sysinfo-l1-2-0.dll，它确实丢失了。

我从 Window 10 安装中获取了 dll，并将其放在与可执行文件相同的文件夹中。结果是一样的。

如何解决？

问题

自从从 Qt 5.10 升级到 Qt 5.11 后，我开始在为现有项目生成带有QDoc的文档时遇到问题。

尽管源代码中存在相应的注释，但文档中缺少功能是众多问题之一。

研究

我已设法将问题缩小到包含Q_OBJECT宏，如提供的代码示例所示（见下文）。

Qt 文档中确实提到了这一点：

如果没有由Cpp.ignoretokensorCpp.ignoredirectives变量指定，非标准构造（通常是宏）可能会导致错误的文档。

Q_OBJECT不过不应该引起问题，因为它写得更远一点：

然而Q_OBJECT，宏是一个例外：QDoc 识别这种特殊的非标准构造，因此无需使用Cpp.ignoredirectives变量指定它。

无论如何，我确实包含qt-cpp-defines.qdocconf在我的qdocconf文件中。

我也尝试手动添加Q_OBJECT到忽略列表

但结果是一样的。

我在 Windows 10 和 Ubuntu 17 下遇到了所描述的问题。在 Windows 7 下我根本无法执行qdoc.exe。

qdocconf克服这个问题的正确配置是什么？

最小的例子

为了快速复制（在实际情况下，声明和实现被拆分并添加了适当的注释），请考虑以下设置：

Foo.h

Foo.cpp

测试.qdocconf

结果

• 好结果（没有Q_OBJECT）

执行qdoc.exe test.qdocconf我或多或少得到以下信息：

• 富

内容

• 公共职能
• 受保护的功能
• 详细说明

Foo 类

• 所有成员的列表，包括继承的成员

公共职能

富（）

无效嘘（）

受保护的功能

无效哞（）

详细说明

成员函数文档

富::富()

Default 构造一个 Foo 的实例。

无效 Foo::boo()

[受保护] 无效 Foo::moo()

• 坏结果（带Q_OBJECT）

取消注释Q_OBJECT宏并qdoc.exe再次运行会产生以下结果：

• 富

内容

• 详细说明

Foo 类

详细说明

重要提示： Foo，moo并且boo消失了。

我在另一个模板类中有以下嵌套模板类：

operator==嵌套类型的非成员的签名是什么B？以下天真的尝试不起作用：

Clang、GCC 和 MSVC 给出了各种不同的错误和/或提示出了什么问题，例如缺少template关键字，但我没有尝试解决它。

请注意，这显然有效：

但是，我需要非成员声明的原因是使用 qdoc 记录它。qdoc 使用 clang 来解析源代码，它要求我提供operator==我已经实际实现的声明，就像刚才显示的那样。

现场演示

我想用 QDoc 生成文档，并按照 QDoc 指南的说明进行了尝试。我可以获得文档，但它并不完整。

我都试过了：

• qt 5.11.3，llvm 6.0.1，Windows 10
• qt 5.12.3、llvm 6.0.1、ubuntu 16.04

但都是一样的。

这是代码：

项目.qconconf

主窗口.cpp

在我执行命令“qdoc proect.qdocconf”后，警告如下：

.../mainwindow.cpp:4: (qdoc) 警告：MainWindow 类没有 \inmodule 命令；默认使用项目名称：
.../mainwindow.cpp:9: (qdoc) 警告：无法将此文档绑定到任何内容 [我找到了 /*！... */ 评论，但评论中没有主题命令（例如，'\fn'，'\page'），并且评论后没有函数定义。]

我有两个文件：“.index”和“mainwindow.html”

“主窗口.html”：

MainWindow
内容
详细说明
MainWindow 类
主窗口，用于ui 界面。

更多的...

详细说明
ui 界面的主窗口。

似乎它无法获取除“\class”之外的任何其他信息。

有谁知道什么可能导致无法生成文档？

我正在使用 QDoc 为我的 QML 项目编写文档。到目前为止，我可以用我的功能/信号/属性的描述来制作一个简单的。现在，我想定义 Qt 文档中的继承和重要语句（见下文）。

• 根据Qt 文档，继承是用\inherits命令定义的。但是，当我想让我的对象从Item继承并且运行 qdoc 时没有任何警告/错误时，我看不到任何结果。

• 根据Qt wiki，QDoc 将命令中指定的版本视为导入语句。按照该示例，我尝试定义自己的导入语句，因为我的 qml 文件仅可用于特定的导入（假设此处为MyLib 2.0）。和继承一样，qdoc好像没看懂，因为我有以下结果：

知道我错过了什么吗？您可以在下面找到我所拥有的一个简单示例（css 文件非常简单，因此我认为展示它无关紧要）。

我的环境：

• 带有 msvc2015 的 Qt 5.10.10
• LLVM 9.0.0（用于 qdoc）

config.qdocconf

CustomItem.qml

谢谢您的帮助 ！