En esta página

Estado

Estos comandos sirven para indicar que un elemento documentado tiene un estado especial. El elemento podría estar marcado como «obsoleto», es decir, que está a punto de quedar en desuso y ya no se incluirá en la interfaz pública. El \since comando sirve para especificar el número de versión en la que apareció por primera vez una función o clase. El \qmlabstract comando sirve para marcar un tipo QML como clase base abstracta.

\abstract y \qmlabstract

\abstractes un sinónimo del comando « \qmlabstract ». Añade este comando al \qmltype comentario de un tipo QML cuando dicho tipo esté destinado a utilizarse únicamente como tipo base abstracto. Cuando un tipo QML es abstracto, significa que no se puede instanciar. En su lugar, las propiedades de su API pública se incluyen en la lista de propiedades públicas de la página de referencia de cada tipo QML que hereda del tipo QML abstracto. Las propiedades se documentan como si fueran propiedades del tipo QML heredante.

Normalmente, cuando un tipo QML se marca con \qmlabstract, también se marca con \internal para que no se genere su página de referencia. Si el tipo QML abstracto no está marcado como «internal», tendrá una página de referencia en la documentación.

\attribution

El comando « \attribution » marca un documento de atribución de licencia documentado \page como documentación de atribución de licencia.

El comando «\generatelist annotatedattributions» genera una lista comentada de todas las páginas de atribución de licencias del proyecto de documentación.

\default

El comando « \default » se utiliza para documentar un valor por defecto de una propiedad QML. El comando admite un único argumento, que se muestra en la documentación como valor por defecto.

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

Si el valor por defecto es una cadena no vacía, utiliza comillas:

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\compares

Utiliza el comando « \compares » para describir los resultados de la comparación del tipo C++ documentado cuando se compara consigo mismo. Debes utilizar este comando junto con el \class comando.

\compares Admite uno de los siguientes argumentos:

  • strong
  • partial
  • weak
  • equality

strong, « partial » y « weak » se refieren al orden. « equality » significa que el tipo solo se compara para determinar si son iguales.

Este comando se introdujo en QDoc con Qt 6.7.

Véase también \compareswith.

\compareswith

Utiliza el par de comandos « \compareswith .. \endcompareswith » para describir los resultados de la comparación del tipo C++ documentado con respecto a otros tipos. El comando « \compareswith » admite dos o más argumentos: una categoría de comparación, seguida de un nombre de tipo o una lista de nombres de tipos separados por espacios. Cualquier línea de texto situada entre los comandos « \compareswith » y « \endcompareswith » se considera información adicional que se aplica a todos los tipos sujetos al argumento de categoría de comparación.

Los tipos que contengan uno o más espacios en su nombre, como unsigned long, deben ir entre llaves.

Por ejemplo:

/*!
    ...
    \compareswith strong int long {unsigned long} {unsigned int} char
    ...
    \endcompareswith
    ...
*/

A los argumentos entre llaves se les eliminan los espacios en blanco iniciales y finales. Por ejemplo, unsigned long y unsigned long son equivalentes.

El argumento de la categoría de comparación debe ser uno de los siguientes:

  • strong
  • partial
  • weak
  • equality

strong, partial y weak se refieren al orden. equality significa que el tipo solo se compara para determinar si son iguales.

Este comando se introdujo en QDoc con Qt 6.7.

Véase también \compares.

\qmldefault

El comando « \qmldefault » sirve para marcar una propiedad QML como propiedad por defecto. La palabra « default » aparece en la documentación de la propiedad.

/*!
    \qmlproperty list<Change> State::changes
    This property holds the changes to apply for this state.
    \qmldefault

    By default, these changes are applied against the default state. If the state
    extends another state, then the changes are applied against the state being
    extended.
*/

Consulta cómo QDoc muestra esta propiedad en la página de referencia del tipo « State ».

\qmlenumeratorsfrom

Utiliza el comando \qmlenumeratorsfrom en un \qmlproperty tema con una enumeración de tipo de propiedad para replicar automáticamente la documentación de los enumeradores a partir de un \enum .

El comando toma como argumento una enumeración de C++ completamente calificada y genera una lista de enumeradores y sus descripciones.

Nota: La enumeración de C++ debe estar documentada en el mismo proyecto; QDoc no puede acceder a su documentación si forma parte de un conjunto de documentación externo que el proyecto actual depends .

Por defecto, cada enumerador lleva como prefijo el nombre del tipo al que pertenece la propiedad, con « . » como separador.

Por ejemplo:

/*!
    \qmlproperty enumeration QtMultimedia::Camera::error
    \qmlenumeratorsfrom QCamera::Error

    //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
*/

Si los enumeradores están registrados en QML con un nombre de tipo diferente, este nombre (prefijo) se puede especificar utilizando el argumento opcional entre corchetes:

    \qmlenumeratorsfrom [Errors] QCamera::Error

    //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
\1/

Este comando se introdujo en QDoc 6.8.

Véase también \qmlproperty, \enum, y \value.

\dontdocument

El comando « \dontdocument » solo se utiliza en un archivo «dontdocument.qdoc» para un módulo concreto. Este archivo especifica las clases o estructuras declaradas públicamente que no deben documentarse. QDoc no mostrará advertencias sobre la falta de comentarios « \class » para estas clases y estructuras.

A continuación encontrarás el comando « \dontdocument » en el archivo «dontdocument.qdoc» de los widgets:

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

El metacomando « \inheaderfile » se utiliza para anular la instrucción «include» generada para la documentación de referencia de una clase, un espacio de nombres o un archivo de cabecera de C++.

Por defecto, QDoc documenta un ` \class SomeClass ` como si estuviera disponible mediante la siguiente instrucción `include`:

#include <SomeClass>

Si la instrucción «include» real difiere de la predeterminada, se puede documentar como

\class SomeClass
\inheaderfile Tools/SomeClass
...

Véase también \class y \headerfile.

\obsolete

El comando « \obsolete » ha sido sustituido por el comando « \deprecated ».

Este comando se mantiene únicamente por motivos de compatibilidad con versiones anteriores. Es posible que se elimine en una futura versión de QDoc. Utiliza en su lugar el comando \deprecated.

Véase también \deprecated.

\deprecated

El comando « \deprecated » sirve para indicar que el elemento asociado está obsoleto y que ya no debe utilizarse en código nuevo.

El comando « \deprecated » admite dos argumentos opcionales:

  • Una versión entre corchetes (p. ej., [6.2]).
  • Una cadena con más información, por ejemplo, una alternativa sugerida.

Al generar la documentación de referencia de una clase, QDoc crea y enlaza una página independiente que documenta los miembros obsoletos. Es recomendable sugerir una alternativa equivalente.

/*!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
*/

\internal

El comando « \internal » indica que el elemento documentado no forma parte de la interfaz pública.

El comando debe aparecer en una línea independiente.

QDoc ignora tanto la documentación como el elemento documentado al generar la documentación de referencia de la clase asociada.

/*!
    \internal

    Tries to find the decimal separator. If it can't find
    it and the thousand delimiter is != '.' it will try to
    find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
        (const QString &str, int index) const
{
    int dotindex = str.indexOf(delimiter, index);
    if (dotindex == -1 && thousand != dot && delimiter != dot)
        dotindex = str.indexOf(dot, index);
    return dotindex;
}

Esta función no se incluirá en la documentación, a menos que se ejecute QDoc con la opción de línea de comandos « -showinternal » o se establezca la variable de entorno « QDOC_SHOW_INTERNAL ».

\modulestate

Utiliza el comando « \modulestate » dentro de un tema « \module » o « \qmlmodule » para proporcionar una descripción personalizada del estado del módulo.

El comando admite un argumento que describe el estado del módulo. Por ejemplo:

/*!
    \module QtFoo
    \modulestate Experimental
*/

A continuación, QDoc añadirá esta información en la página del módulo:

Este módulo se encuentra en estado «Experimental ».

Nota: No utilices este comando para marcar un módulo como obsoleto. Utiliza en su lugar el \deprecated comando correspondiente.

En la salida HTML, esta información sobre el estado también aparece en la barra de navegación (ruta de navegación) de las páginas de referencia de los miembros del módulo.

Véase también \preliminary.

\preliminary

El comando « \preliminary » sirve para indicar que el elemento documentado aún se encuentra en fase de desarrollo.

El comando debe aparecer en una línea separada.

El comando « \preliminary » se expande en una nota en la documentación y marca el elemento como preliminar cuando aparece en listas.

/*!
    \preliminary

    Returns information about the joining type attributes of the
    character (needed for certain languages such as Arabic or
    Syriac).

*/
QChar::JoiningType QChar::joiningType() const
{
    return QChar::joiningType(ucs);
}

Desde la versión 6.12 de QDoc, es posible personalizar el descriptor de estado y el contenido de la nota generada para los elementos marcados con \preliminary.

Véase también preliminary variable de configuración.

\readonly

El comando « \readonly » se utiliza junto con el \qmlproperty para marcar la propiedad QML como de solo lectura.

\required

El comando « \required » se utiliza junto con un \qmlproperty para marcar la propiedad QML como obligatoria.

Véase también El sistema de propiedades.

\since

El comando « \since » indica en qué versión secundaria se añadió la funcionalidad asociada.

Si el argumento pasado a \since no contiene espacios, se considera una notación abreviada del nombre del producto, y QDoc antepondrá a la versión el valor de productname en la salida generada. Si la variable productname no está definida, QDoc genera únicamente la cadena de versión.

El argumento también puede contener el nombre del producto de forma explícita:

\since MyFramework 2.0

En este caso, los argumentos (producto y versión) se utilizan tal cual.

Herencia de la información «Desde»

Desde la versión 6.5 de QDoc, las clases de C++ y los tipos de QML heredan la instrucción « \since » de su módulo o módulo QML respectivo, a menos que se utilice explícitamente « \since » en la documentación del tipo.

Cláusula «Since»

El comando « \value » permite que una cláusula «since» opcional, entre corchetes, siga inmediatamente a la cadena de comando. Esto se utiliza para marcar valores específicos de enumeraciones de C++ con información «since».

Véase también \value y «ignoresince».

\wrapper

El comando « \wrapper », cuando se utiliza en la documentación de una clase de C++, marca la clase como un envoltorio que proporciona acceso a una API ajena a Qt. Este comando se utiliza para suprimir las advertencias que, de otro modo, podrían generarse para los miembros de dicha clase.

© 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.