Estado

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

\abstract y \qmlabstract

\abstractes un sinónimo del comando \qmlabstract. Añada este comando al \qmltype de un tipo QML cuando ese tipo sólo se vaya a utilizar como tipo base abstracto. Cuando un tipo QML es abstracto, significa que el tipo QML 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 el tipo QML abstracto. Las propiedades se documentan como si fueran propiedades del tipo QML heredero.

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

\attribution

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

El comando \generatelist annotatedattributions genera una lista anotada de todas las páginas de atribución de licencia en el proyecto de documentación.

\default

El comando \default se utiliza para documentar un valor predeterminado para una propiedad QML. El comando toma un único argumento, que se muestra en la documentación como valor predeterminado.

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

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

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

\compares

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

\compares toma uno de los siguientes argumentos:

• strong
• partial
• weak
• equality

strong, partial, y weak se refieren a la ordenación. equality significa que el tipo sólo se compara para la igualdad.

Este comando se introdujo en QDoc con Qt 6.7.

Véase también \compareswith.

\compareswith

Utilice el par de comandos \compareswith .. \endcompareswith para describir los resultados de la comparación del tipo C++ documentado cuando se compara con otros tipos. \compareswith recibe 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 entre los comandos \compareswith y \endcompareswith se consideran detalles adicionales que se aplican a todos los tipos sujetos al argumento de la categoría de comparación.

Los tipos que tienen 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 encerrados 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 se refieren a la ordenación. significa que el tipo sólo se compara para la igualdad. weak equality

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

Vea cómo QDoc representa esta propiedad en la página de referencia del tipo State.

\qmlenumeratorsfrom

Utilice el comando \qmlenumeratorsfrom en un \qmlproperty tema con una propiedad de tipo enumeración, para replicar automáticamente la documentación de los enumeradores de un tema C++. \enum de C++.

El comando toma un enum C++ completamente cualificado como argumento, y genera una lista de enumeradores y sus descripciones.

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 se registran en QML con un nombre de tipo diferente, este nombre (prefijo) puede especificarse 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, \enumy \value.

\dontdocument

El comando \dontdocument sólo se utiliza en un archivo dontdocument.qdoc para un módulo concreto. Este archivo especifica clases o estructuras declaradas públicamente que no deben ser documentadas. QDoc no imprimirá advertencias sobre la falta de comentarios \class para estas clases y structs.

A continuación encontrará el comando \dontdocument en el archivo dontdocument.qdoc para widgets:

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

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

Por defecto, QDoc documenta un \class SomeClass para que esté disponible con la siguiente sentencia include:

#include <SomeClass>

Si la sentencia include real difiere de la predeterminada, puede documentarse como

\class SomeClass
\inheaderfile Tools/SomeClass
...

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

\obsolete

El comando \obsolete es sustituido por el comando \deprecated.

Este comando se mantiene únicamente por razones de compatibilidad con versiones anteriores. Es posible que se elimine en una versión futura de QDoc. Utilice 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 recibe dos argumentos opcionales:

• Una versión entre corchetes (por ejemplo, [6.2]).
• Una cadena con más información, por ejemplo una sugerencia de sustitución.

Cuando se genera la documentación de referencia para una clase, QDoc crea y enlaza a una página separada que documenta los miembros obsoletos. Es una buena práctica 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 ir en su propia línea.

QDoc ignora la documentación, así 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 llame a QDoc con la opción de línea de comandos -showinternal o se establezca la variable de entorno QDOC_SHOW_INTERNAL.

\modulestate

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

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

/*!
    \module QtFoo
    \modulestate Experimental
*/

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

Este módulo se encuentra en estado Experimental.

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

Véase también \preliminary.

\preliminary

El comando \preliminary sirve para indicar que el elemento documentado está aún en fase de desarrollo.

El comando debe ir en su propia línea.

El comando \preliminary se expande a una notificación 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);
}

\readonly

El comando \readonly se utiliza junto con un comando \qmlproperty para marcar la propiedad QML como de sólo lectura.

\required

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

Véase también El sistema de propiedades.

\since

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

Si el argumento pasado a \since no contiene espacios, se asume que es una notación abreviada para el 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 sólo genera la cadena de versión.

El argumento también puede contener explícitamente el nombre del producto:

\since MyFramework 2.0

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

Herencia de la información Since

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

Cláusula Since

El comando \value permite una cláusula since opcional, encerrada entre corchetes, inmediatamente después de la cadena de comandos. Se utiliza para marcar valores enum C++ específicos con información since.

Véase también \value e ignoraince.

\wrapper

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