c++ - 为什么 Q_OBJECT 会破坏 QDoc？

Question

问题

自从从 Qt 5.10 升级到 Qt 5.11 后，我开始无法生成带有 QDoc 的文档。对于我现有的项目。

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

研究

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

Qt documentation中确实提到了这一点:

If not specified by the Cpp.ignoretokens or Cpp.ignoredirectives variables, non-standard constructs (typically macros) can result in erroneous documentation.

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

The Q_OBJECT macro, however, is an exception: QDoc recognizes this particular non-standard construct, so there is no need specifying it using the Cpp.ignoredirectives variable.

无论如何我都会包含qt-cpp-defines.qdocconf在我的 qdocconf 文件中。

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

Cpp.ignoredirectives += Q_OBJECT

但结果是一样的。

我在 Windows 10 和 Ubuntu 17 下遇到了上述问题。Under Windows 7 I cannot execute qdoc.exe at all .

解决此问题的 qdocconf 的正确配置是什么？

最小示例

为了快速重现(在真实情况下，声明和实现是分开的，并添加了适当的注释)，请考虑以下设置:

Foo.h

#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 我或多或少得到以下信息:

• Foo

Contents

• Public Functions
• Protected Functions
• Detailed Description

Foo Class

• List of all members, including inherited members

Public Functions

Foo()

void boo()

Protected Functions

void moo()

Detailed Description

Member Function Documentation

Foo::Foo()

Default constructs an instance of Foo.

void Foo::boo()

[protected] void Foo::moo()

• 错误的结果(Q_OBJECT)

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

• Foo

Contents

• Detailed Description

Foo Class

Detailed Description

重要提示:Foo、moo 和boo 都不见了。

Answer 1

我知道这个问题已经有几年了，但我想为找到这个问题的 future 搜索者发布一个答案。我的 .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 (如果您的 qmake 命令需要，请使用您的 qt 安装 bin 的绝对路径)

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

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