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 tiene la capacidad de dar formato a una página dependiendo del tipo. Además, las hojas de estilo pueden proporcionar un control adicional sobre la visualización de cada categoría.

Documentación API

QDoc sobresale en la creación de documentación API dado un conjunto de código fuente y documentación en comentarios QDoc. En concreto, QDoc conoce la arquitectura de Qt y puede validar la existencia de documentación de clases, funciones o propiedades de C++ de Qt. QDoc da advertencias y errores si no puede asociar una documentación con una entidad de código o si una entidad de código no tiene documentación.

En general, cada entidad de código Qt como propiedades, clases, métodos, señales y enumeraciones tienen 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 .h ) para construir un árbol de las estructuras de las clases. A continuación, QDoc analizará los archivos fuente y los archivos de documentación para asociar la documentación a la estructura de clases. Después, QDoc generará una página para la clase.

Estilos de lenguaje

Para producir una documentación de calidad de la API, las referencias de la API de Qt siguen unas pautas de lenguaje particulares. Mientras que el contenido de esta página demuestra cómo crear documentación de la API, las directrices de estilo demuestran cómo los materiales de referencia siguen un uso coherente del lenguaje.

• Estilo de documentación C
• Estilo de documentación QML

Documentación de tipos QML

En el mundo de QML, hay entidades adicionales que necesitamos documentar, como las señales QML, las propiedades adjuntas y los métodos QML. Internamente, utilizan tecnologías Qt, sin embargo, la documentación de la API QML requiere un diseño y unas convenciones de nomenclatura diferentes de la documentación de la API C++ de Qt.

Una lista de comandos QDoc relacionados con QML:

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - crea una documentación de tipo QML
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

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

Analizador sintáctico QML

Si su tipo QML está definido en un archivo qml, documéntelo allí. Si el tipo QML está representado por una clase C++, documéntelo en el archivo cpp de esa clase C++ e incluya un comando \nativetype para especificar el nombre de la clase C++. No documente un tipo QML en un archivo cpp si el tipo QML está definido en un archivo qml.

Cuando documente un tipo QML en un archivo qml, coloque cada comentario QDoc directamente encima de la entidad a la que se aplica el comentario. Por ejemplo, coloque el comentario QDoc que contiene el comando \qmltype (el comentario del tema) directamente encima del tipo QML externo en el archivo qml. Coloque el comentario para documentar una propiedad QML directamente encima de la declaración de la propiedad, y así sucesivamente para los manejadores de señales QML y los métodos QML. Tenga en cuenta que al documentar propiedades QML en un archivo qml, normalmente no se incluye el comando \qmlproperty como comando de tema (lo que debe hacer al documentar tipos QML en archivos cpp ), porque el analizador QML asocia automáticamente cada comentario QDoc con la siguiente declaración QML que analiza. Lo mismo ocurre con los comentarios de manejadores de señales QML y métodos QML. Pero a veces es útil incluir uno o más comandos \qmlproperty en el comentario, por ejemplo, cuando el tipo de propiedad es otro tipo QML y se desea que el usuario sólo utilice determinadas propiedades dentro de ese otro tipo QML, pero no todas. Pero cuando documente una propiedad que tiene un alias, coloque el comentario QDoc correspondiente directamente encima de la declaración del alias. En estos casos, el comentario QDoc debe contener un comando \qmlproperty porque es la única forma de que QDoc conozca el tipo de la propiedad con alias.

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

Módulos QML

Un tipo QML pertenece a un módulo. El módulo puede incluir todos los tipos relacionados para una plataforma o contener una versión determinada de Qt Quick. Por ejemplo, los tipos QML 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 comando \qmltype topic debe tener un comando \inqmlmodule comando context para relacionar el tipo con un módulo QML. Del mismo modo, un comando \qmlmodule comando topic debe existir en un archivo .qdoc separado para crear la página de resumen del módulo. La página de resumen enumerará 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 denominado TabWidget se encuentra en el módulo UIComponents, debe enlazarse como UIComponents::TabWidget.

Propiedades QML internas y de sólo lectura

QDoc detecta las propiedades QML marcadas como readonly. Tenga 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 comando \internal comando. QDoc no publicará la documentación en las salidas generadas.

Artículos y resúmenes

Los artículos y resúmenes son un estilo de escritura que se utiliza mejor para proporcionar detalles resumidos sobre un tema o concepto. Pueden presentar una tecnología o explicar cómo puede aplicarse un concepto, pero sin explicar los pasos exactos con demasiado detalle. Sin embargo, este tipo de contenido podría proporcionar el punto de entrada para que los lectores encuentren materiales instructivos y de referencia que sí lo hagan, como tutoriales, ejemplos y documentación de clase. Un ejemplo de visión general podría ser una página de producto, como una discusión de alto nivel sobre Qt Quick, módulos individuales, principios de diseño o herramientas.

Para indicar que un documento es un artículo, añada 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 de comandos de escritura de temas 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 determinada tecnología o concepto. Cuando se trata de middleware, esto suele ser en forma de una aplicación que utiliza código simple y explicaciones claras de lo que el código está haciendo. Todo módulo, API, proyecto, patrón, etc. debe tener al menos un buen ejemplo.

Un ejemplo puede ir acompañado de un tutorial. El tutorial instruye y describe el código, mientras que el ejemplo de código es el contenido del código que los usuarios pueden estudiar. Los ejemplos de código pueden ir acompañados de texto 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 encontrar el archivo Qt Project (.pro) para generar los archivos de ejemplo. El HTML generado tendrá el nombre de archivo, declarative-ui-components-tabwidget.html. QDoc también listará todo el código de ejemplo.