为什么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文件中。

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

Cpp.ignoredirectives += Q_OBJECT

但结果是一样的。

我体验Windows 10和Ubuntu 17下所描述的问题在Windows 7下我无法执行qdoc.exe在所有。

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

最小的例子

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

oo

#include <QObject>

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

    void boo() {}

protected:
    void moo() {}
};

Foo.cpp

#include "Foo.h"

/*!
    \class Foo
 */

test.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我或多或少会得到以下内容：

• oo

内容

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

富班

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

公共职能

Foo（）

无效的boo（）

受保护的功能

无效的moo（）

详细说明

会员功能文档

Foo :: Foo（）

默认构造一个Foo的实例。

无效Foo :: boo（）

[保护] void Foo :: moo（）

• 不良结果（带有Q_OBJECT）

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

• oo

内容

• 详细说明

富班

详细说明

重要提示： Foo，moo并且boo都不见了。

Answer 1

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

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

我只会展示如何让它与我的 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（如果命令需要，请使用 qt 安装箱的绝对路径qmake）

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

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