Commandes thématiques

Une commande de thème indique à QDoc quel élément du code source est documenté. Certaines commandes de thème vous permettent de créer des pages de documentation qui ne sont liées à aucun élément de code source sous-jacent.

Lorsque QDoc traite un commentaire QDoc, il tente de relier le commentaire à un élément du code source en recherchant d'abord une commande de rubrique qui nomme l'élément du code source. S'il n'y a pas de commande de sujet, QDoc essaie de relier le commentaire à l'élément du code source qui suit immédiatement le commentaire. S'il ne peut faire ni l'un ni l'autre et s'il n'y a pas de commande de thème indiquant que le commentaire n'a pas d'élément de code source sous-jacent (par ex. \page), le commentaire est rejeté.

Le nom de l'entité documentée est généralement le seul argument d'une commande topic. Utilisez le nom complet. Parfois, il peut y avoir un deuxième paramètre dans l'argument. Voir par exemple \page.

\enum QComboBox::InsertPolicy

La commande \fn est un cas particulier. Pour la commande \fn utilisez la signature de la fonction, y compris le qualificateur de classe.

\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)

Une commande de sujet peut apparaître n'importe où dans un commentaire, mais elle doit être indépendante sur sa propre ligne. Une bonne pratique consiste à placer la commande de sujet sur la première ligne du commentaire. Si l'argument s'étend sur plusieurs lignes, assurez-vous que chaque ligne (sauf la dernière) se termine par une barre oblique inverse. De plus, QDoc compte les parenthèses, ce qui signifie que s'il rencontre un '(', il considère comme argument tout ce qui se trouve jusqu'au ')' de fermeture.

Si une commande de thème est répétée avec des arguments différents, la même documentation apparaîtra pour les deux unités.

/*!
    \fn void PreviewWindow::setWindowFlags()
    \fn void ControllerWindow::setWindowFlags()

    Sets the widgets flags using the QWidget::setWindowFlags()
    function.

    Then runs through the available window flags, creating a text
    that contains the names of the flags that matches the flags
    parameter, displaying the text in the widgets text editor.
*/

Les fonctions PreviewWindow::setWindowFlags() et ControllerWindow::setWindowFlags() recevront la même documentation.

Nomenclature des fichiers générés par les commandes topic

Pour de nombreuses commandes thématiques, telles que \pageQDoc génère un fichier lors du traitement de la documentation.

QDoc normalise le nom de chaque fichier avant de l'écrire sur le disque. Les opérations suivantes sont effectuées :

• Toutes les séquences de caractères non alphanumériques sont remplacées par un trait d'union, '-'.
• Toutes les lettres majuscules sont remplacées par leur équivalent en minuscules.
• Tous les traits d'union de fin sont supprimés.

Par exemple, la commande suivante génère un fichier nommé this-generates-a-file-and-writes-it-to-disk.html:

\page this_generates_a_file_(and_writes_it_to_DISK)-.html

Comme le montre l'exemple, le nom donné au fichier dans la commande peut différer du nom du fichier réel qui est écrit sur le disque.

Préfixes et suffixes des fichiers générés

Lorsque QDoc génère un fichier, il peut ajouter un préfixe, un suffixe ou les deux, en fonction de l'élément que le fichier documentera.

Le tableau ci-dessous indique quels sont ces préfixes et suffixes pour différents éléments.

\class

La commande \class permet de documenter une classe C++, une structure C/C++ ou une union. L'argument est le nom complet et qualifié de la classe. La commande indique à QDoc qu'une classe fait partie de l'API publique et vous permet d'entrer une description détaillée.

/*!
    \class QMap::iterator
    \inmodule QtCore

    \brief The QMap::iterator class provides an STL-style
    non-const iterator for QMap and QMultiMap.

    QMap features both \l{STL-style iterators} and
    \l{Java-style iterators}. The STL-style iterators ...
*/

La documentation HTML de la classe nommée est écrite dans un fichier .html nommé à partir du nom de la classe, en minuscules, et avec les deux-points remplacés par "-". Par exemple, la documentation de la classe QMap::iterator est écrite dans le fichier qmap-iterator.html.

Le fichier contient la description de la classe à partir du commentaire \class, ainsi que la documentation générée à partir des commentaires QDoc pour tous les membres de la classe : une liste des types, des propriétés, des fonctions, des signaux et des emplacements de la classe.

En plus de la description détaillée de la classe, le commentaire \class contient généralement une commande \inmodule ainsi qu'une \brief description. Voici un exemple très simple :

/*!
    \class PreviewWindow
    \inmodule CustomWidgets
    \brief The PreviewWindow class is a custom widget.
           displaying the names of its currently set
           window flags in a read-only text editor.

    \ingroup miscellaneous

    The PreviewWindow class inherits QWidget. The widget
    displays the names of its window flags set with the \l
    {function} {setWindowFlags()} function. It is also
    provided with a QPushButton that closes the window.

    ...

    \sa QWidget
*/

La façon dont QDoc rend cette page \class dépend de votre fichier style.css.

\enum

La commande \enum permet de documenter un type d'énumération C++. L'argument est le nom complet du type enum.

Les valeurs de l'énumération sont documentées dans le commentaire \enum à l'aide de la commande \value pour documenter les valeurs de l'énumération. Si une valeur d'énumération n'est pas documentée avec \value, QDoc émet un avertissement. Ces avertissements peuvent être évités en utilisant la commande \omitvalue pour indiquer à QDoc qu'une valeur d'énumération ne doit pas être documentée. La documentation de l'enum sera incluse dans la page de référence de la classe, la page du fichier d'en-tête ou la page de l'espace de noms où le type enum est défini. Par exemple, considérons le type d'énumération Corner dans l'espace de noms Qt :

enum Corner {
    TopLeftCorner = 0x00000,
    TopRightCorner = 0x00001,
    BottomLeftCorner = 0x00002,
    BottomRightCorner = 0x00003
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
    ,TopLeft = TopLeftCorner,
    TopRight = TopRightCorner,
    BottomLeft = BottomLeftCorner,
    BottomRight = BottomRightCorner
#endif
};

Cette énumération peut être documentée de la manière suivante :

/*!
    \enum Qt::Corner

    This enum type specifies a corner in a rectangle:

    \value TopLeftCorner
           The top-left corner of the rectangle.
    \value TopRightCorner
           The top-right corner of the rectangle.
    \value BottomLeftCorner
           The bottom-left corner of the rectangle.
    \value BottomRightCorner
           The bottom-right corner of the rectangle.

    \omitvalue TopLeft
    \omitvalue TopRight
    \omitvalue BottomLeft
    \omitvalue BottomRight
               Bottom-right (omitted; not documented).
*/

Notez l'inclusion du qualificatif d'espace de noms.

Voir aussi \value et \omitvalue.

\example

La commande \example permet de documenter un exemple. L'argument est le chemin de l'exemple relatif à l'un des chemins répertoriés dans la variable exampledirs du fichier de configuration de QDoc.

La page de documentation sera produite au format modulename-path-to-example.html. QDoc ajoutera une liste de tous les fichiers sources et images de l'exemple à la fin de la page, sauf si la commande \noautolist ne soit utilisée ou que la variable de configuration url.examples ne soit définie pour le projet.

Par exemple, si exempledirs contient $QTDIR/examples/widgets/imageviewer, alors

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \subtitle

    The example shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

Voir aussi \noautolist, url.examples, \meta

\externalpage

La commande \externalpage attribue un titre à une URL externe.

/*!
    \externalpage http://doc.qt.io/
    \title Qt Documentation Site
*/

Cela vous permet d'inclure un lien vers la page externe dans votre documentation :

/*!
    At the \l {Qt Documentation Site} you can find the latest
    documentation for Qt, Qt Creator, the Qt SDK and much more.
*/

Pour obtenir le même résultat sans utiliser la commande \externalpage, vous devriez coder l'adresse en dur dans votre documentation :

/*!
    At the \l {http://doc.qt.io/}{Qt Documentation Site}
    you can find the latest documentation for Qt, Qt Creator, the Qt SDK
    and much more.
*/

La commande \externalpage facilite la mise à jour de la documentation. Si l'adresse change, il suffit de modifier l'argument de la commande \externalpage.

\fn (fonction)

La commande \fn permet de documenter une fonction. L'argument est la signature de la fonction, y compris ses paramètres de modèle (le cas échéant), son type de retour, son caractère constant et la liste des arguments formels avec leurs types. Si la fonction nommée n'existe pas, QDoc émet un avertissement.

La commande accepte auto comme type d'une fonction, même si le type complet peut être déduit par QDoc. Dans certaines situations, il peut être préférable d'utiliser auto au lieu du type réel d'une fonction. L'utilisation de auto comme type de retour dans la commande \fn permet à l'auteur de le faire explicitement, même pour les types définis sans le mot-clé auto.

Depuis la version 6.0 de QDoc, la commande \fn peut être utilisée pour documenter les membres de la classe qui ne sont pas explicitement déclarés dans l'en-tête, mais qui sont implicitement générés par le compilateur : constructeur et destructeur par défaut, constructeur de copie et constructeur de copie mobile, opérateur d'affectation et opérateur d'affectation mobile.

Lors de la documentation d'un ami caché, il est nécessaire de faire précéder le nom de la fonction du nom de la classe qui l'entoure. Par exemple, pour :

class Foo {
   ...
   friend bool operator==(const Foo&, const Foo&) { ... }
   ...
}

La commande doit être écrite sous la forme "\fn Foo::operator==(const Foo&, const Foo&)" et non sous la forme de la fonction libre "\fn operator==(const Foo&, const Foo&)".

Dans le cas contraire, QDoc se plaindra de l'impossibilité de résoudre la fonction.

/*!
    \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const

    Returns \c true if this toolbar is dockable in the given
    \a area; otherwise returns \c false.
*/

Voir aussi \overload.

\group

La commande \group crée une page distincte qui répertorie les classes, les pages ou d'autres entités appartenant à un groupe donné. L'argument est le nom du groupe.

Une classe est incluse dans un groupe à l'aide de la commande \ingroup pour inclure une classe dans un groupe. Les pages de présentation peuvent également être associées à un groupe à l'aide de la même commande, mais la liste des pages de présentation doit être demandée explicitement à l'aide de la commande \generatelist (voir l'exemple ci-dessous).

La commande \group est généralement suivie d'une commande \title et d'une brève présentation du groupe. La page HTML du groupe est écrite dans un fichier .html nommé <nom-du-groupe-en-bas-de-casse>.html.

Chaque entité du groupe est listée sous forme de lien (en utilisant le titre de la page ou le nom de la classe), suivi d'une description de la commande \brief dans la documentation de l'entité.

/*!
    \group io
    \title Input/Output and Networking
*/

QDoc génère une page de groupe io.html.

Notez que les pages de présentation liées au groupe doivent être listées explicitement à l'aide de la commande \generatelist avec l'argument related.

/*!
    \group architecture

    \title Architecture

    These documents describe aspects of Qt's architecture
    and design, including overviews of core Qt features and
    technologies.

    \generatelist{related}
*/

Voir aussi \ingroup, \annotatedlist, \generatelist, et \noautolist.

\headerfile

La commande \headerfile permet de documenter les fonctions globales, les types et les macros qui sont déclarés dans un fichier d'en-tête, mais pas dans un espace de noms. L'argument est le nom du fichier d'en-tête. La page HTML est écrite dans un fichier .html construit à partir de l'argument du fichier d'en-tête.

La documentation d'une fonction, d'un type ou d'une macro déclarée dans le fichier d'en-tête documenté est incluse dans la page du fichier d'en-tête à l'aide de la commande \relates pour l'inclure dans la page du fichier d'en-tête.

Si l'argument n'existe pas en tant que fichier d'en-tête, la commande \headerfile crée quand même une page de documentation pour le fichier d'en-tête.

/*!
   \headerfile <QtAlgorithms>

   \title Generic Algorithms

   \brief The <QtAlgorithms> header file provides
    generic template-based algorithms.

   Qt provides a number of global template functions in \c
   <QtAlgorithms> that work on containers and perform
   well-know algorithms.
*/

QDoc génère une page de fichier d'en-tête, qtalgorithms.html.

Voir aussi \inheaderfile.

\macro

La commande \macro permet de documenter une macro C++. L'argument est la macro dans l'un des trois styles suivants : macros de type fonction comme Q_ASSERT(), macros de type déclaration comme Q_PROPERTY(), et macros sans parenthèses comme Q_OBJECT.

Le commentaire \macro doit contenir une commande \relates qui attache le commentaire de la macro à une classe, un fichier d'en-tête ou un espace de noms. Dans le cas contraire, la documentation sera perdue.

\module

La commande \module crée une page qui répertorie les classes appartenant au module spécifié par l'argument de la commande. Une classe incluse dans le module en incluant la commande \inmodule dans le commentaire de \class.

La commande \module est généralement suivie d'un \title et d'une commande \brief et d'une commande Chaque classe est répertoriée sous la forme d'un lien vers la page de référence de la classe, suivi du texte de la commande \brief de la classe. Par exemple :

/*!
    \module QtNetwork

    \title Qt Network Module

    \brief Contains classes for writing TCP/IP clients and servers.

    The network module provides classes to make network
    programming easier and portable. It offers both
    high-level classes such as QNetworkAccessManager that
    implements application-level protocols, and
    lower-level classes such as QTcpSocket, QTcpServer, and
    QUdpSocket.
*/

La commande \noautolist peut être utilisée ici pour omettre la liste des classes générée automatiquement à la fin.

Voir aussi \inmodule

\namespace

La commande \namespace permet de documenter le contenu de l'espace de noms C++ désigné comme argument. La page de référence que QDoc génère pour un espace de noms est similaire à la page de référence qu'il génère pour une classe C++.

/*!
    \namespace Qt

    \brief Contains miscellaneous identifiers used throughout the Qt library.
*/

Notez qu'en C++, un espace de noms particulier peut être utilisé dans plus d'un module, mais lorsque des éléments C++ de différents modules sont déclarés dans le même espace de noms, l'espace de noms lui-même doit être documenté dans un seul module. Par exemple, l'espace de noms Qt dans l'exemple ci-dessus contient des types et des fonctions provenant à la fois de QtCore et de QtGui, mais il n'est documenté avec la commande \namespace que dans QtCore.

\page

La commande \page permet de créer une page de documentation autonome.

La commande \page attend un seul argument qui représente le nom du fichier dans lequel QDoc doit stocker la page.

Le titre de la page est défini à l'aide de la commande \title pour définir le titre de la page.

/*!
   \page aboutqt.html

   \title About Qt

   Qt is a C++ toolkit for cross-platform GUI
   application development. Qt provides single-source
   portability across Microsoft Windows, macOS, Linux,
   and all major commercial Unix variants.

   Qt provides application developers with all the
   functionality needed to build applications with
   state-of-the-art graphical user interfaces. Qt is fully
   object-oriented, easily extensible, and allows true
   component programming.

   ...
*/

QDoc rend cette page à l'adresse aboutqt.html.

\property

La commande \property permet de documenter une propriété Qt. L'argument est le nom complet de la propriété.

Une propriété est définie à l'aide de la macro Q_PROPERTY(). La macro prend comme arguments le nom de la propriété et ses fonctions set, reset et get.

Q_PROPERTY(QString state READ state WRITE setState)

Les fonctions set, reset et get n'ont pas besoin d'être documentées, il suffit de documenter la propriété. QDoc génère une liste des fonctions d'accès qui apparaîtront dans la documentation de la propriété, laquelle se trouvera à son tour dans la documentation de la classe qui définit la propriété.

Le commentaire de la commande \property comprend généralement une commande \brief commande. Pour les propriétés, l'argument de la commande \brief est un fragment de phrase qui sera inclus dans une description d'une ligne de la propriété. La commande suit les mêmes règles que la commande pour la description. \variable commande.

/*!
    \property QPushButton::flat
    \brief Whether the border is disabled.

    This property's default is false.
*/

\qmlattachedproperty

La commande \qmlattachedproperty permet de documenter une propriété QML qui sera attachée à un type QML. Voir Propriétés attachées. L'argument est le reste de la ligne. Il doit commencer par le type de propriété, suivi du nom du type QML dans lequel la propriété est déclarée, du qualificatif :: et enfin du nom de la propriété.

Par exemple, pour documenter une propriété booléenne QML attachée nommée isCurrentItem pour le type ListView:

/*!
    \qmlattachedproperty bool ListView::isCurrentItem

    This attached property is \c true if this delegate is the current
    item; otherwise false.

    It is attached to each instance of the delegate.

    This property may be used to adjust the appearance of the current
    item, for example:

    \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
*/

QDoc inclut cette propriété jointe dans la page de référence QML du type ListView.

\qmlattachedsignal

La commande \qmlattachedsignal permet de documenter un signal attachable. La commande \qmlattachedsignal s'utilise comme la commande \qmlsignal La commande s'utilise de la même manière que la commande

L'argument est le reste de la ligne. Il doit être composé du nom du type QML dans lequel le signal est déclaré, du qualificatif :: et enfin du nom du signal. Par exemple, un signal QML attaché nommé add() dans l'élément GridView est documenté comme suit :

/*!
    \qmlattachedsignal GridView::add()
    This attached signal is emitted immediately after an item is added to the view.
*/

QDoc inclut cette documentation dans la page de référence QML de l'élément GridView.

\qmlvaluetype

La commande \qmlvaluetype permet de documenter un type de valeur pour QML. La commande prend un nom de type comme seul argument.

\qmlvaluetypeest fonctionnellement identique à la commande \qmltype est fonctionnellement identique à la commande La seule différence est que le type sera intitulé (et groupé) comme un type de valeur QML.

\qmlclass

Cette commande est obsolète. Utilisez plutôt \qmltype à la place.

\qmlenum

La commande \qmlenum permet de documenter une énumération QML. La commande prend un seul argument : le nom complet du type d'énumération, y compris le type QML parent et, éventuellement, le module QML.

Les énumérateurs et leurs descriptions sont documentés à l'aide des commandes \value commandes.

Par exemple, la commande

/*!
    \qmlenum My.Module::Color::Channel
    \brief Specifies a color channel in the RGB colorspace.

    \value R
           Red color channel

    \value G
           Green color channel

    \value B
           Blue color channel
*/

Ceci génère de la documentation pour une énumération Channel, avec trois énumérateurs : Color.R, Color.G et Color.B. Par défaut, le nom du type QML parent est utilisé comme préfixe pour les énumérateurs.

Si le premier argument de la commande qdoccmd{valeur} comprend déjà un préfixe, il est utilisé tel quel :

\value Channel.R
       Red color channel
\value Channel.G
       Green color channel
\value Channel.B
       Blue color channel

Ici, les énumérateurs sont répertoriés sous les noms Channel.R, Channel.G et Channel.B.

Il est également possible de reproduire la documentation des énumérateurs à partir d'un sujet C++ existant, en utilisant la commande \enum en utilisant la commande \qmlenumeratorsfrom à l'aide de la commande

Cette commande a été introduite avec Qt 6.10.

Voir aussi \qmlenumeratorsfrom.

\qmlmethod

La commande \qmlmethod permet de documenter une méthode QML. L'argument est la signature complète de la méthode, y compris le type de retour et les noms et types des paramètres.

/*!
    \qmlmethod void TextInput::select(int start, int end)

    Causes the text from \a start to \a end to be selected.

    If either start or end is out of range, the selection is not changed.

    After having called this, selectionStart will become the lesser, and
    selectionEnd the greater (regardless of the order passed to this method).

   \sa selectionStart, selectionEnd
*/

QDoc inclut cette documentation dans la page de référence de l'élément TextInput.

\qmltype

La commande \qmltype permet de documenter un type QML. La commande a un argument, qui est le nom du type QML.

Si le type QML a une classe C++ équivalente, vous pouvez spécifier cette classe avec la commande \nativetype context.

La commande \inqmlmodule documente le module QML auquel le type appartient. L'argument transmis à cette commande doit correspondre à une page documentée. \qmlmodule documentée.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

Ici, le \qmltype commentaire inclut \nativetype pour spécifier qu'un Transform est la contrepartie QML de la classe C++ QGraphicsTransform. Un commentaire \qmltype doit toujours inclure une commande \since car tous les types QML sont nouveaux. Il doit également inclure une \brief description. Si un type QML est membre d'un groupe de types QML, le commentaire \qmltype doit inclure une ou plusieurs commandes. \ingroup commandes.

\qmlsingletontype

La commande \qmlsingletontype permet de documenter explicitement un type singleton QML. Cette commande est fonctionnellement identique à \qmltypemais elle marque explicitement le type comme étant un singleton, quelle que soit l'implémentation C++.

Un type QML singleton garantit qu'une seule instance existe dans le moteur QML. La désignation singleton est affichée dans la documentation générée avec un indicateur "(Singleton)" dans le titre et une note explicative.

/*!
    \qmlsingletontype Settings
    \inqmlmodule MyApp

    \brief Provides application-wide settings as a singleton.

    The Settings type is a singleton that maintains application
    configuration. Access it directly without instantiation.
*/

Pour les classes C++ qui utilisent la macro QML_SINGLETON, préférez l'utilisation de \qmltype car QDoc détectera automatiquement la nature singleton du code C++.

\qmlproperty

La commande \qmlproperty permet de documenter une propriété QML. L'argument est le reste de la ligne. Le texte de l'argument doit être le type de propriété, suivi du nom du type QML, du qualificatif :: et enfin du nom de la propriété. Si nous avons une propriété QML nommée x dans le type QML Translate, et que la propriété a le type real, la commande \qmlproperty pour cette propriété ressemblerait à ceci :

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

QDoc inclut cette propriété QML dans la page de référence QML du type Translate.

La commande \default est utilisée pour documenter la valeur par défaut d'une propriété :

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

Si la propriété QML expose un enum C++, la propriété QML est définie avec le type enumeration:

\qmlproperty enumeration ParticleShape3D::ShapeType

Les propriétés de type énumération et celles qui contiennent une combinaison bit à bit de drapeaux peuvent utiliser la commande \value pour documenter les valeurs acceptables.

\qmlproperty enumeration Buffer::textureFilterOperation
Specifies the texture filtering mode...
\value Buffer.Nearest Use nearest-neighbor filtering.

QDoc accepte également un nom de propriété entièrement qualifié, y compris l'identifiant du module QML :

\qmlproperty bool QtQuick.Controls::Button::highlighted

S'il est spécifié, l'identifiant du module (ci-dessus, QtQuick.Controls) doit correspondre à la valeur transmise à la commande \inqmlmodule dans la documentation \qmltype associée. Si le nom du type QML auquel la propriété appartient est unique pour tous les types du projet de documentation, l'identifiant du module peut être omis.

\qmlsignal

La commande \qmlsignal permet de documenter un signal QML. L'argument est le reste de la ligne. Les arguments doivent être : le type QML dans lequel le signal est déclaré, le qualificateur :: et enfin le nom du signal. Si nous avons un signal QML nommé clicked(), la documentation pour ce signal ressemblerait à ceci :

/*!
    \qmlsignal MouseArea::clicked(MouseEvent mouse)

    This signal is emitted when there is a click. A click is defined as a
    press followed by a release, both inside the MouseArea.
*/

QDoc inclut cette documentation sur la page de référence QML pour le type MouseArea.

\qmlmodule

Utilisez la commande \qmlmodule pour créer une page de module QML. Une page de module QML est une collection de types QML ou de tout autre matériel connexe. La commande prend un argument facultatif de numéro <VERSION> et est similaire à la commande group.

Un type QML est associé à un module en ajoutant la commande \inqmlmodule au bloc de commentaires qui documente le type. Vous pouvez établir un lien avec n'importe quel membre d'un module QML en utilisant le nom du module et le préfixe de deux points (::).

/*!
    A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
*/

QDoc génère une page pour le module qui répertorie tous les membres du module.

/*!
    \qmlmodule ClickableComponents

    This is a list of the Clickable Components set. A Clickable component
    responds to a \c clicked() event.
*/

\inqmlmodule

Un type QML est marqué comme étant disponible sous une importation de module QML spécifique en insérant la commande \inqmlmodule dans une rubrique. \qmltype dans un sujet. La commande prend comme seul argument le nom du module (import), sans numéro de version.

Le nom du module QML doit correspondre à un module QML documenté avec la commande (\qmlmodule ).

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

    A clickable button that responds to the \c click() event.
*/

QDoc affiche une ligne Déclaration d'importation : import <qmlmodule> dans un tableau en haut de la page de référence du type QML.

Lors de la création de liens vers des types QML, l'identifiant du module QML peut apparaître dans la cible du lien. Par exemple, l'identifiant du module QML peut apparaître dans la cible du lien :

\l {ClickableComponents::}{ClickableButton}

Lien vers la page de référence du type, avec ClickableButton comme texte du lien.

\instantiates

La commande \instantiates est obsolète depuis Qt 6.8. Utilisez plutôt \nativetype à la place.

\nativetype

La commande \nativetype doit être utilisée en conjonction avec la commande \qmltype topic. La commande prend une classe C++ comme argument. Si QDoc ne trouve pas la classe C++, il émet un avertissement. Cette commande a été introduite avec Qt 6.8.

Utilisez la commande \nativetype- pour spécifier le nom du type en C++. Cela garantit que le bloc de réquisitions généré dans la documentation pour le type QML contient une entrée "In C++". La classe C++ aura une entrée correspondante "In QML".

Un type QML ne peut avoir qu'un seul type natif. QDoc émet un avertissement en cas de redéfinition. Cependant, plusieurs types QML peuvent avoir la même classe C++ comme type natif. La documentation de la classe C++ contiendra une liste de tous les types correspondants en QML.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

Ici, la rubrique \qmltype sujet inclut \nativetype pour spécifier qu'une transformation est appelée QGraphicsTransform en C++.

\typealias

La commande \typealias est similaire à \typedefmais spécifique à la documentation d'un alias de type C++ :

class Foo
{
public:
    using ptr = void*;
// ...
}

Celui-ci peut être documenté comme suit

/*!
    \typealias Foo::ptr
*/

La commande \typealias a été introduite dans QDoc 5.15.

Voir aussi \typedef.

\typedef

La commande \typedef permet de documenter un typedef C++. L'argument est le nom du typedef. La documentation du typedef sera incluse dans la documentation de référence de la classe, de l'espace de noms ou du fichier d'en-tête dans lequel le typedef est déclaré. Pour relier le site \typedef à une classe, un espace de noms ou un fichier d'en-tête, le commentaire \typedef doit contenir une commande \relates commande.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

Les autres définitions de type se trouvent sur la page de référence de la classe qui les définit.

/*!
    \typedef QList::Iterator

    Qt-style synonym for QList::iterator.
*/

Voir aussi \typealias.

\variable

La commande \variable permet de documenter une variable membre de la classe ou une constante. L'argument est le nom de la variable ou de la constante. Le commentaire de la commande \variable comprend une commande \brief commande. QDoc génère la documentation en se basant sur le texte de la commande \brief.

La documentation se trouve dans la documentation de la classe, du fichier d'en-tête ou de l'espace de noms associé.

Dans le cas d'une variable membre :

/*!
    \variable QStyleOption::palette
    \brief The palette that should be used when painting
           the control
*/

Vous pouvez également documenter les constantes à l'aide de la commande \variable. Par exemple, supposons que vous ayez les constantes Type et UserType dans la classe QTreeWidgetItem:

enum { Type = 0, UserType = 1000 };

Pour ces constantes, la commande \variable peut être utilisée de la manière suivante :

/*!
    \variable QTreeWidgetItem::Type

    The default type for tree widget items.

    \sa UserType, type()
*/

/*!
    \variable QTreeWidgetItem::UserType

    The minimum value for custom types. Values below
    UserType are reserved by Qt.

    \sa Type, type()
*/