7

问题

自从从 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到忽略列表

Cpp.ignoredirectives += Q_OBJECT

但结果是一样的。

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

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
 */

测试.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 类

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

公共职能

富（）

无效嘘（）

受保护的功能

无效哞（）

详细说明

成员函数文档

富::富()

Default 构造一个 Foo 的实例。

无效 Foo::boo()

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

  • 坏结果（带Q_OBJECT）

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

  • 富

内容

  • 详细说明

Foo 类

详细说明

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

4

2 回答 2

3

我知道这个问题已经有几年了，但我想为将来找到这个问题的搜索者发布一个答案。我的 .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 install bin 的绝对路径）qmake

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

编辑 2：确保您的系统上安装了 clang（通过巧克力、自制软件、apt 或其他方式），如果在set LLVM_INSTALL_DIR=C:\Program Files\LLVM运行 qdoc 之前运行的 Windows 上 - 此处的说明：为 QDoc 安装 Clang

于 2020-09-11T17:18:22.823 回答
0

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

#ifndef Q_QDOC
    Q_OBJECT
#endif //Q_QDOC

Q_QDOC在 include 中定义qt-cpp-defines.qdocconf，因此QDoc跳过宏，但它没有在构建系统中定义，代码照常编译。

于 2018-11-03T16:36:19.243 回答