Relating Things

The relating commands are for specifying how one documented element relates to another documented element. Some examples:

• This function is an overload of another function.
• This function is a reimplementation of another function.
• This typedef is related to some class or header file.

There is also a command for documenting that a QML type inherits some other QML type.

Commands

\inherits

The \inherits command is for documenting that one QML type inherits some other QML type. It must be included in the inheriting element's \qmltype comment. The argument is the name of the inherited QML type.

/*!
    \qmltype PauseAnimation
    \nativetype QDeclarativePauseAnimation
    \ingroup qml-animation-transition
    \since 4.7
    \inherits Animation
    \brief The PauseAnimation element provides a pause for an animation.

    When used in a SequentialAnimation, PauseAnimation is a step
    when nothing happens, for a specified duration.

    A 500ms animation sequence, with a 100ms pause between two animations:

    SequentialAnimation {
        NumberAnimation { ... duration: 200 }
        PauseAnimation { duration: 100 }
        NumberAnimation { ... duration: 200 }
    }

    \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
*/

QDoc includes this line on the reference page for the PauseAnimation element:

Inherits Animation

\overload

Use the \overload command to mark C++ function overloads. This command must appear on its own line in the documentation comment.

How it works

When you have multiple C++ functions with the same name (overloads) that perform similar work with different parameters, use \overload to avoid repetitive documentation. Functions without \overload require complete documentation. Functions with \overload can focus on their specific differences.

Functions marked with \overload automatically suppress missing parameter warnings, since they reference the documentation of the main function.

Basic usage

/*!
    \overload
    Brief description of what makes this overload different.
*/

Linking to the primary function

Add the function name to create a link to the primary function:

/*!
    \overload functionName()
    Brief description of what makes this overload different.
*/

Use either qualified names (ClassName::functionName()) or unqualified names (functionName()). QDoc automatically qualifies unqualified names using the current class or namespace.

Designating a primary overload

By default, QDoc chooses the primary overload automatically. To explicitly designate which overload serves as the primary, use:

/*!
    \overload primary
    Main documentation for this function family.
    Document all parameters here.
*/

Primary overloads:

• Contain the main function documentation.
• Require complete parameter documentation.
• Do not display "This function overloads..." text.
• Serve as the link target for other overloads.

Use \overload primary when the most important overload differs from QDoc's automatic selection, or when you need consistent linking behavior.

\reimp

The \reimp command is for indicating that a function is a reimplementation of a virtual function without requiring any additional documentation.

By default, QDoc will omit a reimplemented virtual function from the class reference unless it is documented. This command ensures that an otherwise undocumented function will be included.

The command must stand on its own line.

/*!
    \reimp
*/
void QToolButton::nextCheckState()
{
    Q_D(QToolButton);
    if (!d->defaultAction)
        QAbstractButton::nextCheckState();
    else
        d->defaultAction->trigger();
}

This function will not be included in the documentation. Instead, a link to the base function QAbstractButton::nextCheckState() will appear in the documentation.

\relates

The \relates command is for including the documentation of an entity (a function, macro, typedef, enum, or variable) to a class, namespace, or header file. The argument is the name of the class, namespace, or header the entity is related to.

If the argument refers to a templated type, use the type name only (without template parameters).

/*!
    \relates QChar

    Reads a char from the stream \a in into char \a chr.

    \sa {Format of the QDataStream operators}
*/
QDataStream &operator>>(QDataStream &in, QChar &chr)
{
    quint16 u;
    in >> u;
    chr.unicode() = ushort(u);
    return in;
}

The documentation for this function is included on the reference page for class QChar, listed under the Related Non-members section.