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

The \overload command is for indicating that a function is a secondary overload of its name.

The command must stand on its own line.

For a function name that is overloaded (except constructors), QDoc expects one primary version of the function, and all the others marked with the \overload command. The primary version should be fully documented. Each overload can have whatever extra documentation you want to add for just that overloaded version.

You can include the function name plus '()' as a parameter to the \overload command, which will include a standard This function overloads... line of text with a link to the documentation for the primary version of the function.

/*!
    \overload addAction()

    This convenience function creates a new action with an
    \a icon and some \a text. The function adds the newly
    created action to the menu's list of actions, and
    returns it.

    \sa QWidget::addAction()
*/
QAction *QMenu::addAction(const QIcon &icon, const QString &text)
{
    QAction *ret = new QAction(icon, text, this);
    addAction(ret);
    return ret;
}

If you don't include the function name with the \overload command, then instead of the "This function overloads..." line with the link to the documentation for the primary version, you get the old standard line:

This is an overloaded member function, provided for convenience.

.

\reimp

The \reimp command is for indicating that a function is a reimplementation of a virtual function.

The command must stand on its own line.

QDoc will omit the reimplemented function from the class reference.

/*!
    \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.