Estos comandos proporcionan 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 se expande a una lista de los miembros de un grupo, cada miembro listado con su breve texto. A continuación se muestra un ejemplo 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 C++ y/o tipos QML en el grupo draganddrop. Una clase C++ o tipo QML en el grupo draganddrop tendrá \ingroup draganddrop en sus etiquetas \class o \qmltype comentario.

Los miembros 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 admiten también la ordenación personalizada.

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

\cmakepackage

Utilice el comando \cmakepackage para añadir información del paquete CMake a las clases y espacios de nombres. Esta información aparecerá en una tabla en la parte superior de la página de documentación de la clase o 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...

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

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

\cmakecomponent

Utilice el comando \cmakecomponent para añadir información de componentes CMake a clases y espacios de nombres. Esta información aparecerá en una tabla en la parte superior de la página de documentación de la clase o 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...

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

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

\cmaketargetitem

Utilice el comando \cmaketargetitem para anular la parte del elemento de la información de CMake target_link_libraries que se añade a las clases y espacios de nombres. El comando debe usarse junto con los comandos \module y \cmakecomponent . Por ejemplo:

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

    ...
*/

QDoc mostrará esto como

Espacio de nombres Foo

Un espacio de nombres. Más...

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

Ver también \module y \cmakecomponent}

\qtcmakepackage

Utilice el comando \qtcmakepackage para añadir información del paquete CMake a las clases y espacios de nombres. Esta información aparecerá en una tabla en la parte superior de la página de documentación de la clase o 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...

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

\qtcmaketargetitem

Utilice el comando \qtcmaketargetitem para anular la parte del elemento de la información de CMake target_link_libraries que se añade a las clases y espacios de nombres. El comando debe usarse junto con los comandos \module y \qtcmakepackage .

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

\generatelist

El comando \generatelist se expande a una lista de enlaces a las entidades de documentación agrupadas con un \ingroup o entidades que coinciden con uno de los argumentos enumerados a continuación. Un ejemplo 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 acepta los siguientes argumentos:

<group-name>

Con un nombre de grupo como único argumento, QDoc lista todas las entidades que utilizan el comando \ingroup <group-name>.

Clasificación de los miembros de un grupo

Cuando se genera una lista de miembros de un grupo, éstos se ordenan en orden ascendente, según el nombre o título visible para el usuario. Desde QDoc 6.8, el orden de clasificación predeterminado puede modificarse:

\generatelist [descending] changelogs

Asumiendo que el grupo changelogs consiste en páginas que detallan cambios en diferentes versiones, esto genera la lista en orden descendente (la versión más nueva primero).

Clave de ordenación

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

\meta sortkey {sort key}

La ordenación (ascendente o descendente) se realiza entonces en función de esta(s) clave(s), en lugar de en función de los títulos visibles para el usuario.

annotatedclasses

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

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

annotatedexamples

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

Se genera una tabla separada para cada módulo (que tenga ejemplos documentados), siempre que el módulo haya definido una variable de configuración navigation.landingpage. La variable landingpage se utiliza como título para una cabecera que precede a cada tabla.

annotatedattributions

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

Se genera una tabla separada para cada módulo (que tiene atribuciones), siempre que el módulo haya definido una variable de configuración navigation.landingpage. La variable landingpage se utiliza como título para una cabecera 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 Qt es Q. El prefijo común es opcional. Si no se proporciona ningún prefijo común, los nombres de las clases se ordenarán por 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 así la página Todas las clases:

/*!
    \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 C++ se documenta con el comando \class comando.

classesbymodule

Cuando se utiliza este argumento, se requiere un segundo argumento, que especifica el módulo cuyas clases deben listarse. QDoc genera una tabla que contiene esas clases. Cada clase se lista con el texto de su \brief comando.

Por ejemplo, este comando se puede utilizar en una página de 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 sea miembro del módulo especificado debe marcarse con el comando \inmodule en su comentario \class.

qmltypesbymodule

Similar al argumento classesbymodule, pero utilizado para listar los tipos QML (excluyendo los tipos de valor QML) del módulo QML especificado con el segundo argumento.

qmlvaluetypesbymodule

Similar al argumento qmltypesbymodule, pero en su lugar enumera los tipos de valor QML.

functionindex

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

/*!
    \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 comando \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 así la página de resúmenes:

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

related

El argumento related se utiliza en combinación con los argumentos \group y \ingroup para obtener una lista de todos los resúmenes relacionados con un grupo especificado. Por ejemplo, la página de Programación con Qt se genera de esta forma:

/*!
    \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 listada 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 encierran partes de un comentario QDoc que sólo 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 sentencia #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 sólo se mostrará si el símbolo de preprocesador opensourceedition está definido, y especificado en la variable defines en el fichero de configuración para hacer que QDoc procese el código dentro de #ifdef y #endif:

defines = opensourceedition

También puede definir el símbolo del preprocesador manualmente en la línea de comandos. Para más información consulte la documentación de la variable defines.

Véase también \endif, \else, defines y false.

\endif

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

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

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

\else

El comando \else especifica una alternativa si la condición del comando \if es falsa.

El comando \else sólo se puede utilizar dentro de los comandos \if... \endif, pero es útil cuando sólo 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 ser procesado como un fragmento de comentario QDoc.

El comando es útil cuando algún fragmento de comandos o texto se va a utilizar en varios lugares de la documentación. Utilice el comando \include siempre que desee insertar un fragmento en la documentación. El archivo que contiene el fragmento que se va a incluir debe encontrarse en la(s) ruta(s) indicada(s) en la variable 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 comando \include ), o cualquier otro archivo de texto. Para almacenar fragmentos en un archivo independiente que no esté destinado a ser analizado por QDoc, utilice una extensión de archivo que no aparezca 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 una entrada QDoc, es decir, una secuencia de comandos y texto QDoc, pero sin los delimitadores de comentario QDoc /*! ... */ . Si desea incluir el archivo completo, deje vacío el segundo argumento. Si sólo desea incluir una parte del fichero, consulte la forma de dos argumentos que aparece a continuación. He aquí un ejemplo de la forma de un argumento:

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

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

\include nombre-archivo fragmento-identificador

Es una pérdida de tiempo crear un archivo .qdocinc separado para cada fragmento de inclusión de QDoc que desee utilizar en varios lugares de la documentación, sobre todo teniendo en cuenta que probablemente tenga que poner el aviso de copyright/licencia en cada uno de estos archivos. Si tiene varios fragmentos para incluir, puede 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, puede utilizar la forma de dos argumentos del comando:

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

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

Argumentos adicionales

Desde QDoc 6.3, cualquier argumento adicional que se pase al comando \include se utiliza para inyectar cadenas en el contenido incluido. Para inyectar una cadena en un lugar específico del contenido, añada una barra invertida seguida de un dígito (1..9). Los dígitos se corresponden con el orden de la lista de argumentos. Encierre los argumentos entre llaves para asegurarse de que QDoc muestra el argumento completo, incluidos los posibles caracteres de espacio en blanco, tal y como usted espera.

Por ejemplo, dado el siguiente fragmento en un archivo includes.qdocinc:

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

A continuación, la siguiente línea \include:

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

Renderiza

Para activar la salida detallada, seleccione 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 del atributo. Cada argumento debe ir entre llaves, 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}
*/

Algunos atributos de metadatos tienen una finalidad específica:

Ejemplo de metadatos

Otro uso del comando \meta es incluir metadatos (etiquetas) en la \example documentación. Por defecto, QDoc genera etiquetas de ejemplo basadas en el nombre del ejemplo \title y el nombre del módulo. Estas etiquetas se muestran en el modo de bienvenida de Qt Creator, ayudando 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 como resultado las siguientes etiquetas: tutorial,básico,hola,mundo. Las palabras comunes como ejemplo se ignoran.

Excluir ejemplos

Si marca un ejemplo como roto, lo excluirá del archivo de manifiesto generado, eliminándolo del modo de bienvenida de Qt Creator.

\meta {tag} {broken}

Rutas de instalación de ejemplos

El comando \meta combinado con un 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 archivo \class o un \qmltype. Esta descripción aparecerá en una tabla en la parte superior de la página de referencia del tipo.

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

Consulte también los comandos relacionados con el estado.

Metadatos del documento

Un argumento keywords para el comando \meta añade las palabras clave especificadas como metadatos para el 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 la lista anotada de clases C++ o tipos QML, que se genera automáticamente en la parte inferior de la página del módulo C++ o QML debe omitirse, porque las clases o tipos se han listado manualmente. Este comando también puede utilizarse con el comando \group para omitir la lista de miembros del grupo, cuando se enumeran manualmente.

El comando debe estar en su propia línea. Véase Qt Quick Controls QML Types para ver un ejemplo. La página se genera a partir de qtquickcontrols2-qmlmodule.qdoc. Allí encontrará 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 comando \generatelist para listar 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 puede aplicarse también a \example 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 partes de la documentación que se desea 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 de lenguaje de marcado en bruto.

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

QDoc genera el código dado sólo cuando genera el formato especificado por el usuario.

Por ejemplo, "\raw HTML" sólo generará código cuando QDoc genere documentación HTML.

\sincelist

El comando \sincelist se expande a un desglose detallado de las nuevas inclusiones a la API documentada en una versión especificada. Ejemplo de uso:

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

   \sincelist 6.11
*/

\sincelisttoma un único argumento, una cadena de versión. La salida generada incluye toda la funcionalidad marcada con un comando \since o una cláusula since que coincida con la cadena de versión.

\unicode

El comando \unicode permite insertar un carácter Unicode arbitrario en el documento.

El comando recibe 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 base 16 y 8, respectivamente).