Relating Things | Qt 6.10

- Qt 6.10
- QDoc Manual
- Context Commands
- Relating Things
- Qt 6.10.3 Reference Documentation

Thread Support ◦ Grouping Things

# 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, optionally qualified with a QML module name.

     /*!
         \qmltype PauseAnimation
         \inqmlmodule QtQuick
         \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

When documenting a QML types directly in a .qml file, the \inherits command is normally not required as QDoc can detect the base type from QML syntax. If present, an \inherits command will override this automatic base type detection.

### \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. If the command is used with a function that isn't an actual overload, it's considered a no-op.

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. You can use either a fully qualified name (such as `QMenu::addAction()`) or an unqualified name (such as `addAction()`). When you use an unqualified function name, QDoc automatically qualifies it by using the parent class or namespace name. For example, `addAction()` becomes `QMenu::addAction()` when used within the `QMenu` class documentation.

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

Thread Support ◦ Grouping Things