Relacionar objetos

Los comandos de relación sirven para especificar cómo un elemento documentado se relaciona con otro elemento documentado. Algunos ejemplos:

• Esta función es una sobrecarga de otra función.
• Esta función es una reimplementación de otra función.
• Este typedef está relacionado con alguna clase o fichero de cabecera.

También existe un comando para documentar que un tipo QML hereda algún otro tipo QML.

Comandos

\inherits

El comando \inherits sirve para documentar que un tipo QML hereda otro tipo QML. Debe incluirse en el comentario del elemento que hereda. \qmltype del elemento heredero. El argumento es el nombre del tipo QML heredado, opcionalmente cualificado con un nombre de módulo QML.

/*!
    \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 incluye esta línea en la página de referencia del elemento PauseAnimation:

Hereda de Animation

Cuando se documentan tipos QML directamente en un archivo .qml, normalmente no es necesario el comando \inherits, ya que QDoc puede detectar el tipo base a partir de la sintaxis QML. Si está presente, un comando \inherits anulará esta detección automática del tipo base.

\overload

Utilice el comando \overload para marcar las sobrecargas de funciones C++. Este comando debe aparecer en su propia línea en el comentario de la documentación.

Cómo funciona

Cuando tiene varias funciones C++ con el mismo nombre (sobrecargas) que realizan un trabajo similar con diferentes parámetros, use \overload para evitar una documentación repetitiva. Las funciones sin \overload requieren una documentación completa. Las funciones con \overload pueden centrarse en sus diferencias específicas.

Las funciones marcadas con \overload suprimen automáticamente las advertencias de falta de parámetros, ya que hacen referencia a la documentación de la función principal.

Uso básico

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

Enlace a la función principal

Añada el nombre de la función para crear un enlace a la función principal:

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

Utilice nombres cualificados (ClassName::functionName()) o nombres no cualificados (functionName()). QDoc califica automáticamente los nombres no calificados utilizando la clase o el espacio de nombres actual.

Designación de una sobrecarga primaria

Por defecto, QDoc elige automáticamente la sobrecarga primaria. Para designar explícitamente qué sobrecarga es la principal, utilice:

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

Sobrecargas primarias:

• Contienen la documentación de la función principal.
• Exigir documentación completa de los parámetros.
• No mostrar el texto "Esta función sobrecarga...".
• Sirven de enlace para otras sobrecargas.

Utilice \overload primary cuando la sobrecarga más importante difiera de la selección automática de QDoc, o cuando necesite un comportamiento de enlace coherente.

\reimp

El comando \reimp sirve para indicar que una función es una reimplementación de una función virtual sin necesidad de documentación adicional.

Por defecto, QDoc omitirá una función virtual reimplementada de la referencia de clase a menos que esté documentada. Este comando garantiza la inclusión de una función que, de otro modo, no estaría documentada.

El comando debe estar en su propia línea.

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

Esta función no se incluirá en la documentación. En su lugar, aparecerá en la documentación un enlace a la función base QAbstractButton::nextCheckState().

\relates

El comando \relates sirve para incluir la documentación de una entidad (una función, macro, typedef, enum o variable) en un archivo de clase, espacio de nombres o cabecera. El argumento es el nombre de la clase, espacio de nombres o cabecera con la que está relacionada la entidad.

Si el argumento se refiere a un tipo de plantilla, utilice sólo el nombre del tipo (sin parámetros de plantilla).

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

La documentación de esta función se incluye en la página de referencia de la clase QChar, que aparece en la sección No miembros relacionados.