Rédaction de la documentation

Commentaires QDoc

La documentation est contenue dans les commentaires QDoc, délimités par les commentaires /* ! et */. Notez que ces commentaires sont valables en C++ et en QML.

Dans un commentaire QDoc, //! est utilisé comme un commentaire de documentation d'une seule ligne ; le commentaire lui-même et tout ce qui suit, jusqu'à une nouvelle ligne, est omis dans la sortie générée.

QDoc analysera les fichiers C++ et QML à la recherche de commentaires QDoc. Pour omettre explicitement un certain type de fichier, il faut l'omettre dans le fichier de configuration.

Commandes de QDoc

QDoc utilise des commandes pour récupérer des informations sur la documentation. Les commandes Topic déterminent le type d'élément de documentation, les commandes context fournissent des conseils et des informations sur un sujet, et les commandes markup fournissent des informations sur la manière dont QDoc doit formater un élément de documentation.

Sujets de QDoc

Chaque commentaire QDoc doit avoir un type de sujet. Un sujet le distingue des autres sujets. Pour spécifier un type de sujet, utilisez l'une des commandes de sujet.

QDoc rassemblera les sujets similaires et créera une page pour chacun d'entre eux. Par exemple, toutes les énumérations, propriétés, fonctions et descriptions d'une classe C++ particulière seront regroupées dans une page. Une page générique est spécifiée à l'aide de la commande \page et le nom du fichier est l'argument.

Exemple de commandes de sujet :

• \enum - pour la documentation sur les énumérations
• \class - pour la documentation sur les classes C++
• \qmltype - pour la documentation sur les types QML
• \page - pour la création d'une page.

Plusieurs sujets

Un commentaire QDoc peut contenir plusieurs commandes de sujets dans la même catégorie, avec quelques restrictions. Ainsi, il est possible d'écrire un seul commentaire qui documente toutes les surcharges d'une fonction (à l'aide de plusieurs commandes \fn ), ou toutes les propriétés d'un groupe de propriétés QML (à l'aide de commandes \qmlproperty ) en une seule fois.

Si un commentaire QDoc contient plusieurs commandes de sujet, il est possible de fournir des commandes de contexte supplémentaires pour des sujets individuels dans des commentaires de suivi :

/*!
    \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 de suivi marque la propriété element.id en lecture seule, tandis que element.name reste accessible en écriture.

La page Commandes de thème contient des informations sur toutes les commandes de thème disponibles.

Contextes des thèmes

Les commandes de contexte donnent à QDoc un indice sur le contexte du sujet. Par exemple, si une fonction C++ est obsolète, elle doit être marquée comme telle avec la commande \deprecated pour l'indiquer. De même, la navigation et le titre de la page donnent à QDoc des informations supplémentaires sur la page.

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

La page Commandes contextuelles contient une liste de toutes les commandes contextuelles disponibles.

Balisage de la documentation

QDoc peut baliser du texte de la même manière que d'autres outils de balisage ou de documentation. QDoc peut marquer une section de texte en gras, lorsque le texte est marqué avec la commande \b commande.

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

La page Commandes de balisage contient une liste complète des commandes de balisage disponibles.

Anatomie de la documentation

Pour que QDoc puisse créer une page, certains ingrédients essentiels doivent être présents.

• Assigner un sujet à un commentaire QDoc - Un commentaire peut être une page, une documentation de propriété, une documentation de classe ou n'importe quelle commande de sujet disponible.
• Donner 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.
• Marquer des sections du document avec des commandes de balisage - QDoc peut créer des mises en page et formater la documentation pour la documentation.

Dans Qt, la classe QVector3D a été documentée avec le 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 possède un constructeur, QVector3D::QVector3D(), qui a été documenté avec 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 résider dans différents fichiers et QDoc les rassemblera en fonction de leur sujet et de leur contexte. La documentation résultant des 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, il n'est pas nécessaire qu'elle ait un sujet. QDoc considérera que la documentation située au-dessus du code est la documentation de ce code.

Un article est créé à l'aide de la commande \page commande. Le premier argument est le fichier HTML que QDoc va créer. Le sujet est complété par des commandes contextuelles, les commandes \title et \nextpage et des commandes de contexte. Il existe plusieurs autres commandes QDoc telles que la commande \list la commande

/*!
    \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 sur les commandes de sujets donne un aperçu de plusieurs autres types de sujets.