QML/qdoc : How to define inheritance and important statement for my qml components?

Question

I am writting a documentation for my QML project with QDoc. So far, I am able to make a simple one with a description of my functions/signals/properties. Now, I would like to define the inheritance and the important statements like in the Qt doc (see below).

• According to the Qt documentation, the inheritance is defined with \inherits command. However, I don't see any result when I want to make my objects inherit from Item and I don't have any warning/error when I run the qdoc.

• According the Qt wiki, QDoc considers the version specified in the command as the import statement. Following the example, I tried to define my own import statement since my qml files will be available with a specific import only (let's say MyLib 2.0 here). Like the inheritance, qdoc doesn't seem to understand because I have the following result:

Any idea of what I missed? You can find below a simple example of what I have (the css file is very simple so I don't think it is relevant to show it).

My environment:

• Qt 5.10.10 with msvc2015
• LLVM 9.0.0 (for 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;
}

Thank you for your help !

Answer 1

I think you need to specify the QML module using the \inqmlmodule property and a module.qdoc file.

Example for the mylib.qdoc:

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

    MyLib is a collection of types ... 

    ...
*/

In your QML type file:

import QtQuick 2.10;

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

Item {
 ...
}

For inheritance you can prefix the type with its module:

\inherits QtQuick::Item

If your type is defined in a C++ class, also add the \instanciates property:

\instanciates MyType 

Full example:

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

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

Answer 2

In order for \inherits to work, the type it inherits must be defined somewhere that QDoc can find. Since Item is a type provided by Qt, your .qdocconf file must depend on the module that provides the documentation for Item.

You can do this by adding the following lines to your .qdocconf file.

depends += \
    qtquick

Documentation on depends

Relevant section:

The depends variable defines a list of other documentation projects that this project depends on for resolving link targets for type inheritance and anything else the documentation needs to link to.

But you also need to tell QDoc where the index files for those dependencies are.

When invoking QDoc on a project that has dependencies and uses the depends variable, one or more -indexdir path(s) must be passed as command line option(s). QDoc uses these paths to search for the dependencies' index files.

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

With above, QDoc will search for a file $QT_INSTALL_DOCS/qtquick/qtquick.index for a dependency to qtquick. If an index file for a dependency is not found, QDoc will output a warning.

Which means you need to build the Qt documentation and pass the location of the installed documentation to qdoc

Link on building the Qt documentation

Once you've done that, using \inherits Item should provide the following line in your produced documentation.

Inherits: Item