问题
自从从 Qt 5.10 升级到 Qt 5.11 后,我开始无法生成带有 QDoc 的文档。对于我现有的项目。
许多问题之一是文档中缺少函数,尽管源代码中存在相应的注释。
研究
我已设法将问题缩小到包含 Q_OBJECT
宏,如提供的代码示例所示(见下文)。
Qt documentation中确实提到了这一点:
If not specified by the
Cpp.ignoretokens
orCpp.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 theCpp.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
都不见了。
最佳答案
我知道这个问题已经有几年了,但我想为找到这个问题的 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
关于c++ - 为什么 Q_OBJECT 会破坏 QDoc?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/52739030/