为什么 Q_OBJECT 会破坏 QDoc？

Question

问题

自从从 Qt 5.10 升级到 Qt 5.11 以来，我开始遇到使用QDoc为现有项目生成文档的问题。

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

研究

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

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

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

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

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

在任何情况下，我qt-cpp-defines.qdocconf在我的qdocconf文件中包含qt-cpp-defines.qdocconf 。

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

Cpp.ignoredirectives += Q_OBJECT

但结果是一样的。

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

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

最小的例子

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

foo.h

#include <QObject>

class Foo : public QObject
{
//  Q_OBJECT // <-- uncomment this to break QDoc
public:
    Foo() {}

    void boo() {}

protected:
    void moo() {}
};

文件

#include "Foo.h"

/*!
    \class Foo
 */

测试.qdocconf

include($QT_INSTALL_DOCS/global/compat.qdocconf)
include($QT_INSTALL_DOCS/global/fileextensions.qdocconf)
include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf)
include($QT_INSTALL_DOCS/global/macros.qdocconf)

# Uncoment this for a test
# Cpp.ignoredirectives += Q_OBJECT

outputdir   = html
headerdirs  = .
sourcedirs  = .
exampledirs = .
imagedirs   = ./images

结果

• 好结果（没有Q_OBJECT ）

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

• 富

内容

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

Foo类

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

公共职能

富()

无效的嘘（）

受保护的功能

void moo()

详细说明

成员函数文档

Foo::Foo()

默认构造一个 Foo 的实例。

void Foo::boo()

[受保护] void Foo::moo()

• 糟糕的结果（带有Q_OBJECT ）

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

• 富

内容

• 详细说明

Foo类

详细说明

重要提示： Foo 、 moo和boo都消失了。

Answer 1

我知道这个问题已经有几年了，但我想为未来找到这个问题的搜索者发布一个答案。 我的 .cpp 文件中的 Q_OBJECT 和 Q_INVOKABLE 宏都有这个问题。

解决方案是在 .qdocconf 文件中使用未记录的命令includepaths ，或者在运行qdoc时将-I参数传递给命令。

我将只展示如何使用我的 config.qdocconf 文件

...
# undocumented feature that simulates passing -I parameters to the command line
includepaths = . \
           .. \
           $QT_INSTALL_HEADERS \
           $QT_INSTALL_HEADERS/QtCore \
           $QT_INSTALL_HEADERS/QtGui \
           $QT_INSTALL_HEADERS/QtQuick \
           $QT_INSTALL_DOCS
...

如果需要，您还可以使用绝对路径而不是$QT_INSTALL_HEADERS 。

查看这些特殊变量指向何处的一种简单方法是运行qmake -query （如果qmake命令需要，请使用 qt install bin 的绝对路径）

编辑：对我来说， $QT_INSTALL_HEADERS = C:/Qt/5.12.9/msvc2017_64/include

编辑 2：确保您的系统上安装了 clang（通过Chocolately 、 homebrew 、 apt 或其他），如果在运行set LLVM_INSTALL_DIR=C:\\Program Files\\LLVM之前在 Windows 上运行set LLVM_INSTALL_DIR=C:\\Program Files\\LLVM - 此处的说明：安装 Clang用于 QDoc

Answer 2

我想出的唯一解决方案是将以下预处理器指令添加到Q_OBJECT宏：

#ifndef Q_QDOC
    Q_OBJECT
#endif //Q_QDOC

Q_QDOC在包含的qt-cpp-defines.qdocconf ，所以QDoc跳过宏，但它没有在构建系统中定义，代码像往常一样编译。