为什么 Q_OBJECT 会破坏 QDoc？

Question

Problem

Since the upgrade from Qt 5.10 to Qt 5.11 I have started having problems to generate a documentation with QDoc for my existing projects.

One of the many issues are missing functions in the documentation, although the corresponding comments exist in the source code.

Research

I have managed to narrow the issue down to the inclusion of the Q_OBJECT macro, as shown by the provided code example (see below).

This is indeed mentioned in the 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 is not supposed to cause problems though, because just a little bit further it is written:

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.

In any case I do include qt-cpp-defines.qdocconf in my qdocconf file.

I have also tried to manually add Q_OBJECT to the ignore list

Cpp.ignoredirectives += Q_OBJECT

but the result is the same.

I experience the described issue under Windows 10 and Ubuntu 17. Under Windows 7 I cannot execute qdoc.exe at all .

What is the correct configuration of qdocconf to overcome this issue?

Minimal example

For a quick reproduction (in the real situation the declarations and the implementations are split and proper comments are added), please consider the following setup:

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

Results

• Good result (without Q_OBJECT )

Executing qdoc.exe test.qdocconf I get more or less the following:

• 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()

• Bad result (with Q_OBJECT )

Uncommenting the Q_OBJECT macro and running qdoc.exe again yelds the following result:

• Foo

Contents

• Detailed Description

Foo Class

Detailed Description

IMPORTANT: Foo , moo and boo are gone.

Answer 1

I know this question is a few years old already but I wanted to post an answer for future searchers that find this. I had this issue for both Q_OBJECT and Q_INVOKABLE macros in my .cpp file.

The solution is either to use an undocumented command in your .qdocconf file, includepaths , or to pass -I parameters to your command when you run qdoc .

I will only show how I got it working with my config.qdocconf file

...
# 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
...

You can also use absolute paths instead of $QT_INSTALL_HEADERS if needed.

An easy way to see where those special variables point to is to run qmake -query (use an absolute path to your qt install bin if needed for your qmake command)

Edit: For me, the $QT_INSTALL_HEADERS = C:/Qt/5.12.9/msvc2017_64/include

Edit 2: make sure you have clang installed on your system (via chocolately , homebrew , apt, or others) and if on windows that you run set LLVM_INSTALL_DIR=C:\\Program Files\\LLVM before you run qdoc - Instructions here: Installing Clang for QDoc

Answer 2

The only solution I came up with is to add the following preprocessor directives to the Q_OBJECT macro:

#ifndef Q_QDOC
    Q_OBJECT
#endif //Q_QDOC

Q_QDOC is defined in the included qt-cpp-defines.qdocconf , so QDoc skips the macro, but it is not defined within the build system and the code compiles as usual.