Rédaction de la documentation

Commentaires QDoc

La documentation est contenue dans des commentaires QDoc, délimités par les balises /*! et */. Notez qu'il s'agit de commentaires valides en C++ et en QML.

Dans un commentaire QDoc, la commande « //! » sert à créer un commentaire de documentation sur une seule ligne ; le commentaire lui-même et tout ce qui le suit, jusqu'à un retour à la ligne, sont omis de la sortie générée.

QDoc analyse les fichiers C++ et QML à la recherche de commentaires QDoc. Pour exclure explicitement un certain type de fichier, ne l'incluez pas dans le fichier de configuration.

Commandes QDoc

QDoc utilise des commandes pour récupérer des informations sur la documentation. Les commandes Topic permettent de déterminer le type d’élément de documentation, les commandes context fournissent des indications et des informations sur un sujet, et les commandes markup indiquent à QDoc comment formater un élément de documentation.

Rubriques QDoc

Chaque commentaire QDoc doit avoir un type de rubrique. Une rubrique permet de le distinguer des autres rubriques. Pour spécifier un type de rubrique, utilisez l'une des différentes commandes de rubrique.

QDoc regroupera les thèmes similaires et créera une page pour chacun d’entre eux. Par exemple, toutes les énumérations, propriétés, fonctions et la description d’une classe C++ donnée figureront sur une seule et même page. Une page générique est spécifiée à l’aide de la \page commande, le nom de fichier servant d'argument.

Exemple de commandes de rubrique :

• \enum - pour la documentation d'une énumération
• \class - pour la documentation des classes C++
• \qmltype - pour la documentation des types QML
• \page - pour créer une page.

Plusieurs rubriques

Un commentaire QDoc peut contenir plusieurs commandes de rubrique dans la même catégorie, sous réserve de certaines restrictions. De cette manière, il est possible d'écrire un seul commentaire qui documente toutes les surcharges d'une fonction (à l'aide de plusieurs \fn commandes), ou toutes les propriétés d’un groupe de propriétés QML (à l’aide de \qmlproperty commandes) en une seule fois.

Si un commentaire QDoc contient plusieurs commandes de rubrique, il est possible de fournir des commandes de contexte supplémentaires pour des rubriques individuelles dans des commentaires suivants :

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

    \brief Holds the element name and id.
*/

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

Ici, le commentaire suivant marque la propriété ` element.id ` comme étant en lecture seule, tandis que `element.name ` reste modifiable.

La page Commandes de rubrique contient des informations sur toutes les commandes de rubrique disponibles.

Contextes de rubrique

Les commandes de contexte fournissent à QDoc des indications sur le contexte de la rubrique. Par exemple, si une fonction C++ est obsolète, elle doit être signalée comme telle à l'aide de la \deprecated . De même, la navigation entre les pages et le titre de la page fournissent des informations supplémentaires à QDoc.

QDoc créera des liens ou des pages supplémentaires pour ces contextes. Par exemple, un groupe est créé à l’aide de la \group commande et ses membres sont créés à l’aide de la \ingroup commande. Le nom du groupe est fourni en argument.

La page « Commandes de contexte » répertorie toutes les commandes de contexte disponibles.

Balisage de la documentation

QDoc permet de baliser du texte de la même manière que d’autres outils de balisage ou de documentation. QDoc peut mettre une section de texte en gras lorsque celle-ci est balisée avec la \b commande.

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

La page « Commandes de mise en forme » présente la liste complète des commandes de mise en forme disponibles.

Structure de la documentation

En substance, pour que QDoc puisse créer une page, certains éléments essentiels doivent être présents.

• Attribuer un sujet à un commentaire QDoc : un commentaire peut correspondre à une page, à la documentation d’une propriété, à la documentation d’une classe ou à n’importe quelle commande de sujet disponible.
• Attribuer un contexte au sujet : QDoc peut associer certains sujets à d’autres pages, par exemple en associant des éléments obsolètes lorsque la documentation est marquée avec \deprecated.
• Marquez des sections du document à l'aide de commandes de balisage: QDoc peut créer des mises en page et formater la documentation.

Dans Qt, la classe QVector3D a été documentée à l'aide du commentaire QDoc suivant :

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

Elle dispose d'un constructeur, QVector3D::QVector3D(), qui était documenté par le commentaire QDoc suivant :

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

Les différents commentaires peuvent se trouver dans des fichiers distincts et QDoc les regroupe en fonction de leur sujet et de leur contexte. La documentation résultant de ces extraits est générée dans la documentation de la classe ` QVector3D `.

Notez que si la documentation précède immédiatement la fonction ou la classe dans le code source, elle n’a pas besoin d’avoir de rubrique. QDoc supposera que la documentation située au-dessus du code correspond à la documentation de ce code.

Un article est créé à l'aide de la \page commande. Le premier argument est le fichier HTML que QDoc va créer. Le sujet est complété par des commandes de contexte, à savoir les commandes \title et \nextpage . Il existe plusieurs autres commandes QDoc, telles que la \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 section consacrée aux commandes de rubrique donne un aperçu de plusieurs autres types de rubriques.