En esta página

Varios

Estos comandos ofrecen funciones diversas relacionadas con el aspecto visual de la documentación y con el proceso de generación de la misma.

\annotatedlist

El comando « \annotatedlist » muestra una lista de los miembros de un grupo, cada uno de ellos acompañado de un breve texto descriptivo. A continuación se muestra un ejemplo extraído de la documentación de referencia de Qt:

/*!
   ...
   \section1 Drag and Drop Classes

   These classes deal with drag and drop and the necessary mime type
   encoding and decoding.

   \annotatedlist draganddrop
*/

Esto genera una lista de todas las clases de C++ y/o tipos de QML del grupo «draganddrop ». Una clase de C++ o un tipo de QML del grupo «draganddrop» tendrá «\ingroup draganddrop » en su \class o \qmltype comentario.

Los elementos del grupo se ordenan en orden ascendente, según el nombre o título visible para el usuario. Desde QDoc 6.8, \annotatedlist y \generatelist también admiten la ordenación personalizada.

Véase también \generatelist y Ordenación de los miembros del grupo.

\cmakepackage

Utiliza el comando « \cmakepackage » para añadir información sobre los paquetes CMake a las clases y los espacios de nombres. Esta información aparecerá en una tabla situada en la parte superior de la página de documentación de la clase o del espacio de nombres. Por ejemplo:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc mostrará esto como

Espacio de nombres Foo

Un espacio de nombres. Más...

Encabezado:#include <Bar>
CMake: find_package(Baz REQUIRED)
target_link_libraries(mytarget PRIVATE Baz::Baz)

Véase también \module y \cmakecomponent}

\cmakecomponent

Utiliza el comando « \cmakecomponent » para añadir información sobre los componentes de CMake a las clases y los espacios de nombres. Esta información aparecerá en una tabla situada en la parte superior de la página de documentación de la clase o del espacio de nombres. Por ejemplo:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDoc mostrará esto como

Espacio de nombres Foo

Un espacio de nombres. Más...

Encabezado:#include <Bar>
CMake: find_package(Qt6 REQUIRED COMPONENTS Baz)
target_link_libraries(mytarget PRIVATE Qt6::Baz)

Véase también \module y \cmakepackage}

\cmaketargetitem

Utiliza el comando « \cmaketargetitem » para anular la parte relativa a los elementos de la información de « target_link_libraries » de CMake que se añade a las clases y los espacios de nombres. El comando debe utilizarse junto con el \module y \cmakecomponent . Por ejemplo:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \cmaketargetitem Qt6::BazPrivate
    \brief A namespace.

    ...
*/

QDoc generará esto como

Espacio de nombres Foo

Un espacio de nombres. Más...

Encabezado:#include <Bar>
CMake: find_package(Qt6 REQUIRED COMPONENTS Baz)
target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)

Véase también \module y \cmakecomponent}

\qtcmakepackage

Utiliza el comando « \qtcmakepackage » para añadir información del paquete CMake a las clases y los espacios de nombres. Esta información aparecerá entonces en una tabla situada en la parte superior de la página de documentación de la clase o del espacio de nombres. Por ejemplo:

/*!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc mostrará esto como

Espacio de nombres Foo

Un espacio de nombres. Más...

Encabezado:#include <Bar>
CMake: find_package(Qt6 REQUIRED COMPONENTS Baz)

\qtcmaketargetitem

Utiliza el comando « \qtcmaketargetitem » para anular la parte «item» de la información « target_link_libraries » de CMake que se añade a las clases y los espacios de nombres. El comando debe utilizarse junto con el \module y \qtcmakepackage .

Véase también \module y \qtcmakepackage}

\generatelist

El comando « \generatelist » se expande en una lista de enlaces a las entidades de la documentación agrupadas por un \ingroup o a entidades que coincidan con uno de los argumentos que se enumeran a continuación. Un ejemplo extraído de la documentación de referencia de Qt:

/*!
   \page classes.html
   \title All Classes

   For a shorter list that only includes the most
   frequently used classes, see \l{Qt's Main Classes}.

   \generatelist classes Q
*/

Esto genera la página «Todas las clases ». El comando admite los siguientes argumentos:

<group-name>

Si se especifica únicamente un nombre de grupo como argumento, QDoc muestra todas las entidades que utilizan el comando « \ingroup <group-name> ».

Ordenar los miembros del grupo

Al generar una lista de miembros del grupo, estos se ordenan en orden ascendente, según el nombre o título visible para el usuario. Desde la versión 6.8 de QDoc, se puede modificar el orden de clasificación predeterminado:

\generatelist [descending] changelogs

Suponiendo que el grupo «changelogs» esté formado por páginas que detallan los cambios en las diferentes versiones, esto genera la lista en orden descendente (la versión más reciente primero).

Clave de ordenación

Desde QDoc 6.8, se puede asignar una clave de ordenación personalizada a uno o varios miembros del grupo mediante el \meta siguiente comando:

\meta sortkey {sort key}

A continuación, la ordenación (ascendente o descendente) se realiza en función de estas claves, en lugar de los títulos visibles para el usuario.

Nota: Cualquier miembro del grupo que tenga una clave de ordenación aparece antes que los miembros que no la tienen (en el orden ascendente predeterminado). Esto permite situar a uno o varios miembros del grupo en la parte superior de la lista.

annotatedclasses

El argumento « annotatedclasses » proporciona una tabla que contiene los nombres de todas las clases y una descripción de cada una de ellas. Cada nombre de clase es un enlace a la documentación de referencia de la clase. Por ejemplo:

QDialControl de rango redondeado (como un velocímetro o un potenciómetro)
QDialogLa clase base de las ventanas de diálogo
QDirAcceso a las estructuras de directorios y a su contenido

Una clase de C++ se documenta con el \class . La anotación de la clase se extrae del argumento del comando \brief .

annotatedexamples

El argumento annotatedexamples proporciona una lista completa de todos los ejemplos en forma de conjunto de tablas que contienen los títulos de todos los ejemplos y una descripción de cada uno de ellos. Cada título es un enlace a la documentación del ejemplo.

Se genera una tabla independiente para cada módulo (que cuente con ejemplos documentados), siempre que el módulo haya definido una variable de configuración `navigation.landingpage`. La variable `landingpage` se utiliza como título de un encabezado que precede a cada tabla.

annotatedattributions

El argumento « annotatedattributions » proporciona una lista completa de todas las atribuciones en forma de conjunto de tablas que contienen los títulos de todas las atribuciones y una descripción de cada una de ellas. Cada título es un enlace a la página de la atribución.

Se genera una tabla independiente para cada módulo (que tenga atribuciones), siempre que el módulo haya definido una variable de configuración `navigation.landingpage`. La variable `landingpage` se utiliza como título de un encabezado que precede a cada tabla.

classes <prefix>

El argumento « classes » proporciona una lista alfabética completa de las clases. El segundo argumento, ` <prefix>`, es el prefijo común para los nombres de las clases. Los nombres de las clases se ordenarán según el carácter que siga al prefijo común. Por ejemplo, el prefijo común para las clases de Qt es ` Q`. El argumento del prefijo común es opcional. Si no se proporciona ningún prefijo común, los nombres de las clases se ordenarán según su primer carácter.

Cada nombre de clase se convierte en un enlace a la documentación de referencia de la clase. Este comando se utiliza para generar la página «Todas las clases» de la siguiente manera:

/*!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
*/

Una clase de C++ se documenta con el \class comando.

classesbymodule

Cuando se utiliza este argumento, se requiere un segundo argumento que especifique el módulo cuyas clases se van a enumerar. QDoc genera una tabla que contiene dichas clases. Cada clase aparece en la lista con el texto de su \brief comando.

Por ejemplo, este comando se puede utilizar en la página de un módulo de la siguiente manera:

/*!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

    ...
*/

Cada clase que forme parte del módulo especificado debe marcarse con el \inmodule en su comentario « \class ».

qmltypesbymodule

Similar al argumento « classesbymodule », pero se utiliza para enumerar los tipos QML (excluidos los tipos de valor QML) del módulo QML especificado con el segundo argumento.

Nota: La compatibilidad con este argumento se introdujo en QDoc 5.6.

qmlvaluetypesbymodule

Es similar al argumento « qmltypesbymodule », pero en su lugar enumera los tipos de valor de QML.

Nota: La compatibilidad con este argumento se introdujo en QDoc 6.7.

functionindex

El argumento functionindex proporciona una lista alfabética completa de todas las funciones miembro documentadas. Normalmente se utiliza únicamente para generar la página de índice de funciones de Qt de esta manera:

/*!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
*/

legalese

El argumento legalese indica a QDoc que genere una lista de licencias en el proyecto de documentación actual. Cada licencia se identifica mediante el \legalese comando.

overviews

El argumento ` overviews ` se utiliza para indicar a QDoc que genere una lista concatenando el contenido de todas las \group páginas. Qt lo utiliza para generar la página de resumen de la siguiente manera:

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

El argumento « attributions » se utiliza para indicar a QDoc que genere una lista de atribuciones en la documentación.

El argumento « related » se utiliza junto con el \group y \ingroup para enumerar todas las descripciones generales relacionadas con un grupo específico. Por ejemplo, la página «Programación con Qt » se genera de esta manera:

/*!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
*/

Cada página que aparece en esta página de grupo contiene el comando:

\ingroup qt-basic-concepts

Véase también \annotatedlist.

\if

El comando « \if » y el comando correspondiente « \endif » enmarcan partes de un comentario QDoc que solo se incluirán si la condición especificada por el argumento del comando es verdadera.

El comando lee el resto de la línea y la analiza como una instrucción #if de C++.

/*!
   \if defined(opensourceedition)

   \note This edition is for the development of
   \l{Qt Open Source Edition} {Free and Open Source}
   software only; see \l{Qt Commercial Editions}.

   \endif
*/

Este comentario QDoc solo se mostrará si está definido el símbolo del preprocesador opensourceedition y se ha especificado en la variable «defines» del archivo de configuración para que QDoc procese el código entre #ifdef y #endif:

defines = opensourceedition

También puedes definir el símbolo del preprocesador manualmente en la línea de comandos. Para obtener más información, consulta la documentación de la variable `defines`.

Véase también \endif, \else, «defines » y «falsehoods».

\endif

El comando « \endif » y el comando correspondiente « \if » enmarcan partes de un comentario QDoc que se incluirán si la condición especificada por el \if argumento del comando sea verdadera.

Para obtener más información, consulta la documentación del \if comando.

Véase también \if, \else, definiciones y falsedades.

\else

El comando « \else » especifica una alternativa en caso de que la condición del \if comando es falsa.

El comando « \else » solo se puede utilizar dentro de los comandos «\if »... « \endif », pero resulta útil cuando solo hay dos alternativas.

\include

El comando « \include » envía todo o parte del archivo especificado por su primer argumento al flujo de entrada de QDoc para que se procese como un fragmento de comentario de QDoc.

El comando resulta útil cuando se desea utilizar un fragmento de comandos o texto en varios lugares de la documentación. Utiliza el comando \include siempre que quieras insertar un fragmento en la documentación. El archivo que contiene el fragmento a incluir debe encontrarse en alguna de las rutas indicadas en las variables de configuración de QDoc «sourcedirs » o «exampledirs ». Puede ser cualquier archivo fuente analizado por QDoc (o incluso el mismo en el que se utiliza el comand \include ), o cualquier otro archivo de texto. Para almacenar fragmentos en un archivo independiente que no esté destinado a ser analizado por QDoc, utiliza una extensión de archivo que no figure en sources.fileextensions; por ejemplo, .qdocinc.

El comando puede tener uno o más argumentos. El primer argumento es siempre un nombre de archivo. El contenido del archivo debe ser entrada de QDoc; en otras palabras, una secuencia de comandos de QDoc y texto, pero sin los delimitadores de comentarios de QDoc que lo enmarcan: /*! ... */ . Si desea incluir todo el archivo indicado, deje el segundo argumento vacío. Si deseas incluir solo una parte del archivo, consulta la forma de dos argumentos que se muestra a continuación. A continuación se muestra un ejemplo de la forma de un solo argumento:

/*!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
*/

\include nombre-archivo identificador-fragmento

Es una pérdida de tiempo crear un archivo .qdocinc independiente para cada fragmento de código QDoc que quieras utilizar en varios lugares de la documentación, sobre todo teniendo en cuenta que probablemente tengas que incluir el aviso de copyright y licencia en cada uno de estos archivos. Si tienes varios fragmentos que incluir, puedes ponerlos todos en un único archivo y rodear cada uno de ellos con:

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

A continuación, puedes utilizar la forma del comando con dos argumentos:

\include examples/signalandslots.qdocinc snippet-id2
\include examples/objectmodel.qdocinc another-snippet-id

La secuencia de comandos de QDoc y el texto que se encuentra entre las dos etiquetas con el mismo nombre que el segundo argumento se envía al flujo de entrada de QDoc. Incluso puedes tener fragmentos anidados.

Nota: Los identificadoresde fragmentos también funcionan dentro de los bloques de comentarios de documentación (/*! .. */), por lo que no es necesario utilizar un archivo .qdocinc independiente. Al procesar un bloque de comentarios, QDoc elimina cualquier línea de comentario //! de la salida generada.

Argumentos adicionales

Desde QDoc 6.3, cualquier argumento adicional que se pase al comando \include se utiliza para insertar cadenas en el contenido incluido. Para insertar una cadena en una ubicación específica del contenido, añade una barra invertida seguida de un dígito (1..9). Los dígitos se corresponden con el orden de la lista de argumentos. Encuadra los argumentos entre llaves para asegurarte de que QDoc represente el argumento completo, incluidos los posibles caracteres de espacio en blanco, tal y como esperas.

Importante: Cada argumento adicional (incluido el ID del fragmento) debe ir entre llaves. Si quieres incluir el archivo completo, utiliza un ID de fragmento vacío: {}.

Por ejemplo, dado el siguiente fragmento de código en un archivo includes.qdocinc:

//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]

Entonces, la siguiente línea \include:

\include includes.qdocinc {usage} {detailed output} {Verbose}

Se muestra

Para habilitar la salida detallada, selecciona « Verbose » > « Enable ».

\meta

El comando « \meta » se utiliza para añadir metadatos a la documentación. El comando tiene dos argumentos: el primero es el nombre del atributo de metadatos y el segundo es el valor de dicho atributo. Cada argumento debe ir entre llaves, tal y como se muestra en este ejemplo:

/*!
    \example demos/coffee
    \title Coffee Machine
    \brief A Qt Quick application with a state-based custom user interface.

    \meta {tags} {quick,embedded,states,touch}
    \meta {category} {Application Examples}
*/

Hay una serie de atributos de metadatos que tienen una finalidad específica:

Ejemplo de metadatos

Otro uso del comand \meta es incluir metadatos (etiquetas) en \example la documentación. Por defecto, QDoc genera etiquetas de ejemplo basadas en el \title y el nombre del módulo. Estas etiquetas se muestran en el modo «Bienvenida» de Qt Creator, lo que ayuda a los usuarios a navegar por la lista de ejemplos.

Se pueden crear etiquetas adicionales con \meta {tag} {tag1} o \meta {tags} {tag1,[tag2,...]}. Por ejemplo:

/*!
    \example helloworld
    \title Hello World Example
    \meta {tags} {tutorial,basic}
*/

Esto daría lugar a las siguientes etiquetas: tutorial, básico, hola, mundo. Se ignoran las palabras comunes, como «ejemplo ».

Exclusión de ejemplos

Si se marca un ejemplo como «no funciona», se excluirá del archivo de manifiesto generado, lo que supondrá su eliminación efectiva del modo «Bienvenida» de Qt Creator.

\meta {tag} {broken}

Rutas de instalación de los ejemplos

El comando \meta, combinado con el argumento installpath, especifica la ubicación de un ejemplo instalado. Este valor anula el establecido mediante la variable de configuración examplesinstallpath.

/*!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
*/

Véase también examplesinstallpath.

Estado

Un argumento « status » para el comando « \meta » añade una descripción de estado personalizada para un \class o un \qmltype. Esta descripción aparecerá entonces en una tabla situada en la parte superior de la página de referencia del tipo.

/*!
    \class QNativeInterface::QAndroidApplication
    \meta {status} {Android-specific}
*/

Véanse también los comandos relacionados con el estado.

Metadatos del documento

El argumento « keywords » del comando « \meta » añade las palabras clave especificadas como metadatos del documento generado:

\meta {keywords} {reference, internal}

En la salida HTML, estas palabras clave se generan como un elemento ` <meta name="keywords" content="..."> `.

\noautolist

El comando « \noautolist » indica que debe omitirse la lista comentada de clases de C++ o tipos de QML, que se genera automáticamente al final de la página del módulo de C++ o QML, ya que dichas clases o tipos se han enumerado manualmente. Este comando también puede utilizarse junto con el \group para omitir la lista de miembros de un grupo, cuando estos se han enumerado manualmente.

El comando debe aparecer en una línea independiente. Véase Qt Quick Controls QML Types para ver un ejemplo. La página se genera a partir de qtquickcontrols2-qmlmodule.qdoc. Allí encontrarás un comentario QDoc que contiene el comando \qmlmodule para el módulo QtQuick.Controls. El mismo comentario contiene un comando \noautolist para desactivar la generación automática de listas, y un \generatelist para enumerar los tipos QML en una sección específica del documento.

Este comando se introdujo en QDoc 5.6.

Desde Qt 5.10, este comando también se puede aplicar a la \example la documentación, donde hace que se omita la lista generada automáticamente de archivos e imágenes pertenecientes a un proyecto de ejemplo.

\omit

El comando « \omit » y el correspondiente « \endomit » delimitan las partes de la documentación que quieres que QDoc omita. Por ejemplo:

/*!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
*/

\raw (¡evitar!)

El comando « \raw » y el comando correspondiente « \endraw » delimitan un bloque de código sin formato en lenguaje de marcado.

Advertencia: Evita utilizar este comando siempre que sea posible. Si intentas generar un comportamiento especial en tablas o listas, intenta conseguir el comportamiento deseado utilizando el comando \span y \div en tu \table o \list.

El comando admite un argumento que especifica el formato del código.

QDoc genera el código indicado únicamente cuando se genera el formato especificado por el usuario.

Por ejemplo, «\raw HTML» solo generará código cuando QDoc genere documentación HTML.

Nota: A menudose puede lograr el objetivo deseado utilizando los comandos de QDoc, al tiempo que se reduce la probabilidad de cometer errores o de que el contenido quede desatendido.

\sincelist

El comando « \sincelist » se desglosa en un desglose detallado de las nuevas incorporaciones a la API documentada en una versión específica. Ejemplo de uso:

/*!
   \page newclasses612.html
   \title New Classes and Functions in 6.12
   \brief A comprehensive list of new classes and functions in 6.12.

   \sincelist 6.12
*/

\sincelisttoma un único argumento: una cadena de versión. La salida generada incluye todas las funcionalidades marcadas con un \since o una cláusula «since» que coincida con la cadena de versión.

\unicode

El comando « \unicode » permite insertar un carácter Unicode cualquiera en el documento.

El comando toma un argumento que especifica el carácter como un número entero. Por defecto, se asume la base 10, a menos que se especifique un prefijo «0x» o «0» (para la base 16 y 8, respectivamente).

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