Escribir documentación

Comentarios sobre QDoc

La documentación está contenida dentro de comentarios QDoc, delimitados por comentarios /*! y */. Tenga en cuenta que estos comentarios son válidos en C++ y QML.

Dentro de un comentario QDoc, //! se utiliza como comentario de documentación de una sola línea; el propio comentario y todo lo que le sigue, hasta una nueva línea, se omite en la salida generada.

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

Comandos de QDoc

QDoc utiliza comandos para obtener 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 QDoc debe dar formato a un elemento de documentación.

Temas de QDoc

Cada comentario de QDoc debe tener un tipo de tema. Un tema lo distingue de otros temas. Para especificar un tipo de tema, utilice uno de los varios comandos de tema.

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

Ejemplo de comandos de temas:

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

Múltiples temas

Un comentario QDoc puede contener múltiples comandos de temas de la misma categoría, con algunas restricciones. De este modo, es posible escribir un único comentario que documente todas las sobrecargas de una función (utilizando múltiples \fn comandos), o todas las propiedades de un grupo de propiedades 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 individuales 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
*/

Aquí, el comentario de seguimiento marca la propiedad element.id como de sólo lectura, mientras que element.name sigue siendo de escritura.

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

Contextos de temas

Los comandos de contexto dan a QDoc una pista sobre el contexto del tema. Por ejemplo, si una función C++ está obsoleta, debe marcarse como tal con el comando \deprecated . Del mismo modo, la navegación por la página 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 con el comando \group y los miembros tienen el comando \ingroup comando. El nombre del grupo se suministra como argumento.

La página Comandos contex tuales contiene una lista de todos los comandos contextuales disponibles.

Documentación

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

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

La página Comandos de marcado contiene una lista completa de los comandos de marcado disponibles.

Anatomía de la documentación

Esencialmente, para que QDoc cree una página, deben estar presentes algunos ingredientes esenciales.

• Asignar un tema a un comentario de QDoc - Un comentario puede ser una página, una documentación de propiedades, una documentación de clases, o cualquiera de los comandos de tema disponibles.
• Dar al tema un contexto - QDoc puede asociar ciertos temas a otras páginas como por ejemplo asociar elementos obsoletos cuando la documentación está marcada con \deprecated.
• Marcar secciones del documento con comandos de marcado - QDoc puede crear diseños y formatear la documentación para la documentación.

En Qt, la clase QVector3D se documentó con el siguiente comentario 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 fue documentado con el siguiente comentario 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 diferentes comentarios pueden residir en diferentes archivos y QDoc los recogerá dependiendo 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, entonces no necesita tener un tema. QDoc asumirá que la documentación sobre el código es la documentación para ese código.

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

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