En esta página

Comandos por 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 del código fuente subyacente.

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

El nombre de la entidad que se está documentando suele ser el único argumento de un comando de tema. Utiliza el nombre completo. En ocasiones, puede haber un segundo parámetro en el argumento. Véase, por ejemplo, \page.

\enum QComboBox::InsertPolicy

El \fn es un caso especial. Para el \fn comando, utiliza la firma de la función incluyendo 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. Se recomienda que el comando de tema sea la primera línea del comentario. Si el argumento ocupa varias líneas, asegúrate de que cada línea (excepto la última) termine con una barra invertida. Además, QDoc cuenta los paréntesis, lo que significa que, si encuentra un «(», considera todo lo que hay 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 los comandos de tema

En el caso de muchos comandos de topic, como \page, QDoc genera un archivo al procesar la documentación.

QDoc normaliza el nombre de cada archivo antes de guardarlo en el disco. Se llevan a cabo 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 sus equivalentes 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 le da al archivo en el comando puede diferir del nombre del archivo real que se guarda en el disco.

Prefijos y sufijos para los archivos generados

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

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

ElementoPrefijoSufijoComando
Módulos QMLNinguno«-qmlmodule»\qmlmodule
MódulosNinguno«-module»\module
EjemplosEl nombre del proyecto, tal y como lo indica la variable de configuración del proyecto, seguido de un guión.«-example»\example
Tipos QMLEl prefijo de salida para QML, tal y como se especifica en la variable de configuración outputprefixes.

Si QDoc conoce el módulo que contiene este tipo, se añade el nombre del módulo como prefijo, seguido del sufijo de salida de QML, tal y como se define en la variable de configuración outputsuffixes, y de un guión.

Ninguno\qmltype

\class

El comando ` \class ` sirve para documentar una clase de C++, una estructura de C/C++ o una unión. El argumento es el nombre completo y calificado 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 indicada se guarda en un archivo « .html » cuyo nombre se deriva del nombre de la clase, en minúsculas, y en el que los calificadores de dos dos puntos se sustituyen por «-». Por ejemplo, la documentación de la clase « QMap::iterator » se guarda en « qmap-iterator.html ».

El archivo contiene la descripción de la clase procedente del comentario \class, además de la documentación generada a partir de los comentarios de 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 \inmodule comando, así como una \brief descripción. A continuación se muestra 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 tu archivo « style.css ».

\concept

El comando \concept crea una página independiente para cada concepto de C++20 y agrupa los tipos y funciones documentados cuyas restricciones de plantilla hacen referencia a él. El argumento es el nombre completo del concepto, que debe coincidir con el nombre que Clang indica para la declaración. Los conceptos en el ámbito del archivo utilizan su nombre sin prefijos; los conceptos dentro de un espacio de nombres necesitan el nombre completo, como por ejemplo algorithms::Ordered.

Un tipo o una función se añade automáticamente a la página de un concepto. Cuando QDoc analiza una declaración documentada, inspecciona las restricciones de la declaración y la registra junto con los conceptos a los que hace referencia. No es necesario utilizar ningún comando del tipo \ingroup o \inmodule en el propio elemento restringido.

QDoc reconoce las tres formas sintácticas de las restricciones de C++20:

  • Una cláusula explícita « requires », tanto si aparece en la cabecera de la plantilla (template <typename T> requires Ordered<T>) como si va al final de la firma de la función.
  • Un parámetro « auto » restringido (void sort(Ordered auto& range)).
  • Un concepto escrito directamente sobre un parámetro de plantilla (template <Ordered T> class SortedSet).

El comando « \concept » suele ir seguido de un \inmodule comando y una \brief descripción. El cuerpo del comentario se muestra como la descripción detallada; \section1 los encabezados funcionan igual que en cualquier otra página de documentación.

/*!
    \concept Ordered
    \inmodule Algorithms

    \brief A type that admits a total order.

    The Ordered concept is satisfied by any type that supplies the
    relational operators \c {<}, \c {<=}, \c {>}, and \c {>=}, and for
    which those operators induce a strict total order.

    \section1 Definition

    Ordered evaluates to \c true when \c {T} is totally ordered
    and to \c false otherwise.
*/

QDoc genera una página de referencia para el concepto. En el ejemplo anterior, la página es ordered.html, que contiene el resumen, la descripción detallada y una sección «Utilizado por» en la que se enumeran los tipos y funciones documentados incluidos en la documentación generada cuyas restricciones hacen referencia a Ordered. Cada entrada se muestra como un enlace seguido de la descripción \brief procedente de la propia documentación de la entrada, con el mismo formato que los listados de las páginas \group y \module.

Las referencias a conceptos no documentados, como los que se encuentran en la biblioteca estándar, se ignoran sin aviso. No generan ninguna página ni emiten ninguna advertencia.

Véase también \group, \module, y \inmodule.

\enum

El comando « \enum » sirve para documentar un tipo de enumeración de C++. El argumento es el nombre completo del tipo de enumeración.

Los valores de la enumeración se documentan en el comentario de ` \enum ` utilizando el \value . Si un valor de la enumeración no se documenta con ` \value`, QDoc emite una advertencia. Estas advertencias pueden evitarse utilizando el \omitvalue para indicar a QDoc que un valor de la enumeración no debe documentarse. La documentación de la enumeración 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 enumeración. Por ejemplo, consideremos el tipo de enumeración ` 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 enumeración se puede documentar de la siguiente manera:

/*!
    \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).
*/

Fíjate en 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 que figuran en la variable «exampledirs» del archivo de configuración de QDoc.

La página de documentación se generará 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 \noautolist se utilice el comando o se haya definido la variable de configuración ` url.examples ` 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: \noautolist, url.examples, \meta

\externalpage

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

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

Esto te permite incluir un enlace a la página externa en tu 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 conseguir el mismo resultado sin utilizar el comando « \externalpage », tendrías que introducir la dirección directamente en tu 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, solo hay que modificar 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, que incluye sus parámetros de plantilla (si los hay), el tipo de retorno, si es `const` y la lista de argumentos formales con sus tipos. Si la función indicada 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 hacerlo de forma explícita, incluso para tipos que se definen sin la palabra clave «auto ».

Desde la versión 6.0 de QDoc, el comando « \fn » se puede utilizar para documentar miembros de clase que no están declarados explícitamente en el encabezado, pero que son generados implícitamente por el compilador: el constructor y el destructor por defecto, el constructor de copia y el constructor de copia por traslado, el operador de asignación y el operador de asignación por traslado.

Al documentar un «hidden friend», puedes utilizar tanto la sintaxis calificada por clase como la sintaxis de función libre no calificada. Por ejemplo, para:

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

El comando se puede escribir como "\fn Foo::operator==(const Foo&, const Foo&)" o como la función libre "\fn bool operator==(const Foo&, const Foo&)". QDoc resuelve los «amigos ocultos» buscando las clases a las que se hace referencia en los tipos de los parámetros de la función.

Nota: El comando \fn es el comando predeterminado de QDoc: cuando no se encuentra ningún comando de tema en un comentario de QDoc, QDoc intenta vincular la documentación al código siguiente como si se tratara de la documentación de una función. Por lo tanto, normalmente no es necesario incluir este comando al documentar una función, si el comentario QDoc de la función está escrito inmediatamente encima de la implementación de la función en el archivo .cpp. Sin embargo, debe estar presente al documentar una función en línea en el archivo .cpp que se implemente en el archivo .h.

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

Nota: Ejecutar en modo de depuración (pasando la opción de línea de comandos -debug o estableciendo la variable de entorno QDOC_DEBUG antes de invocar QDoc) puede ayudar a solucionar problemas con los comandos \fn que QDoc no consigue analizar. En modo de depuración, se dispone de información de diagnóstico adicional.

Véase también \overload.

\group

El comando « \group » crea una página independiente en la que se enumeran las clases, páginas u otras entidades que pertenecen a un grupo determinado. El argumento es el nombre del grupo.

Una clase se incluye en un grupo mediante el \ingroup . Las páginas de resumen también pueden vincularse a un grupo mediante el mismo comando, pero la lista de páginas de resumen debe solicitarse explícitamente mediante el \generatelist comando (véase el ejemplo a continuación).

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

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

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

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

Ten en cuenta que las páginas de resumen relacionadas con el grupo deben indicarse explícitamente mediante el \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, \generatelist, y \noautolist.

\headerfile

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

La documentación de una función, un tipo o una macro declarados en el archivo de cabecera que se está documentando se incluye en la página del archivo de cabecera mediante el \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 dicho archivo.

/*!
   \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 de archivo de cabecera: qtalgorithms.html.

Véase también \inheaderfile.

\macro

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

El comentario « \macro » debe contener un \relates comando que vincule el comentario de la macro a una clase, un archivo de cabecera o un 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 \inmodule comando en el comentario « \class ».

El comando « \module » suele ir seguido de un \title y un \brief . Cada clase aparece como un enlace a la página de referencia de la clase, seguido del texto del \brief . 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 \noautolist comando se puede utilizar aquí 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 de C++ cuyo nombre se indica como argumento. La página de referencia que QDoc genera para un espacio de nombres es similar a la que genera para una clase de C++.

/*!
    \namespace Qt

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

Ten en cuenta que, en C++, un espacio de nombres concreto puede utilizarse en más de un módulo, pero cuando se declaran elementos de C++ de diferentes módulos en el mismo espacio de nombres, este debe documentarse únicamente en un 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 únicamente en QtCore.

\page

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

El comando \page espera un único argumento que represente el nombre del archivo en el que QDoc debe guardar la página.

El título de la página se establece mediante el \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 muestra esta página en aboutqt.html.

\property

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

Una propiedad se define mediante 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)

No es necesario documentar las funciones «set», «reset» y «get»; basta con documentar la propiedad. QDoc generará una lista de las funciones de acceso que aparecerá en la documentación de la propiedad, la cual, a su vez, se incluirá 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 \brief argumento del comando es un fragmento de frase que se incluirá en una descripción de una sola línea de la propiedad. El comando sigue las mismas reglas para la descripción que el \variable comando.

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

    This property's default is false.
*/

\qmlattachedmethod

El comando ` \qmlattachedmethod ` sirve para documentar un método asociado a algún tipo QML (propiedades asociadas). El comando ` \qmlattachedmethod ` se utiliza igual que el \qmlmethod .

El argumento es el resto de la línea y debe ser la firma completa del método, comenzando por el tipo de retorno, seguido del nombre del tipo QML en el que se declara el método, el calificador « :: » y, por último, el nombre del método con los tipos y nombres de sus parámetros entre paréntesis. Si un método no toma argumentos, utiliza « () ».

Por ejemplo, para documentar un método adjunto llamado show() para el tipo ToolTip:

/*!
    \qmlattachedmethod void QtQuick.Controls::ToolTip::show(string text, int timeout = -1)

    This attached method shows the shared tool tip with \a text for
    \a timeout milliseconds. You can attach the method to any item.
*/

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

Nota: Al igual que \qmlproperty, ` \qmlattachedmethod ` acepta un identificador de módulo QML como parte de su argumento.

\qmlattachedproperty

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

Por ejemplo, para documentar una propiedad asociada de QML de tipo booleano 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 de QML del tipo « ListView ».

Nota: Al igual que \qmlproperty, ` \qmlattachedproperty ` acepta un identificador de módulo QML como parte de su argumento.

\qmlattachedsignal

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

El argumento es el resto de la línea. Debe ser el nombre del tipo QML en el que se declara la señal, el calificador « :: » y, por último, el nombre de la señal. Por ejemplo, una señal adjunta en 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 de QML para el elemento GridView.

Nota: Al igual que \qmlproperty, \qmlattachedsignal acepta un identificador de módulo QML como parte de su argumento.

\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 \qmltype . La única diferencia es que el tipo se denominará (y agrupará) como un tipo de valor de QML.

\qmlclass

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

\qmlenum

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

Los elementos de la enumeración y sus descripciones se documentan mediante \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. De forma predeterminada, se utiliza el nombre del tipo QML padre como prefijo para los enumeradores.

Si el primer argumento del comando qdoccmd{valor} 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

En este caso, los enumeradores aparecen como Channel.R, Channel.G y Channel.B.

Como alternativa, es posible replicar la documentación de los enumeradores a partir de un tema existente de C++ \enum , utilizando el \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 y debe incluir el tipo de retorno, así como los nombres y tipos de los parámetros entre paréntesis. Si un método no admite argumentos, utiliza « () ».

/*!
    \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 tipo « TextInput ».

\qmltype

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

Si el tipo QML tiene una clase C++ equivalente, puedes especificar dicha clase con el \nativetype comando «context».

El \inqmlmodule comando documenta el módulo QML al que pertenece el tipo. El argumento que se pasa a este comando debe coincidir con una \qmlmodule .

/*!
    \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 el equivalente en QML de la clase de C++ « QGraphicsTransform ». Un comentario « \qmltype » siempre debe incluir un \since comando, ya que todos los tipos de QML son «new». 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 más \ingroup comandos.

Nota: QDoc detecta automáticamente los tipos singleton y los tipos no creables de QML cuando la clase de C++ correspondiente utiliza la macro « QML_SINGLETON » o « QML_UNCREATABLE ». Para este tipo de tipos, basta con utilizar \qmltype es suficiente, ya que su naturaleza de tipo único o no creable se detectará y documentará automáticamente.

\qmlsingletontype

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

Un tipo singleton de QML garantiza que solo exista una instancia en el motor de 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.
*/

En el caso de las clases de C++ que utilizan la macro ` QML_SINGLETON `, es preferible utilizar \qmltype , ya que QDoc detectará automáticamente la naturaleza de singleton a partir del código C++.

Véase también \qmluncreatabletype.

\qmluncreatabletype

El comando ` \qmluncreatabletype ` sirve para documentar explícitamente un tipo que está registrado en el sistema de tipos de QML, pero que no se puede instanciar directamente en QML.

Este comando es funcionalmente idéntico a \qmltype, pero marca explícitamente el tipo como no creable, independientemente de la implementación en C++.

La designación de «no creable» se muestra en la documentación generada con un indicador «(No creable)» en el título y una nota explicativa.

/*!
    \qmluncreatabletype Dialog
    \inqmlmodule QtQuick.Dialogs

    \brief The base type of native dialogs.
*/

En el caso de las clases de C++ que utilizan la macro « QML_UNCREATABLE », es preferible utilizar \qmltype , ya que QDoc detectará automáticamente que no se puede crear a partir del código C++.

El comando \qmluncreatabletype se introdujo en QDoc en Qt 6.12.

Véase también \qmlsingletontype.

\qmlproperty

El comando « \qmlproperty » sirve 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, por último, 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 comando « \qmlproperty » correspondiente 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 de QML para el tipo Translate.

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

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

Si la propiedad QML expone una enumeración de C++, la propiedad QML se define con el tipo ` enumeration`:

\qmlproperty enumeration ParticleShape3D::ShapeType

Las propiedades de tipo enumeración y aquellas que contienen una combinación bit a bit de indicadores pueden utilizar el \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 completo, incluido el identificador del módulo QML:

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

Si se especifica, el identificador del módulo (en el ejemplo anterior, QtQuick.Controls) debe coincidir con el valor pasado al \inqmlmodule comando en la documentación asociada de \qmltype. Si el nombre del tipo QML al que pertenece la propiedad es único entre todos los tipos del proyecto de documentación, se puede omitir 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 en el que 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 correspondiente 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 de QML para el tipo « MouseArea ».

Nota: Al igual que \qmlproperty, ` \qmlsignal ` acepta un identificador de módulo QML como parte de su argumento.

\qmlmodule

Utiliza el comando \qmlmodule para crear una página de módulo QML. Una página de módulo QML es una recopilación de tipos QML o cualquier material relacionado. El comando admite 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 \inqmlmodule comando al bloque de comentarios que documenta el tipo. Se puede enlazar a 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 en la que se enumeran todos los miembros del mismo.

/*!
    \qmlmodule ClickableComponents

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

\inqmlmodule

Para indicar que un tipo QML está disponible bajo una importación específica de un módulo QML, se inserta el comando « \inqmlmodule » en un \qmltype tema. El comando toma como único argumento el nombre del módulo (importación), sin número de versión.

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

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

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

QDoc genera una línea con la instrucción de importación: import <qmlmodule> en una tabla situada en la parte superior de la página de referencia de tipos de QML.

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

\l {ClickableComponents::}{ClickableButton}

Enlaces a la página de referencia de tipos, con «ClickableButton» como texto del enlace.

\instantiates

El comando « \instantiates » ha quedado obsoleto desde Qt 6.8. Utiliza \nativetype en su lugar.

\nativetype

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

Utiliza el comando \nativetype para especificar cómo se denomina el tipo en C++. Esto garantiza que el bloque de requisitos generado en la documentación para el tipo QML contenga una entrada «En C++». La clase de C++ tendrá una entrada correspondiente «En QML».

Cada tipo de QML solo puede tener un tipo nativo. QDoc emite una advertencia si se produce una redefinición. Sin embargo, varios tipos de QML pueden tener la misma clase de C++ como su tipo nativo. La documentación de la clase de 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 tema incluye \nativetype para especificar que un «Transform» se denomina « QGraphicsTransform » en C++.

\typealias

El comando « \typealias » es similar a \typedef, pero es específico para documentar un alias de tipo en C++:

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

Esto se puede documentar 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 una definición de tipo (typedef) en C++. El argumento es el nombre de la definición de tipo. La documentación de la definición de tipo se incluirá en la documentación de referencia de la clase, el espacio de nombres o el archivo de cabecera en el que se declare dicha definición. Para vincular el ` \typedef ` a una clase, un espacio de nombres o un archivo de cabecera, el comentario ` \typedef ` debe contener un \relates comando.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

El resto de 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 la 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 ubicará en la documentación de la clase, el archivo de cabecera o el espacio de nombres asociados.

En el caso de una variable miembro:

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

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

enum { Type = 0, UserType = 1000 };

Para ellas, el comando « \variable » se puede utilizar de la siguiente 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()
*/

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