Проблема
После обновления с 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 ()
[protected] void Foo :: moo ()
- Плохой результат (с
Q_OBJECT)
Раскомментирование макроса Q_OBJECT и запуск qdoc.exe снова приводит к следующему результату:
Содержание
Класс Foo
Подробное описание
ВАЖНО: Foo, moo и boo ушли.