Comandos de tema

Un comando de tema indica a QDoc qué elemento del código fuente se está documentando. Algunos comandos de tema permiten crear páginas de documentación que no están vinculadas a ningún elemento de código fuente subyacente.

Cuando QDoc procesa un comentario QDoc, intenta conectar el comentario a un elemento del código fuente buscando primero un comando de tema que nombre el elemento del código fuente. Si no hay ningún comando de tema, QDoc intenta conectar el comentario con el elemento del código fuente que sigue inmediatamente al comentario. Si no puede hacer ninguna de estas dos cosas y si no hay ningún comando de tema que indique que el comentario no tiene un elemento de código fuente subyacente (p. ej. \page), el comentario se descarta.

El nombre de la entidad que se está documentando suele ser el único argumento de una orden de tema. Utilice el nombre completo. A veces puede haber un segundo parámetro en el argumento. Véase, por ejemplo \page.

\enum QComboBox::InsertPolicy

El comando \fn es un caso especial. Para el comando \fn utilice la firma de la función, incluido el calificador de clase.

\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)

Un comando de tema puede aparecer en cualquier parte de un comentario, pero debe estar solo en su propia línea. Es una buena práctica que la orden temática sea la primera línea del comentario. Si el argumento abarca varias líneas, asegúrese de que cada una de ellas (excepto la última) termina con una barra invertida. Además, QDoc cuenta los paréntesis, lo que significa que si encuentra un '(' considera todo hasta el ')' de cierre como su argumento.

Si se repite un comando de tema con argumentos diferentes, aparecerá la misma documentación para ambas unidades.

/*!
    \fn void PreviewWindow::setWindowFlags()
    \fn void ControllerWindow::setWindowFlags()

    Sets the widgets flags using the QWidget::setWindowFlags()
    function.

    Then runs through the available window flags, creating a text
    that contains the names of the flags that matches the flags
    parameter, displaying the text in the widgets text editor.
*/

Las funciones PreviewWindow::setWindowFlags() y ControllerWindow::setWindowFlags() obtendrán la misma documentación.

Nomenclatura de los archivos generados por comandos temáticos

Para muchos comandos de tema, como \pageQDoc genera un archivo al procesar la documentación.

QDoc normaliza el nombre de cada archivo antes de escribirlo en el disco. Se realizan las siguientes operaciones:

• Todas las secuencias de caracteres no alfanuméricos se sustituyen por un guión, '-'.
• Todas las letras mayúsculas se sustituyen por su equivalente en minúsculas.
• Se eliminan todos los guiones finales.

Por ejemplo, el siguiente comando genera un archivo llamado this-generates-a-file-and-writes-it-to-disk.html:

\page this_generates_a_file_(and_writes_it_to_DISK)-.html

Como muestra el ejemplo, el nombre que se da al archivo en el comando puede diferir del nombre del archivo real que se escribe en el disco.

Prefijos y sufijos de los ficheros generados

Cuando QDoc genera un fichero, puede añadir un prefijo, un sufijo, o ambos, dependiendo del elemento que el fichero vaya a documentar.

La siguiente tabla muestra cuáles son esos prefijos y sufijos para varios elementos.

\class

El comando \class sirve para documentar una clase C++, una estructura C/C++ o una unión. El argumento es el nombre completo y cualificado de la clase. El comando indica a QDoc que una clase forma parte de la API pública y permite introducir una descripción detallada.

/*!
    \class QMap::iterator
    \inmodule QtCore

    \brief The QMap::iterator class provides an STL-style
    non-const iterator for QMap and QMultiMap.

    QMap features both \l{STL-style iterators} and
    \l{Java-style iterators}. The STL-style iterators ...
*/

La documentación HTML de la clase nombrada se escribe en un archivo .html con el nombre de la clase, en minúsculas y con los dos puntos dobles sustituidos por '-'. Por ejemplo, la documentación de la clase QMap::iterator se escribe en qmap-iterator.html.

El archivo contiene la descripción de la clase del comentario \class, además de la documentación generada a partir de los comentarios QDoc para todos los miembros de la clase: una lista de los tipos, propiedades, funciones, señales y ranuras de la clase.

Además de la descripción detallada de la clase, el comentario \class suele contener un comando \inmodule así como una \brief descripción. He aquí un ejemplo muy sencillo:

/*!
    \class PreviewWindow
    \inmodule CustomWidgets
    \brief The PreviewWindow class is a custom widget.
           displaying the names of its currently set
           window flags in a read-only text editor.

    \ingroup miscellaneous

    The PreviewWindow class inherits QWidget. The widget
    displays the names of its window flags set with the \l
    {function} {setWindowFlags()} function. It is also
    provided with a QPushButton that closes the window.

    ...

    \sa QWidget
*/

La forma en que QDoc representa este \class depende de su archivo style.css.

\enum

El comando \enum es para documentar un tipo enum de C++. El argumento es el nombre completo del tipo enum.

Los valores del enum se documentan en el comentario \enum utilizando el comando \value . Si un valor enum no se documenta con \value, QDoc emite una advertencia. Estas advertencias pueden evitarse utilizando el comando \omitvalue para indicar a QDoc que un valor enum no debe documentarse. La documentación de enum se incluirá en la página de referencia de la clase, en la página del archivo de cabecera o en la página del espacio de nombres donde se defina el tipo de enum. Por ejemplo, considere el tipo enum Corner en el espacio de nombres Qt:

enum Corner {
    TopLeftCorner = 0x00000,
    TopRightCorner = 0x00001,
    BottomLeftCorner = 0x00002,
    BottomRightCorner = 0x00003
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
    ,TopLeft = TopLeftCorner,
    TopRight = TopRightCorner,
    BottomLeft = BottomLeftCorner,
    BottomRight = BottomRightCorner
#endif
};

Esta enum puede documentarse de esta forma:

/*!
    \enum Qt::Corner

    This enum type specifies a corner in a rectangle:

    \value TopLeftCorner
           The top-left corner of the rectangle.
    \value TopRightCorner
           The top-right corner of the rectangle.
    \value BottomLeftCorner
           The bottom-left corner of the rectangle.
    \value BottomRightCorner
           The bottom-right corner of the rectangle.

    \omitvalue TopLeft
    \omitvalue TopRight
    \omitvalue BottomLeft
    \omitvalue BottomRight
               Bottom-right (omitted; not documented).
*/

Observe la inclusión del calificador de espacio de nombres.

Véase también \value y \omitvalue.

\example

El comando \example sirve para documentar un ejemplo. El argumento es la ruta del ejemplo relativa a una de las rutas enumeradas en la variable exampledirs del archivo de configuración de QDoc.

La página de documentación se mostrará en modulename-path-to-example.html. QDoc añadirá una lista de todos los archivos fuente e imágenes del ejemplo al final de la página, a menos que se utilice el comando \noautolist o la variable de configuración url.examples esté definida para el proyecto.

Por ejemplo, si exampledirs contiene $QTDIR/examples/widgets/imageviewer, entonces

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \subtitle

    The example shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

Véase también: \noautolisturl.ejemplos, \meta

\externalpage

El comando \externalpage asigna un título a una URL externa.

/*!
    \externalpage http://doc.qt.io/
    \title Qt Documentation Site
*/

Esto le permite incluir un enlace a la página externa en su documentación de esta manera:

/*!
    At the \l {Qt Documentation Site} you can find the latest
    documentation for Qt, Qt Creator, the Qt SDK and much more.
*/

Para obtener el mismo resultado sin utilizar el comando \externalpage, tendría que codificar la dirección en la documentación:

/*!
    At the \l {http://doc.qt.io/}{Qt Documentation Site}
    you can find the latest documentation for Qt, Qt Creator, the Qt SDK
    and much more.
*/

El comando \externalpage facilita el mantenimiento de la documentación. Si la dirección cambia, sólo tiene que cambiar el argumento del comando \externalpage.

\fn (función)

El comando \fn sirve para documentar una función. El argumento es la firma de la función, incluidos sus parámetros de plantilla (si los hay), tipo de retorno, const-ness y lista de argumentos formales con tipos. Si la función nombrada no existe, QDoc emite una advertencia.

El comando acepta auto como tipo de una función, aunque QDoc pueda deducir el tipo completo. En determinadas situaciones, puede ser preferible utilizar auto en lugar del tipo real de una función. El uso de auto como tipo de retorno en el comando \fn permite al autor hacer esto explícitamente, también para tipos definidos sin la palabra clave auto.

Desde la versión 6.0 de QDoc, el comando \fn puede usarse para documentar miembros de clase que no están declarados explícitamente en la cabecera, pero que son generados implícitamente por el compilador; constructor y destructor por defecto, constructor de copia y constructor de mover-copiar, operador de asignación y operador de mover-asignación.

Al documentar un amigo oculto, es necesario anteponer el nombre de la clase a la que pertenece el nombre de la función. Por ejemplo, para:

class Foo {
   ...
   friend bool operator==(const Foo&, const Foo&) { ... }
   ...
}

El comando debe escribirse como "\fn Foo::operator==(const Foo&, const Foo&)" y no como la función libre "\fn operator==(const Foo&, const Foo&)".

De lo contrario, QDoc se quejará de que no puede resolver la función.

/*!
    \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const

    Returns \c true if this toolbar is dockable in the given
    \a area; otherwise returns \c false.
*/

Véase también \overload.

\group

El comando \group crea una página separada que lista las clases, páginas u otras entidades pertenecientes a un grupo nombrado. El argumento es el nombre del grupo.

Una clase se incluye en un grupo utilizando el comando \ingroup para incluir una clase en un grupo. Las páginas de resumen también pueden relacionarse con un grupo utilizando el mismo comando, pero la lista de páginas de resumen debe solicitarse explícitamente utilizando el comando \generatelist (véase el ejemplo siguiente).

El comando \group suele ir seguido de un comando \title y una breve introducción al grupo. La página HTML del grupo se escribe en un archivo .html llamado <nombre-del-grupo-en-minúsculas>.html.

Cada entidad del grupo se enumera como un enlace (utilizando el título de la página o el nombre de la clase), seguido de una descripción del comando \brief de la documentación de la entidad.

/*!
    \group io
    \title Input/Output and Networking
*/

QDoc genera una página de grupo io.html.

Tenga en cuenta que las páginas de resumen relacionadas con el grupo deben listarse explícitamente utilizando el comando \generatelist con el argumento related.

/*!
    \group architecture

    \title Architecture

    These documents describe aspects of Qt's architecture
    and design, including overviews of core Qt features and
    technologies.

    \generatelist{related}
*/

Véase también \ingroup, \annotatedlist, \generatelisty \noautolist.

\headerfile

El comando \headerfile sirve para documentar las funciones, tipos y macros globales que se declaran en un archivo de cabecera, pero no en un espacio de nombres. El argumento es el nombre del fichero de cabecera. La página HTML se escribe en un archivo .html construido a partir del argumento del archivo de cabecera.

La documentación de una función, tipo o macro declarada en el archivo de cabecera que se está documentando se incluye en la página del archivo de cabecera mediante el comando \relates comando.

Si el argumento no existe como archivo de cabecera, el comando \headerfile crea de todos modos una página de documentación para el archivo de cabecera.

/*!
   \headerfile <QtAlgorithms>

   \title Generic Algorithms

   \brief The <QtAlgorithms> header file provides
    generic template-based algorithms.

   Qt provides a number of global template functions in \c
   <QtAlgorithms> that work on containers and perform
   well-know algorithms.
*/

QDoc genera una página para el archivo de cabecera, qtalgorithms.html.

Véase también \inheaderfile.

\macro

El comando \macro sirve para documentar una macro C++. El argumento es la macro en uno de tres estilos: macros de tipo función como Q_ASSERT(), macros de tipo declaración como Q_PROPERTY(), y macros sin paréntesis como Q_OBJECT.

El comentario \macro debe contener un comando \relates que adjunte el comentario de la macro a una clase, archivo de cabecera o espacio de nombres. De lo contrario, se perderá la documentación.

\module

El comando \module crea una página que enumera las clases pertenecientes al módulo especificado por el argumento del comando. Una clase incluida en el módulo mediante la inclusión del comando \inmodule en el comentario \class.

El comando \module suele ir seguido de un \title y un comando \brief comando. Cada clase aparece como un enlace a la página de referencia de la clase seguido del texto del comando \brief de la clase. Por ejemplo:

/*!
    \module QtNetwork

    \title Qt Network Module

    \brief Contains classes for writing TCP/IP clients and servers.

    The network module provides classes to make network
    programming easier and portable. It offers both
    high-level classes such as QNetworkAccessManager that
    implements application-level protocols, and
    lower-level classes such as QTcpSocket, QTcpServer, and
    QUdpSocket.
*/

El comando \noautolist para omitir la lista de clases generada automáticamente al final.

Véase también \inmodule

\namespace

El comando \namespace sirve para documentar el contenido del espacio de nombres C++ nombrado como argumento. La página de referencia que QDoc genera para un espacio de nombres es similar a la página de referencia que genera para una clase C++.

/*!
    \namespace Qt

    \brief Contains miscellaneous identifiers used throughout the Qt library.
*/

Ten en cuenta que en C++, un espacio de nombres particular puede ser usado en más de un módulo, pero cuando elementos C++ de diferentes módulos son declarados en el mismo espacio de nombres, el propio espacio de nombres debe ser documentado en un solo módulo. Por ejemplo, el espacio de nombres Qt del ejemplo anterior contiene tipos y funciones tanto de QtCore como de QtGui, pero se documenta con el comando \namespace sólo en QtCore.

\page

El comando \page sirve para crear una página de documentación independiente.

El comando \page espera un único argumento que representa el nombre del archivo donde QDoc debe almacenar la página.

El título de la página se define con el comando \title comando.

/*!
   \page aboutqt.html

   \title About Qt

   Qt is a C++ toolkit for cross-platform GUI
   application development. Qt provides single-source
   portability across Microsoft Windows, macOS, Linux,
   and all major commercial Unix variants.

   Qt provides application developers with all the
   functionality needed to build applications with
   state-of-the-art graphical user interfaces. Qt is fully
   object-oriented, easily extensible, and allows true
   component programming.

   ...
*/

QDoc representa esta página en aboutqt.html.

\property

El comando \property sirve para documentar una propiedad Qt. El argumento es el nombre completo de la propiedad.

Una propiedad se define utilizando la macro Q_PROPERTY(). La macro toma como argumentos el nombre de la propiedad y sus funciones set, reset y get.

Q_PROPERTY(QString state READ state WRITE setState)

Las funciones set, reset y get no necesitan ser documentadas, con documentar la propiedad es suficiente. QDoc generará una lista de la función de acceso que aparecerá en la documentación de la propiedad que a su vez se encontrará en la documentación de la clase que define la propiedad.

El comentario del comando \property suele incluir un \brief comando. En el caso de las propiedades, el argumento del comando \brief es un fragmento de frase que se incluirá en una descripción de una línea de la propiedad. El comando sigue las mismas reglas para la descripción que el comando \variable comando.

/*!
    \property QPushButton::flat
    \brief Whether the border is disabled.

    This property's default is false.
*/

\qmlattachedproperty

El comando \qmlattachedproperty sirve para documentar una propiedad QML que se adjuntará a algún tipo QML. Véase Propiedades adjuntas. El argumento es el resto de la línea. Debe comenzar con el tipo de propiedad, seguido del nombre del tipo QML donde se declara la propiedad, el calificador :: y, por último, el nombre de la propiedad.

Por ejemplo, para documentar una propiedad adjunta QML booleana denominada isCurrentItem para el tipo ListView:

/*!
    \qmlattachedproperty bool ListView::isCurrentItem

    This attached property is \c true if this delegate is the current
    item; otherwise false.

    It is attached to each instance of the delegate.

    This property may be used to adjust the appearance of the current
    item, for example:

    \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
*/

QDoc incluye esta propiedad adjunta en la página de referencia QML para el tipo ListView.

\qmlattachedsignal

El comando \qmlattachedsignal sirve para documentar una señal acoplable. El comando \qmlattachedsignal se utiliza igual que el comando \qmlsignal .

El argumento es el resto de la línea. Debe ser el nombre del tipo QML donde se declara la señal, el calificador :: y, por último, el nombre de la señal. Por ejemplo, una señal adjunta a QML llamada add() en el elemento GridView se documenta así:

/*!
    \qmlattachedsignal GridView::add()
    This attached signal is emitted immediately after an item is added to the view.
*/

QDoc incluye esta documentación en la página de referencia QML del elemento GridView.

\qmlvaluetype

El comando \qmlvaluetype sirve para documentar un tipo de valor para QML. El comando toma un nombre de tipo como único argumento.

\qmlvaluetypees funcionalmente idéntico al comando \qmltype . La única diferencia es que el tipo se titulará (y agrupará) como un tipo de valor QML.

\qmlclass

Este comando está obsoleto. Utilice \qmltype en su lugar.

\qmlenum

El comando \qmlenum sirve para documentar una enumeración QML. El comando toma un único argumento: el nombre completo del tipo de enumeración, incluyendo el tipo QML padre y, opcionalmente, el módulo QML.

Los enumeradores y sus descripciones se documentan mediante los comandos \value comandos.

Por ejemplo,

/*!
    \qmlenum My.Module::Color::Channel
    \brief Specifies a color channel in the RGB colorspace.

    \value R
           Red color channel

    \value G
           Green color channel

    \value B
           Blue color channel
*/

Esto genera documentación para una enumeración Channel, con tres enumeradores: Color.R, Color.G y Color.B. Por defecto, el nombre del tipo QML padre se utiliza como prefijo para los enumeradores.

Si el primer argumento del comando qdoccmd{value} ya incluye un prefijo, se utiliza tal cual:

\value Channel.R
       Red color channel
\value Channel.G
       Green color channel
\value Channel.B
       Blue color channel

Aquí, los enumeradores se enumeran como Channel.R, Channel.G y Channel.B.

Como alternativa, es posible reproducir la documentación de los enumeradores a partir de un tema de C \enum existente, utilizando el comando \qmlenumeratorsfrom comando.

Este comando se introdujo con Qt 6.10.

Véase también \qmlenumeratorsfrom.

\qmlmethod

El comando \qmlmethod sirve para documentar un método QML. El argumento es la firma completa del método, incluyendo el tipo de retorno y los nombres y tipos de los parámetros.

/*!
    \qmlmethod void TextInput::select(int start, int end)

    Causes the text from \a start to \a end to be selected.

    If either start or end is out of range, the selection is not changed.

    After having called this, selectionStart will become the lesser, and
    selectionEnd the greater (regardless of the order passed to this method).

   \sa selectionStart, selectionEnd
*/

QDoc incluye esta documentación en la página de referencia del elemento TextInput.

\qmltype

El comando \qmltype sirve para documentar un tipo QML. El comando tiene un argumento, que es el nombre del tipo QML.

Si el tipo QML tiene una clase C++ equivalente, puede especificarla con el comando \nativetype comando context.

El comando \inqmlmodule documenta el módulo QML al que pertenece el tipo. El argumento pasado a este comando debe coincidir con una página \qmlmodule documentado.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

En este caso, el \qmltype comentario incluye \nativetype para especificar que un Transform es la contrapartida QML de la clase C++ QGraphicsTransform. Un comentario de \qmltype debe incluir siempre un \since porque todos los tipos QML son nuevos. También debe incluir una \brief descripción. Si un tipo QML es miembro de un grupo de tipos QML, el comentario \qmltype debe incluir uno o varios comandos. \ingroup comandos.

\qmlsingletontype

El comando \qmlsingletontype sirve para documentar explícitamente un tipo QML singleton. Este comando es funcionalmente idéntico a \qmltypepero marca explícitamente el tipo como singleton independientemente de la implementación de C++.

Un tipo QML singleton garantiza que sólo exista una instancia en el motor QML. La designación de singleton se muestra en la documentación generada con un indicador "(Singleton)" en el título y una nota explicativa.

/*!
    \qmlsingletontype Settings
    \inqmlmodule MyApp

    \brief Provides application-wide settings as a singleton.

    The Settings type is a singleton that maintains application
    configuration. Access it directly without instantiation.
*/

Para las clases C++ que utilizan la macro QML_SINGLETON, es preferible utilizar \qmltype en su lugar, ya que QDoc detectará automáticamente la naturaleza singleton a partir del código C++.

\qmlproperty

El comando \qmlproperty es para documentar una propiedad QML. El argumento es el resto de la línea. El texto del argumento debe ser el tipo de propiedad, seguido del nombre del tipo QML, el calificador ::, y finalmente el nombre de la propiedad. Si tenemos una propiedad QML llamada x en el tipo QML Translate, y la propiedad tiene el tipo real, el \qmlproperty para ella tendría este aspecto:

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

QDoc incluye esta propiedad QML en la página de referencia QML para el tipo Translate.

El comando \default se utiliza para documentar el valor por defecto de una propiedad:

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

Si la propiedad QML expone un enum de C++, la propiedad QML se define con el tipo enumeration:

\qmlproperty enumeration ParticleShape3D::ShapeType

Las propiedades con tipo de enumeración y las que contienen una combinación de bits de indicadores pueden utilizar el comando \value para documentar los valores aceptables.

\qmlproperty enumeration Buffer::textureFilterOperation
Specifies the texture filtering mode...
\value Buffer.Nearest Use nearest-neighbor filtering.

QDoc también acepta un nombre de propiedad totalmente cualificado, incluido el identificador del módulo QML:

\qmlproperty bool QtQuick.Controls::Button::highlighted

Si se especifica, el identificador del módulo (arriba, QtQuick.Controls) debe coincidir con el valor pasado al comando \inqmlmodule en la documentación asociada de \qmltype. Si el nombre del tipo QML al que pertenece la propiedad es único para todos los tipos del proyecto de documentación, puede omitirse el identificador de módulo.

\qmlsignal

El comando \qmlsignal sirve para documentar una señal QML. El argumento es el resto de la línea. Los argumentos deben ser: el tipo QML donde se declara la señal, el calificador :: y, por último, el nombre de la señal. Si tenemos una señal QML llamada clicked(), la documentación para ella tendría este aspecto:

/*!
    \qmlsignal MouseArea::clicked(MouseEvent mouse)

    This signal is emitted when there is a click. A click is defined as a
    press followed by a release, both inside the MouseArea.
*/

QDoc incluye esta documentación en la página de referencia QML para el tipo MouseArea.

\qmlmodule

Utilice el comando \qmlmodule para crear una página de módulos QML. Una página de módulo QML es una colección de tipos QML o cualquier material relacionado. El comando recibe un argumento opcional de número <VERSION> y es similar al comando group.

Un tipo QML se asocia a un módulo añadiendo el comando \inqmlmodule al bloque de comentarios que documenta el tipo. Puede enlazar con cualquier miembro de un módulo QML utilizando el nombre del módulo y el prefijo de dos dos puntos (::).

/*!
    A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
*/

QDoc genera una página para el módulo que enumera todos los miembros del módulo.

/*!
    \qmlmodule ClickableComponents

    This is a list of the Clickable Components set. A Clickable component
    responds to a \c clicked() event.
*/

\inqmlmodule

Un tipo QML se marca como disponible bajo una importación de módulo QML específica insertando el comando \inqmlmodule en un \qmltype tema. El comando toma el nombre del módulo (importación), sin número de versión, como único argumento.

El nombre del módulo QML debe coincidir con un módulo QML documentado con el comando (\qmlmodule ).

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

    A clickable button that responds to the \c click() event.
*/

QDoc muestra una fila Declaración de importación: import <qmlmodule> en una tabla en la parte superior de la página de referencia del tipo QML.

Al enlazar con tipos QML, el identificador del módulo QML puede aparecer en el destino del enlace. Por ejemplo

\l {ClickableComponents::}{ClickableButton}

Enlace a la página de referencia del tipo, con ClickableButton como texto del enlace.

\instantiates

El comando \instantiates está obsoleto desde Qt 6.8. Utilice \nativetype en su lugar.

\nativetype

El comando \nativetype debe utilizarse junto con el comando \qmltype comando topic. El comando toma una clase C++ como argumento. Si QDoc no puede encontrar la clase C++, emite una advertencia. Este comando se introdujo con Qt 6.8.

Utilice el comando \nativetype para especificar cómo se llama el tipo en C++. Esto garantiza que el bloque de requisitos generado en la documentación para el tipo QML contenga una entrada "In C++". La clase C++ tendrá su correspondiente entrada "In QML".

Un tipo QML sólo puede tener un tipo nativo. QDoc emite una advertencia si se produce una redefinición. Sin embargo, varios tipos QML pueden tener la misma clase C++ como tipo nativo. La documentación de la clase C++ contendrá una lista de todos los tipos correspondientes en QML.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

En este caso, el \qmltype tipo incluye \nativetype para especificar que un Transform se llama QGraphicsTransform en C++.

\typealias

El comando \typealias es similar a \typedefpero específico para documentar un alias de tipo C++:

class Foo
{
public:
    using ptr = void*;
// ...
}

Puede documentarse como

/*!
    \typealias Foo::ptr
*/

El comando \typealias se introdujo en QDoc 5.15.

Véase también \typedef.

\typedef

El comando \typedef sirve para documentar un typedef C++. El argumento es el nombre del typedef. La documentación del typedef se incluirá en la documentación de referencia de la clase, espacio de nombres o fichero de cabecera en el que se declare el typedef. Para relacionar \typedef con una clase, espacio de nombres o archivo de cabecera, el comentario \typedef debe contener un comando \relates orden.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

Otros typedefs se encuentran en la página de referencia de la clase que los define.

/*!
    \typedef QList::Iterator

    Qt-style synonym for QList::iterator.
*/

Véase también \typealias.

\variable

El comando \variable sirve para documentar una variable miembro de una clase o una constante. El argumento es el nombre de la variable o constante. El comentario del comando \variable incluye un \brief comando. QDoc genera la documentación basándose en el texto del comando \brief.

La documentación se encuentra en la clase asociada, archivo de cabecera, o la documentación del espacio de nombres.

En el caso de una variable miembro:

/*!
    \variable QStyleOption::palette
    \brief The palette that should be used when painting
           the control
*/

También puede documentar constantes con el comando \variable. Por ejemplo, supongamos que tiene las constantes Type y UserType en la clase QTreeWidgetItem:

enum { Type = 0, UserType = 1000 };

Para estas, el comando \variable puede ser utilizado de esta manera:

/*!
    \variable QTreeWidgetItem::Type

    The default type for tree widget items.

    \sa UserType, type()
*/

/*!
    \variable QTreeWidgetItem::UserType

    The minimum value for custom types. Values below
    UserType are reserved by Qt.

    \sa Type, type()
*/