QML Documentation Style

This page is part of the Qt Writing Guidelines.

Documentation using QDoc

Qt uses QDoc to generate the QML documentation.

To get started, familiarize yourself with how QDoc works and the basics of setting up a QDoc project.

• QDoc Manual
  • The QDoc Configuration File
  • Topic Commands
  • Context Commands
  • Markup Commands
  • Macros

The general guideline is: Make your documentation set consistent with the rest of Qt.

Follow existing C++ ´documentation and make sure the documentation fits into the current structure.

How QDoc generates QML documentation

QDoc can document QML types with a C++ definition or a purely QML defined type.

QDoc can parse through .cpp implementation files and .qml files, creating a QML node tree to resolve the type properties, functions, and modules. For Qt documentation, QDoc assumes that a QML type may be:

• implemented in C++ .cpp files. C++ class documentation must exist.
• implemented using QML in .qml files. QML documentation must be above the declaration.
• implicitly defined in Javascript or aliases. QML documentation may be in a QDoc .qdoc file.

Otherwise, QDoc will output warnings and will not resolve the QML documentation properly.

Scoping

QML documentation uses C++ scoping style to associate QML members with the QML type and QML module.

For example:

<QML module>::<QML type>::<QML member>

QtNetwork::sslDtlsConfiguration::peerVerifyDepth

QML modules and versions

In Qt 6, QML versioning is no longer applicable but QDoc can still apply versioning to the QML documentation if you need.

For QML modules, the following commands document a module:

• \qmlmodule - QDoc generates the import statement from the module
• \inqmlmodule - types and member documentation can declare membership to a QML module

A QML module documentation must also include:

• \brief - the class' brief description. See section below on the Brief.
• \since - the version when class was added
• \inmodule - associates a class to a Qt module
• \section1 QML Types - use \generatelist and QDoc generates a list of types in the module. See example below
• \section1 Related Information - include links to relevant documentation such as examples or related modules

The example below generates the documentation for the QtNetwork QML module page.

/*!
    \qmlmodule QtNetwork
    \title Qt QML Network QML Types
    \since 6.7
    \ingroup qmlmodules
    \brief Provides core network functionality in QML.

    The Qt QML Network module provides core network functionality in QML.

    The QML types can be imported into your application using the
    following import statement in your .qml file:

    \qml
    import QtNetwork
    \endqml

    \section1 QML Types

    \generatelist {qmltypesbymodule QtNetwork}

    \section1 Related Information
    \list
        \li \l {Qt Network}
        \li \l {Qt Qml QML Types}{Base QML Types}
    \endlist
    \noautolist
*/

QML Types

QML type documentation is generated using the \qmltype command.

Context commands add information about the type, such as its module or which version the class was added.

Some mandatory context commands are:

• \brief - the class' brief description. See section below on the Brief

• \since - the version when class was added

• \inqmlmodule - types and member documentation can declare membership to a QML module

Other important context commands:

• \internal - marks the type as internal and does not appear in the public API documentation
• \nativetype - set the corresponding C++ class and QDoc creates associations between the C++ and QML documentation

The Brief and Detailed Description

The brief description is marked with the \brief command and it is for summarizing the purpose or functionality of the class. QDoc adds the brief descriptions to the annotated lists and tables listing the QML types.

It is a good practice to begin a brief description with a verb, but a noun is appropriate in some areas. Ensure that the brief fits into a QDoc generated table.

Some common initial words for the brief:

• Provides...
• Contains...
• Generates...
• Convenience wrapper...

Things to note:

• QDoc requires a brief description and generates a warning if the brief is empty.
• Terminate the brief description with a period and complete the sentence.
• The brief statement structure differs for C++ APIs, QML APIs, overviews, and examples.

The Detailed Description section starts after the brief description. It provides more information about the class. The detailed description may contain images, snippet code, or links to other relevant documents. There must be an empty line which separates the brief and detailed description.

The example below generates the documentation for NetworkInformation QML type.

/*!
    \qmltype NetworkInformation
    \inqmlmodule QtNetwork
    \nativetype QNetworkInformation
    \brief  Provides a cross-platform interface to network-related information.

    NetworkInformation provides a cross-platform interface to network-related information.

    NetworkInformation is a singleton.

    \sa QNetworkInformation
*/

Properties, read-only, attached properties, and aliases

In QML, there are properties and attached properties. Their documentation is similar, but the QDoc commands are:

• \qmlproperty command is for documenting QML properties
• \qmlattachedproperty command is for attached properties

If the documentation is above the implementation, then QDoc can connect the documentation with the property. Because there are several ways to implement QML properties, the QML documentation needs to be more explicit to help QDoc resolve the type structure. QDoc then generates a listing of properties in the QML type documentation.

Property documentation must include the type. State the type after the \qmlproperty command.

See QML Value Types and Qt Qml Types for examples of QML types.

Property documentation must include:

• \c command to mark property values such as accepted, minimum or maximum ranges, and default values
• \brief command which QDoc uses as the brief description

Other important context commands are:

• \readonly to mark that a command is a read-only
• \since - the version when the property was added

Property documentation usually start with these expressions:

• This property holds…

• This property describes…
• This property represents…
• Returns \c true when… and also when… - for properties that are read
• Sets the… - for properties that configure a type

The example below generates the documentation for ScxmlStateMachine's initialized property.

/*!
    \qmlproperty bool ScxmlStateMachine::initialized

    This read-only property is set to \c true if the state machine has been
    initialized, \c false otherwise.
*/

Documenting QML aliases

The QDoc parser cannot guess the type of the alias, therefore, the type must be fully documented with the \qmlpropertycommand.

Signals and handlers documentation

QML type documentation is generated using the \qmlsignal command.

Signal documentation must include:

• the condition for emitting the signal
• mention the corresponding signal handler
• and document whether the signal accepts a parameter.
  

The example below generates the documentation for PinchHandler's translationChanged() signal.

/*!
    \qmlsignal QtQuick::PinchHandler::translationChanged(QVector2D delta)

    The \c translationChanged signal is emitted when \l activeTranslation (and
    therefore \l persistentTranslation) changes. The \a delta vector gives the
    change in translation. You can use that to incrementally change the
    position of an item:

    \snippet pointerHandlers/pinchHandlerNullTarget.qml 0

    \note If you set the \l persistentTranslation property directly,
    \c delta is \c {0, 0}.
*/

These are the possible documentation styles for signals:

• This signal is triggered when…
• Triggered when…
• Emitted when…

Automatic signal and handler documentation

QDoc collects properties with the corresponding signal and handler when...

Methods and JavaScript functions

QML methods and JavaScript function documentation is generated using the\qmlmethod command.

Typically, methods and JavaScript function documentation precedes the implementation of the function in their sources. But implicitly defined functions may have its documentation in a .qdoc file.

Function documentation must include:

• \a - the parameters and parameter types

• \c - the return type in marked up text
• \since - the version when the function added
• Preconditions, behaviors, and consequences from using the member function.

The function documentation starts with a verb, indicating the operation the function performs.

Some common verbs for function documentation:

• Changes…
• Updates...
• Returns…
• Called...

The example below generates the documentation for InputMethod's setInputMode() method.

/*!
    \qmlmethod bool InputMethod::setInputMode(string locale, int inputMode)

    Changes \a inputMode and \a locale for this input method. The method returns
    \c true if successful.
*/

QML enumerations

QML enumerations are documented as QML properties using the \qmlproperty command.

Enumeration documentation must include:

• \qmlproperty enumeration - states that the property is an enumeration type. QDoc generates a table of values

• \value - the enumerated value. One command for each value

Other important information for QML enumerations are:

• \qmlenumeratorsfrom - for copying C++ enumeration documentation into QML documentation

The example below generates the BarSeries barsType enum.

/*!
    \qmlproperty enumeration BarSeries::barsType

    The type of the bar series:

    \value BarSeries.BarsType.Groups
        Bar sets are grouped by category. This is the default value.
    \value BarSeries.BarsType.Stacked
        Bar sets are stacked after each other by category.
    \value BarSeries.BarsType.StackedPercent
        Bar sets are stacked after each other by category. The segment size corresponds
        to the percentage of the segment value compared with the total value of all
        segments in the stack.
*/

Relating and giving context

QDoc creates an internal structure of the implementation and can generate documentation from this structure. API developers can fine tune QDoc's output by relating the implementations and by giving context to the APIs. For Qt documentation, there are certain things that Qt developers deem as internal or in order to present a cleaner API, abstract implementation details.

For QML API, in many cases, QDoc can assume much of the API structure, but it needs help to abstract and properly connect APIs.

To fine tune relationships and give context to QDoc, here are some common commands:

• \inherits - to state the public inheritance chain of a QML type, \inherits is needed.
• \overload
• \reimp
• \relates

Read the QDoc Manual's Relating Things page for command usage.