问题

Question

问题

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

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

研究

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

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

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

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

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

无论如何，我都会在qdocconf文件中包含qt-cpp-defines.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


内容


公共职能

受保护的功能

详细说明


Foo Class


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


公共职能

Foo（）

void boo（）

受保护的功能

void moo（）

详细说明

成员功能文档

Foo :: Foo（）

Default构造Foo的实例。

void Foo :: boo（）

[受保护的] void Foo :: moo（）

错误的结果（带有Q_OBJECT）

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

Foo


内容


详细说明


Foo Class

详细说明

重要提示：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（如果qmake命令需要，请使用qt安装箱的绝对路径）

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

编辑2：在运行qdoc之前，请确保已在系统上安装了clang（通过chocolately，homebrew，apt或其他语言），以及是否在运行set LLVM_INSTALL_DIR=C:\Program Files\LLVM的窗口上安装了clang -此处的说明：Installing Clang for QDoc

Answer 2

我想到的唯一解决方案是将以下预处理程序指令添加到PASS test/sum.js ----------|----------|----------|----------|----------|-------------------| File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s | ----------|----------|----------|----------|----------|-------------------| All files | Unknown | Unknown | Unknown | Unknown | | ----------|----------|----------|----------|----------|-------------------| Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total Time: 1.125s Ran all test suites matching /.\/test\/sum.js/i.宏中：

Q_OBJECT

#ifndef Q_QDOC Q_OBJECT #endif //Q_QDOC是在包含的Q_QDOC中定义的，因此qt-cpp-defines.qdocconf会跳过该宏，但是它没有在构建系统中定义，因此代码照常编译。

为什么Q_OBJECT破坏QDoc？

问题

研究

最小示例

结果

Foo Class

Foo Class

2 个答案: