QML/qdoc: Как определить наследование и важный оператор для моих компонентов qml?

Question

Я пишу документацию для своего проекта QML с помощью QDoc. Пока что могу сделать простой с описанием моих функций / сигналов / свойств. Теперь я хотел бы определить наследование и важные операторы, как в документе Qt (см. Ниже).

• Согласно документации Qt, наследование определяется командой \ inherits. Однако я не вижу никакого результата, когда хочу наследовать свои объекты от Item, и у меня нет никаких предупреждений / ошибок при запуске qdoc.

• Согласно Qt wiki, QDoc считает версию, указанную в команде, оператором импорта. Следуя примеру, я попытался определить свой собственный оператор импорта, поскольку мои файлы qml будут доступны только с определенным импортом (скажем, здесь MyLib 2.0). Как и наследование, qdoc, похоже, не понимает, потому что у меня следующий результат:

Есть идеи, что я пропустил? Ниже вы можете найти простой пример того, что у меня есть (файл css очень простой, поэтому я не думаю, что уместно его показывать).

Моя среда:

• Qt 5.10.10 с msvc2015
• LLVM 9.0.0 (для qdoc)

config.qdocconf

sourcedirs = .
headerdirs = .
imagedirs = .

sources.fileextensions = "*.qml"


outputdir  =    ./doc/
outputformats = HTML

HTML.stylesheets = style.css
HTML.headerstyles = "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style.css\"/>\n"

CustomItem.qml

import QtQuick 2.10;

/*!
    MyLib 2.0    //!  What should I write to get the import statement?

   \qmltype CustomItem
   \inherits Item //! What should I write to get the "Inherits"?


   \brief A simple example of object that inherits of Item.

   I can safely assume that the properties and signals work well.
*/

Item {
    id: customItem;

    /*!
        prop1 description
    */
    property color prop1;

    /*!
        prop2 description
    */
    property int prop2: 6;
}

Спасибо за помощь!

Answer 1

Для того чтобы \inheritsдля работы тип, который он наследует, должен быть определен где-нибудь, чтобы QDoc мог найти. Поскольку это тип, предоставляемый Qt, ваш файл должен зависеть от модуля, который предоставляет документацию для Item.

Вы можете сделать это, добавив следующие строки в свой .qdocconf файл.

      depends += \
    qtquick

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

Соответствующий раздел:

Переменная зависимостей определяет список других проектов документации, от которых зависит этот проект для разрешения целевых объектов ссылок для наследования типов и всего остального, на что документация должна ссылаться.

Но вам также необходимо указать QDoc, где находятся индексные файлы для этих зависимостей.

При вызове QDoc в проекте, который имеет зависимости и использует зависимую переменную, один или несколько путей -indexdir должны быть переданы в качестве параметров командной строки. QDoc использует эти пути для поиска файлов индекса зависимостей.

      qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS

С указанным выше QDoc будет искать файл $QT_INSTALL_DOCS / qtquick / qtquick.index для зависимости от qtquick. Если индексный файл для зависимости не найден, QDoc выдаст предупреждение.

Это означает, что вам нужно собрать документацию Qt и передать расположение установленной документации в qdoc

Ссылка на сборку документации Qt

Как только вы это сделаете, используя \inherits Item должен предоставить следующую строку в созданной вами документации.

Наследует: Item

Answer 2

Я думаю, вам нужно настроить модуль QML, используя \inqmlmodule свойство и файл module.qdocconf.

Пример для qdocconf:

/*!
    \qmlmodule MyLib 2.0
    \title MyLib 2.0 QML types

    MyLib is a collection of types ... 

    ...
*/

В вашем файле типа QML:

import QtQuick 2.10;

/*!
   \qmltype CustomItem
   \inherits Item
   \inqmlmodule MyLib
 ...
*/

Item {
 ...
}

Для наследования вы можете префикс типа с его модулем:

\inherits QtQuick::Item

Если ваш тип определен в классе C++, также добавьте \instanciates свойство:

\instanciates MyType 

Полный пример:

/*!
    \qmltype CustomType
    \inqmlmodule MyLib
    \inherits QtQuick::Item
    \brief Provides a custom item type.

    CustomType provides a component for use as ...
*/