Relacionar elementos
Los comandos de relación sirven para especificar cómo se relaciona un elemento documentado 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 archivo de cabecera.
También hay un comando para indicar que un tipo QML hereda de otro tipo QML.
Comandos
\inherits
El comando « \inherits » sirve para documentar que un tipo QML hereda de otro tipo QML. Debe incluirse en el \qmltype . El argumento es el nombre del tipo QML del que se hereda, opcionalmente calificado con el nombre de un 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:
Heredan de Animation
Al documentar un tipo QML directamente en un archivo .qml, normalmente no es necesario utilizar el comando « \inherits », ya que QDoc puede detectar el tipo base a partir de la sintaxis QML. Si se incluye, el comando « \inherits » anulará esta detección automática del tipo base.
\overload
Utiliza el \overload para marcar las sobrecargas de funciones en C++. Este comando debe aparecer en una línea separada dentro del comentario de documentación.
Cómo funciona
Cuando tengas varias funciones de C++ con el mismo nombre (sobrecargas) que realizan tareas similares con parámetros distintos, utiliza \overload para evitar la documentación repetitiva. Las funciones que no \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 por parámetros que faltan, 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ñade 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.
*/Utiliza nombres cualificados (ClassName::functionName()) o nombres no cualificados (functionName()). QDoc cualifica automáticamente los nombres no cualificados utilizando la clase o el espacio de nombres actual.
Nota: Por razones históricas, un nombre no calificado sin parámetros como functionName() sirve como abreviatura para enlazar con la sobrecarga principal, no necesariamente con la sobrecarga sin parámetros. QDoc utiliza un algoritmo de búsqueda para encontrar la «mejor» sobrecarga a la que enlazar. Para enlazar con una función específica sin parámetros, bien se designa como sobrecarga principal con \overload primary, bien se utiliza una firma totalmente calificada que especifique explícitamente la lista de parámetros vacía.
Designación de una sobrecarga principal
Por defecto, QDoc elige la sobrecarga principal automáticamente. Para designar explícitamente qué sobrecarga actúa como principal, utiliza:
/*!
\overload primary
Main documentation for this function family.
Document all parameters here.
*/Sobrecargas principales:
- Incluyen la documentación de la función principal.
- Requieren una documentación completa de los parámetros.
- No muestran el texto «Esta función sobrecarga...».
- Sirven como destino de enlace para otras sobrecargas.
Utiliza «\overload » como principal cuando la sobrecarga más importante difiera de la selección automática de QDoc, o cuando necesites 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 la clase a menos que esté documentada. Este comando garantiza que se incluya una función que, de otro modo, no estaría documentada.
El comando debe figurar en una línea independiente.
/*!
\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`, enumeración o variable) en una clase, un espacio de nombres o un archivo de cabecera. El argumento es el nombre de la clase, el espacio de nombres o el archivo de cabecera al que está relacionada la entidad.
Si el argumento hace referencia a un tipo con plantillas, utiliza solo 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`, en la sección «Elementos no miembros relacionados ».
Nota: Cuando QDoc resuelve nombres de funciones o tipos sin calificar en la documentación, busca en el contexto de la página en la que aparece la documentación. Dado que \relates traslada la documentación a la página de otra clase, es posible que los enlaces automáticos que funcionaban en el contexto original ya no se resuelvan. Utiliza nombres totalmente calificados o comandos explícitos de \l para las referencias cruzadas a miembros de la clase original.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.