En esta página

Redacción de documentación

Comentarios sobre QDoc

La documentación se incluye en comentarios QDoc, delimitados por los símbolos /*! y */. Ten en cuenta que se trata de comentarios válidos en C++ y QML.

Dentro de un comentario QDoc, se utiliza « //! » como comentario de documentación de una sola línea; el comentario en sí y todo lo que le sigue, hasta un salto de línea, se omite en el resultado generado.

QDoc analizará los archivos C++ y QML en busca de comentarios QDoc. Para omitir explícitamente un tipo de archivo concreto, omítelo del archivo de configuración.

Comandos de QDoc

QDoc utiliza comandos para recuperar información sobre la documentación. Los comandos Topic determinan el tipo de elemento de documentación, los comandos context proporcionan sugerencias e información sobre un tema, y los comandos markup proporcionan información sobre cómo debe QDoc dar formato a una parte de la documentación.

Temas de QDoc

Cada comentario de QDoc debe tener un tipo de tema. El tema es lo que lo distingue de otros temas. Para especificar un tipo de tema, utiliza uno de los diversos comandos de tema.

QDoc recopilará los temas similares y creará una página para cada uno de ellos. Por ejemplo, todas las enumeraciones, propiedades, funciones y la descripción de una clase concreta de C++ se incluirán en una sola página. Una página genérica se especifica mediante el \page y el nombre del archivo es el argumento.

Ejemplo de comandos de tema:

  • \enum - para la documentación de enumeraciones
  • \class - para la documentación de clases de C++
  • \qmltype - para la documentación de tipos QML
  • \page - para crear una página.

Varios temas

Un comentario QDoc puede contener varios comandos de tema dentro de la misma categoría, con algunas restricciones. De esta forma, es posible escribir un único comentario que documente todas las sobrecargas de una función (utilizando varios \fn comandos), o todas las propiedades de un grupo de propiedades de QML (utilizando \qmlproperty comandos) de una sola vez.

Si un comentario QDoc contiene varios comandos de tema, es posible proporcionar comandos de contexto adicionales para temas concretos en comentarios posteriores:

/*!
    \qmlproperty string Type::element.name
    \qmlproperty int Type::element.id

    \brief Holds the element name and id.
*/

/*!
    \qmlproperty int Type::element.id
    \readonly
*/

En este caso, el comentario posterior marca la propiedad `element.id ` como de solo lectura, mientras que `element.name ` sigue siendo modificable.

Nota: Un comentario de seguimiento no puede contener texto adicional, solo comandos de contexto que documenten el contexto del elemento.

La página «Comandos de tema » contiene información sobre todos los comandos de tema disponibles.

Contextos de tema

Los comandos de contexto proporcionan a QDoc una indicación sobre el contexto del tema. Por ejemplo, si una función de C++ está en desuso, debe marcarse como tal con el \deprecated . Del mismo modo, la navegación por las páginas y el título de la página proporcionan información adicional a QDoc.

QDoc creará enlaces o páginas adicionales para estos contextos. Por ejemplo, se crea un grupo mediante el \group y los miembros se definen mediante el \ingroup . El nombre del grupo se proporciona como argumento.

La página «Comandos de contexto » contiene una lista de todos los comandos de contexto disponibles.

Marcado de documentación

QDoc permite formatear el texto de forma similar a otras herramientas de marcado o documentación. QDoc puede poner en negrita una sección de texto cuando esta se marca con el \b comando.

\b{This} text will be in \b{bold}.

La página «Comandos de formato » contiene una lista completa de los comandos de formato disponibles.

Estructura de la documentación

Básicamente, para que QDoc cree una página, deben estar presentes algunos elementos esenciales.

  • Asignar un tema a un comentario de QDoc: un comentario puede ser una página, la documentación de una propiedad, la documentación de una clase o cualquiera de los comandos de tema disponibles.
  • Asigna un contexto al tema: QDoc puede asociar determinados temas a otras páginas, como, por ejemplo, asociar elementos obsoletos cuando la documentación está marcada con \deprecated.
  • Marca secciones del documento con comandos de marcado: QDoc puede crear diseños y dar formato a la documentación.

En Qt, la clase ` QVector3D ` se documentó con el siguiente comentario de QDoc:

/*!
    \class QVector3D
    \brief The QVector3D class represents a vector or vertex in 3D space.
    \since 4.6
    \ingroup painting-3D

    Vectors are one of the main building blocks of 3D representation and
    drawing.  They consist of three coordinates, traditionally called
    x, y, and z.

    The QVector3D class can also be used to represent vertices in 3D space.
    We therefore do not need to provide a separate vertex class.

    \note By design values in the QVector3D instance are stored as \c float.
    This means that on platforms where the \c qreal arguments to QVector3D
    functions are represented by \c double values, it is possible to
    lose precision.

    \sa QVector2D, QVector4D, QQuaternion
*/

Tiene un constructor, QVector3D::QVector3D(), que se documentó con el siguiente comentario de QDoc:

/*!
    \fn QVector3D::QVector3D(const QPoint& point)

    Constructs a vector with x and y coordinates from a 2D \a point, and a
    z coordinate of 0.
*/

Los distintos comentarios pueden encontrarse en diferentes archivos y QDoc los recopilará en función de su tema y su contexto. La documentación resultante de los fragmentos se genera en la documentación de la clase ` QVector3D `.

Ten en cuenta que, si la documentación precede inmediatamente a la función o clase en el código fuente, no es necesario que tenga un tema. QDoc asumirá que la documentación situada encima del código es la documentación de ese código.

Un artículo se crea mediante el \page comando. El primer argumento es el archivo HTML que creará QDoc. El tema se complementa con comandos de contexto, como el \title y \nextpage . Existen otros comandos de QDoc, como el \list .

/*!
    \page generic-guide.html
    \title Generic QDoc Guide
    \nextpage Creating QDoc Configuration Files
    There are three essential materials for generating documentation with QDoc:

    \list
        \li \c QDoc binary (\c {qdoc})
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist
*/

La sección sobre comandos de temas ofrece una visión general de otros tipos de temas.

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