Почему Q_OBJECT ломает QDoc?

Question

проблема

После обновления с Qt 5.10 до Qt 5.11 у меня начались проблемы с созданием документации с QDoc для моих существующих проектов.

Одной из многих проблем является отсутствие функций в документации, хотя соответствующие комментарии существуют в исходном коде.

Исследование

Мне удалось сузить вопрос до включения Q_OBJECT макрос, как показано в приведенном примере кода (см. ниже).

Это действительно упоминается в документации Qt:

Если не указано Cpp.ignoretokens или же Cpp.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
 */

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

void boo ()

Защищенные функции

void moo()

Подробное описание

Документация по функциям

Foo::Foo()

По умолчанию создается экземпляр Foo.

void Foo:: boo ()

[защищено] void Foo::moo()

• Плохой результат (с Q_OBJECT)

Раскомментировать Q_OBJECT макрос и бег qdoc.exe снова дает следующий результат:

• Foo

содержание

• Подробное описание

Фу класс

Подробное описание

ВАЖНЫЙ: Foo, moo а также boo пропали.

Answer 1

Единственное решение, которое я придумал, - это добавить следующие директивы препроцессора в Q_OBJECT макрос:

#ifndef Q_QDOC
    Q_OBJECT
#endif //Q_QDOC

Q_QDOC определяется во включенном qt-cpp-defines.qdocconf, так QDoc макрос пропускается, но он не определен в системе сборки, и код компилируется как обычно.

Answer 2

Я знаю, что этому вопросу уже несколько лет, но я хотел опубликовать ответ для будущих поисковиков, которые его найдут. У меня была эта проблема для макросов Q_OBJECT и Q_INVOKABLE в моем файле.cpp.

Решение состоит в том, чтобы использовать недокументированную команду в вашем файле.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, если это необходимо для вашего qmake команда)

Изменить: для меня $QT_INSTALL_HEADERS знак равно C:/Qt/5.12.9/msvc2017_64/include

Изменить 2: убедитесь, что в вашей системе установлен clang (через chocolately, homebrew, apt или другие), и если в окнах, которые вы запускаете set LLVM_INSTALL_DIR=C:\Program Files\LLVMперед запуском qdoc - Инструкции здесь: Установка Clang для QDoc