En esta página

Categorías de documentación

Existen varios tipos de categorías o tipos de documentación predefinidos:

  • Artículo
  • Documentación de la API de C++
  • Documentación de tipos QML
  • Ejemplo de código

QDoc permite dar formato a una página en función del tipo. Además, las hojas de estilo pueden ofrecer un control adicional sobre la visualización de cada categoría.

Documentación de la API

QDoc destaca en la creación de documentación de la API a partir de un conjunto de código fuente y documentación en los comentarios de QDoc. En concreto, QDoc conoce la arquitectura de Qt y puede validar la existencia de documentación sobre clases, funciones o propiedades de Qt C++. QDoc muestra advertencias y errores si no puede asociar una documentación a una entidad de código o si una entidad de código carece de documentación.

En general, cada entidad de código de Qt —como propiedades, clases, métodos, señales y enumeraciones— tiene un comando de tema correspondiente. QDoc asociará la documentación al código fuente utilizando las reglas de nomenclatura de C++.

QDoc analizará los archivos de cabecera (normalmente archivos ` .h `) para construir un árbol de las estructuras de clases. A continuación, QDoc analizará los archivos fuente y los archivos de documentación para adjuntar la documentación a la estructura de clases. Posteriormente, QDoc generará una página para la clase.

Nota: QDoc utiliza los archivos de cabecera para obtener información sobre la clase y no procesará correctamente los comentarios de QDoc en dichos archivos.

Estilos lingüísticos

Para producir documentación de la API de calidad, las referencias de la API de Qt siguen unas directrices lingüísticas específicas. Si bien el contenido de esta página muestra cómo crear documentación de la API, las directrices de estilo ilustran cómo los materiales de referencia mantienen un uso coherente del lenguaje.

Documentación de tipos QML

En el mundo de QML, hay entidades adicionales que debemos documentar, como las señales QML, las propiedades asociadas y los métodos QML. Aunque internamente utilizan tecnologías de Qt, la documentación de la API de QML requiere un diseño y unas convenciones de nomenclatura diferentes a las de la documentación de la API de Qt en C++.

Lista de comandos de QDoc relacionados con QML:

Nota: Recuerda habilitar el análisis sintáctico de QML incluyendo el tipo de archivo « *.qml » en la variable «fileextension ».

Para documentar un tipo QML, empieza por crear un comentario QDoc que utilice el \qmltype como comando de tema.

Analizador de QML

Si tu tipo QML está definido en un archivo qml, documéntalo allí. Si tu tipo QML está representado por una clase de C++, documéntalo en el archivo cpp correspondiente a esa clase de C++ e incluye un \nativetype comando para especificar el nombre de la clase C++. No documentes un tipo QML en un archivo cpp si dicho tipo está definido en un archivo qml.

Al documentar un tipo QML en un archivo qml, coloca cada comentario QDoc directamente encima de la entidad a la que se aplica el comentario. Por ejemplo, coloca el comentario QDoc que contiene el \qmltype comando (el comentario de tema) justo encima del tipo QML exterior en el archivo qml. Coloca el comentario para documentar una propiedad QML justo encima de la declaración de la propiedad, y así sucesivamente para los controladores de señales QML y los métodos QML. Ten en cuenta que, al documentar propiedades QML en un archivo qml, normalmente no se incluye el \qmlproperty como comando de tema (lo cual sí hay que hacer al documentar tipos QML en archivos C++ ), ya que el analizador de QML asocia automáticamente cada comentario QDoc con la siguiente declaración QML que analiza. Lo mismo ocurre con los comentarios de los controladores de señales QML y los métodos QML. Sin embargo, a veces resulta útil incluir uno o varios \qmlproperty comandos en el comentario, por ejemplo, cuando el tipo de propiedad es otro tipo QML y se desea que el usuario utilice solo determinadas propiedades dentro de ese otro tipo QML, pero no todas. No obstante, al documentar una propiedad que tiene un alias, coloca el comentario QDoc correspondiente directamente encima de la declaración del alias. En estos casos, el comentario QDoc debe contener un \qmlproperty comando, ya que esa es la única forma en que QDoc puede saber el tipo de la propiedad a la que hace referencia el alias.

Al documentar un tipo QML en el archivo cpp de su clase C++ correspondiente (si la tiene), normalmente se coloca cada comentario QDoc directamente encima de la entidad que documenta. Sin embargo, QDoc no utiliza el analizador de QML para analizar estos archivos (se utiliza el analizador de C++), por lo que estos comentarios QDoc de QML pueden aparecer en cualquier parte del archivo cpp. Ten en cuenta que los comentarios QDoc de QML en los archivos cpp deben utilizar los comandos «topic» de QML; es decir, el \qmltypedebe aparecer en el comentario QDoc del tipo QML, y un \qmlpropertydebe aparecer en cada comentario QDoc de propiedad QML.

Módulos QML

Un tipo QML pertenece a un módulo. El módulo puede incluir todos los tipos relacionados con una plataforma o contener una versión determinada de Qt Quick. Por ejemplo, los tipos QML de « Qt Quick 2» pertenecen al módulo « Qt Quick 2», mientras que también existe un módulo « Qt Quick 1» para los tipos más antiguos introducidos en Qt 4.

Los módulos QML permiten agrupar tipos QML. El \qmltype comando «topic» debe incluir un \inqmlmodule comando «context» para relacionar el tipo con un módulo QML. Del mismo modo, un \qmlmodule comando «topic» debe existir en un archivo « .qdoc » independiente para crear la página de resumen del módulo. La página de resumen mostrará una lista de los tipos QML del módulo QML.

Por lo tanto, los enlaces a los tipos QML también deben contener el nombre del módulo. Por ejemplo, si un tipo llamado « TabWidget » se encuentra en el módulo « UIComponents », debe enlazarse como « UIComponents::TabWidget ».

Propiedades QML de solo lectura e internas

QDoc detecta las propiedades QML marcadas como « readonly ». Ten en cuenta que la propiedad debe inicializarse con un valor.

readonly property int sampleReadOnlyProperty: 0

Las propiedades y señales que no están destinadas a la interfaz pública pueden marcarse con el \internal . QDoc no publicará la documentación en los resultados generados.

Artículos y descripciones generales

Los artículos y las descripciones generales son un estilo de redacción que resulta ideal para ofrecer un resumen detallado sobre un tema o concepto. Pueden presentar una tecnología o analizar cómo se puede aplicar un concepto, pero sin entrar en demasiados detalles sobre los pasos exactos. Sin embargo, este tipo de contenido puede servir de punto de partida para que los lectores encuentren materiales didácticos y de referencia que sí lo hagan, como tutoriales, ejemplos y documentación de clases. Un ejemplo de resumen podría ser una página de producto, como una descripción general de Qt Quick, módulos individuales, principios de diseño o herramientas.

Para indicar que un documento es un artículo, hay que añadir la palabra clave «article» al comando \page:

/*!
    \page overview-qt-technology.html
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

La sección «Comandos de temas de redacción » contiene una lista de los argumentos disponibles para el comando \page.

Ejemplos de código

Los ejemplos son una forma eficaz de demostrar el uso práctico de una tecnología o un concepto determinado. En lo que respecta al middleware, suelen presentarse en forma de una aplicación que utiliza código sencillo y explicaciones claras de lo que hace dicho código. Cualquier módulo, API, proyecto, patrón, etc., debería contar con al menos un buen ejemplo.

Un ejemplo puede ir acompañado de un tutorial. El tutorial explica y describe el código, mientras que el ejemplo de código es el contenido que los usuarios pueden estudiar. Los ejemplos de código pueden incluir texto adicional que no aparece en el tutorial.

QDoc creará una página que contenga el código de ejemplo con una descripción utilizando el comando \example comando.

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc utilizará el directorio especificado en la variable de entrada `exampledirs` para buscar el archivo del proyecto Qt (.pro) con el que generar los archivos de ejemplo. El HTML generado tendrá el nombre de archivo declarative-ui-components-tabwidget.html. QDoc también mostrará una lista con todo el código de ejemplo.

Nota: El archivo de proyecto del ejemplo debe coincidir con el nombre del directorio.

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