Commandes par rubrique

Une commande de rubrique indique à QDoc quel élément de code source est en cours de documentation. Certaines commandes de rubrique 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 ce commentaire à un élément du code source en recherchant d'abord une commande de rubrique qui nomme cet élément. S'il n'y a pas de commande de rubrique, QDoc tente de relier le commentaire à l'élément de code source qui suit immédiatement ce commentaire. S’il ne parvient à effectuer aucune de ces deux opérations et s’il n’existe aucune commande de rubrique indiquant que le commentaire n’a pas d’élément de code source sous-jacent (par exemple \page), alors le commentaire est ignoré.

Le nom de l’entité documentée est généralement le seul argument d’une commande de rubrique. Utilisez le nom complet. Il arrive parfois qu’un deuxième paramètre soit présent dans l’argument. Voir par exemple \page.

\enum QComboBox::InsertPolicy

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

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

Une commande de rubrique peut apparaître n'importe où dans un commentaire, mais doit figurer seule sur une ligne distincte. Il est recommandé de placer la commande de rubrique en première ligne du commentaire. Si l'argument s'étend sur plusieurs lignes, veillez à ce que chaque ligne (à l'exception de la dernière) se termine par une barre oblique inversée. De plus, QDoc compte les parenthèses, ce qui signifie que s’il rencontre un « ( », il considère tout ce qui suit jusqu’à la parenthèse fermante « ) » comme son argument.

Si une commande de rubrique est répétée avec des arguments différents, la même documentation s'affichera 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() afficheront la même documentation.

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

Pour de nombreuses commandes « topic », telles que \page, QDoc génère un fichier lors du traitement de la documentation.

QDoc normalise le nom de chaque fichier avant de l'enregistrer 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 tiret, « - ».
• Toutes les lettres majuscules sont remplacées par leur équivalent en minuscules.
• Tous les tirets 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 attribué 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 est censé documenter.

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

\class

La commande ` \class ` sert à documenter une classe C++, une structure C/C++ ou une union. L’argument est le nom complet et qualifié de la classe. Cette commande indique à QDoc qu’une classe fait partie de l’API publique et vous permet de saisir 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 en question est enregistrée dans un fichier ` .html ` dont le nom correspond à celui de la classe, en minuscules, les doubles deux-points étant remplacés par des tirets « - ». Par exemple, la documentation de la classe ` QMap::iterator ` est enregistrée dans le fichier ` qmap-iterator.html`.

Le fichier contient la description de la classe issue 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, propriétés, fonctions, signaux et slots de la classe.

Outre la description détaillée de la classe, le commentaire \class contient généralement une \inmodule commande, 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 manière dont QDoc affiche cette \class dépend de votre fichier d'style.css.

\concept

La commande ` \concept ` crée une page distincte pour chaque concept C++20 et regroupe les types et fonctions documentés dont les contraintes de modèle y font référence. L’argument est le nom entièrement qualifié du concept, correspondant au nom rapporté par Clang pour la déclaration. Les concepts au niveau du fichier utilisent leur nom simple ; les concepts situés dans un espace de noms nécessitent le nom entièrement qualifié, tel que ` algorithms::Ordered`.

Un type ou une fonction est automatiquement ajouté à la page d'un concept. Lorsque QDoc analyse une déclaration documentée, il examine les contraintes de la déclaration et enregistre celle-ci auprès des concepts auxquels elles font référence. Aucune commande de type \ingroup ou \inmodule n'est requise sur l'élément contraint lui-même.

QDoc reconnaît les trois formes syntaxiques des contraintes C++20 :

• Une clause requires explicite, qu'elle apparaisse dans l'en-tête du modèle (template <typename T> requires Ordered<T>) ou à la fin de la signature de la fonction.
• Un paramètre d’ auto contraint (void sort(Ordered auto& range)).
• Un concept appliqué directement à un paramètre de modèle (template <Ordered T> class SortedSet).

La commande « \concept » est généralement suivie d’une \inmodule commande et d’une \brief description. Le corps du commentaire est affiché comme description détaillée ; \section1 les titres fonctionnent comme sur n'importe quelle autre page de documentation.

/*!
    \concept Ordered
    \inmodule Algorithms

    \brief A type that admits a total order.

    The Ordered concept is satisfied by any type that supplies the
    relational operators \c {<}, \c {<=}, \c {>}, and \c {>=}, and for
    which those operators induce a strict total order.

    \section1 Definition

    Ordered evaluates to \c true when \c {T} is totally ordered
    and to \c false otherwise.
*/

QDoc génère une page de référence pour le concept. Pour l’exemple ci-dessus, la page est ordered.html; elle contient le résumé, la description détaillée et une section « Utilisé par » répertoriant les types et fonctions documentés inclus dans la documentation générée dont les contraintes font référence à Ordered. Chaque entrée est affichée sous forme de lien suivi de la description « \brief » issue de la documentation propre à l’entrée, selon le même format que les listes figurant sur les pages \group et \module.

Les références à des concepts non documentés, tels que ceux présents dans la bibliothèque standard, sont ignorées sans avertissement. Elles ne génèrent pas de page et ne déclenchent pas d’avertissement.

Voir aussi \group, \module, et \inmodule.

\enum

La commande ` \enum ` sert à documenter un type énuméré C++. L'argument est le nom complet du type énuméré.

Les valeurs de l'énumération sont documentées dans le commentaire « \enum » à l'aide de la \value . Si une valeur d’énumération n’est pas documentée avec ` \value`, QDoc génère un avertissement. Ces avertissements peuvent être évités en utilisant la \omitvalue commande pour indiquer à QDoc qu’une valeur d’énumération ne doit pas être documentée. La documentation de l’énumération sera incluse sur la page de référence de la classe, du fichier d’en-tête ou de l’espace de noms où le type d’énumération est défini. Prenons par exemple 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 la présence du qualificateur d'espace de noms.

Voir aussi \value et \omitvalue.

\example

La commande ` \example ` sert à documenter un exemple. L'argument est le chemin d'accès de l'exemple par rapport à l'un des chemins répertoriés dans la variable `exampledirs ` du fichier de configuration QDoc.

La page de documentation sera générée dans le fichier modulename-path-to-example.html. QDoc ajoutera une liste de tous les fichiers source et images de l’exemple à la fin de la page, sauf si \noautolist la commande soit utilisée ou que la variable de configuration ` url.examples ` soit définie pour le projet.

Par exemple, si exampledirs 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 https://doc.qt.io/
    \title Qt Documentation Site
*/

Cela vous permet d’inclure un lien vers la page externe dans votre documentation de la manière suivante :

/*!
    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 intégrer l'adresse directement 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 maintenance de la documentation. Si l'adresse change, il suffit de modifier l'argument de la commande ` \externalpage `.

\fn (fonction)

La commande ` \fn ` sert à 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 `const` 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 » plutôt que le 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, y compris 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 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 : le constructeur et le destructeur par défaut, le constructeur de copie et le constructeur de copie par déplacement, l’opérateur d’affectation et l’opérateur d’affectation par déplacement.

Lors de la documentation d’un « hidden friend », vous pouvez utiliser soit la syntaxe qualifiée par la classe, soit la syntaxe de fonction libre non qualifiée. Par exemple, pour :

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

La commande peut s'écrire sous la forme "\fn Foo::operator==(const Foo&, const Foo&)" ou sous la forme d'une fonction libre "\fn bool operator==(const Foo&, const Foo&)". QDoc résout les « amis cachés » en recherchant les classes référencées dans les types de paramètres de 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 toute autre entité appartenant à un groupe donné. L’argument est le nom du groupe.

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

La commande \group est généralement suivie d’une \title commande et d’une brève présentation du groupe. La page HTML du groupe est enregistrée dans un fichier d’ .html nommé <nom-du-groupe-en-minuscules>.html.

Chaque entité du groupe est répertoriée sous forme de lien (à l’aide du titre de la page ou du nom de classe), suivi d’une description issue de la \brief commande figurant 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 relatives au groupe doivent être répertoriées explicitement à l'aide de la \generatelist commande 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 également \ingroup, \annotatedlist, \generatelist, et \noautolist.

\headerfile

La commande ` \headerfile ` sert à documenter les fonctions globales, les types et les macros 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 enregistrée dans un fichier ` .html ` généré à partir de l'argument du fichier d'en-tête.

La documentation relative à une fonction, un type ou une macro déclarée dans le fichier d'en-tête en cours de documentation est intégrée à la page du fichier d'en-tête à l'aide de la \relates .

Si l'argument n'existe pas en tant que fichier d'en-tête, la commande « \headerfile » crée tout de même une page de documentation pour ce 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 ` sert à documenter une macro C++. L'argument est la macro, qui peut se présenter sous l'une des trois formes suivantes : les macros de type fonction telles que ` Q_ASSERT()`, les macros de type déclaration telles que ` Q_PROPERTY()` et les macros sans parenthèses telles que ` Q_OBJECT`.

Le commentaire « \macro » doit contenir une \relates commande qui associe le commentaire de macro à une classe, un fichier d'en-tête ou un espace de noms. Sinon, 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 via la commande \inmodule commande dans le commentaire « \class ».

La commande « \module » est généralement suivie d’un \title et d’une \brief 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 \brief . 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 \noautolist commande 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 ` sert à documenter le contenu de l'espace de noms C++ dont le nom est spécifié en argument. La page de référence générée par QDoc pour un espace de noms est similaire à celle générée pour une classe C++.

/*!
    \namespace Qt

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

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

\page

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

La commande \page attend un seul argument qui correspond au nom du fichier dans lequel QDoc doit enregistrer la page.

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

/*!
   \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 affiche cette page à l'adresse aboutqt.html.

\property

La commande \property sert à documenter une propriété Qt. L'argument correspond au nom complet de la propriété.

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

Q_PROPERTY(QString state READ state WRITE setState)

Il n'est pas nécessaire de documenter les fonctions « set », « reset » et « get » ; il suffit de documenter la propriété. QDoc générera une liste des fonctions d'accès qui apparaîtra 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 \brief commande. Pour les propriétés, l’ \brief commande est un fragment de phrase qui sera inclus dans la description d’une ligne de la propriété. La commande suit les mêmes règles de description que la \variable commande.

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

    This property's default is false.
*/

\qmlattachedmethod

La commande ` \qmlattachedmethod ` sert à documenter une méthode associée à un type QML (propriétés associées). La commande ` \qmlattachedmethod ` s'utilise exactement comme la \qmlmethod commande.

L’argument correspond au reste de la ligne et doit être la signature complète de la méthode, commençant par le type de retour, suivi du nom du type QML dans lequel la méthode est déclarée, du qualificatif ` :: `, puis enfin du nom de la méthode avec les types et noms de ses paramètres entre parenthèses. Si une méthode ne prend aucun argument, utilisez ` ()`.

Par exemple, pour documenter une méthode associée nommée show() pour le type ToolTip:

/*!
    \qmlattachedmethod void QtQuick.Controls::ToolTip::show(string text, int timeout = -1)

    This attached method shows the shared tool tip with \a text for
    \a timeout milliseconds. You can attach the method to any item.
*/

QDoc inclut cette documentation dans la page de référence QML du type ` ToolTip `.

\qmlattachedproperty

La commande \qmlattachedproperty sert à documenter une propriété QML qui sera associée à un type QML. Voir Propriétés associées. L’argument correspond au 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 qualificateur ::, puis enfin du nom de la propriété.

Par exemple, pour documenter une propriété associée QML de type booléen 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é attachée dans la page de référence QML du type ListView.

\qmlattachedsignal

La commande \qmlattachedsignal sert à documenter un signal attachable. La commande \qmlattachedsignal s'utilise exactement comme la \qmlsignal commande.

L’argument correspond au reste de la ligne. Il doit comporter le nom du type QML dans lequel le signal est déclaré, le qualificatif « :: », puis enfin le nom du signal. Par exemple, un signal attaché en QML 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 sert à documenter un type de valeur pour QML. Elle prend un nom de type comme seul argument.

\qmlvaluetypeest fonctionnellement identique à la \qmltype . La seule différence réside dans le fait que le type sera intitulé (et regroupé) en tant que type de valeur QML.

\qmlclass

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

\qmlenum

La commande ` \qmlenum ` sert à documenter une énumération QML. Elle prend un seul argument : le nom complet du type d’énumération, y compris le type QML parent et, éventuellement, le module QML.

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

Par exemple,

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

Cela génère la documentation d’un canal d’énumération comportant 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{value} comprend déjà un préfixe, celui-ci 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++ \enum , à l'aide de la \qmlenumeratorsfrom commande.

Cette commande a été introduite avec Qt 6.10.

Voir aussi \qmlenumeratorsfrom.

\qmlmethod

La commande ` \qmlmethod ` sert à documenter une méthode QML. L'argument correspond à la signature complète de la méthode et doit inclure le type de retour ainsi que les noms et types des paramètres, entre parenthèses. Si une méthode ne prend aucun argument, utilisez ` ()`.

/*!
    \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 du type « TextInput ».

\qmltype

La commande ` \qmltype ` sert à documenter un type QML. Cette commande prend un seul argument : le nom du type QML.

Si le type QML dispose d'une classe C++ équivalente, vous pouvez spécifier cette classe à l'aide de la \nativetype commande context.

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

/*!
    \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 précise \nativetype pour préciser qu’un « Transform » est l’équivalent QML de la classe C++ QGraphicsTransform. Un commentaire « \qmltype » doit toujours inclure la \since commande, car tous les types QML sont de type « new ». Il doit également comporter une \brief description. Si un type QML est membre d’un groupe de types QML, le commentaire ` \qmltype ` doit inclure une ou plusieurs \ingroup commandes.

\qmlsingletontype

La commande \qmlsingletontype sert à documenter explicitement un type singleton QML. Cette commande est fonctionnellement identique à \qmltype, mais elle marque explicitement le type comme singleton, quelle que soit l’implémentation C++.

Un type singleton QML garantit qu’il n’existe qu’une seule instance dans le moteur QML. La désignation « singleton » apparaît dans la documentation générée sous la forme d’un indicateur « (Singleton) » dans le titre et d’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 utiliser \qmltype à la place, car QDoc détectera automatiquement la nature singleton à partir du code C++.

Voir aussi \qmluncreatabletype.

\qmluncreatabletype

La commande ` \qmluncreatabletype ` sert à documenter explicitement un type qui est enregistré dans le système de types QML mais qui ne peut pas être instancié directement en QML.

Cette commande est fonctionnellement identique à \qmltype, mais elle marque explicitement le type comme non instanciable, quelle que soit l’implémentation en C++.

La mention « non créable » apparaît dans la documentation générée sous la forme d'un indicateur « (Non créable) » dans le titre, accompagné d'une note explicative.

/*!
    \qmluncreatabletype Dialog
    \inqmlmodule QtQuick.Dialogs

    \brief The base type of native dialogs.
*/

Pour les classes C++ qui utilisent la macro ` QML_UNCREATABLE `, privilégiez l’utilisation de \qmltype à la place, car QDoc détectera automatiquement le caractère « non créable » à partir du code C++.

La commande ` \qmluncreatabletype ` a été introduite dans QDoc avec Qt 6.12.

Voir aussi \qmlsingletontype.

\qmlproperty

La commande ` \qmlproperty ` sert à documenter une propriété QML. L’argument correspond au reste de la ligne. Le texte de l’argument doit indiquer le type de la propriété, suivi du nom du type QML, du qualificateur ` :: `, puis enfin du nom de la propriété. Si nous avons une propriété QML nommée ` x ` dans le type QML ` Translate`, et que cette propriété est de type ` real`, la commande ` \qmlproperty ` correspondante ressemblerait à ceci :

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

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

La \default commande sert à documenter la valeur par défaut d’une propriété :

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

Si la propriété QML expose une énumération C++, elle 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 binaire d’indicateurs peuvent utiliser la \value commande 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é complet, incluant 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 \inqmlmodule commande dans la documentation associée à \qmltype. Si le nom du type QML auquel appartient la propriété est unique parmi tous les types du projet de documentation, l’identifiant de module peut être omis.

\qmlsignal

La commande \qmlsignal sert à documenter un signal QML. L’argument correspond au reste de la ligne. Les arguments doivent être les suivants : 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(), sa documentation 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 dans la page de référence QML du type ` MouseArea `.

\qmlmodule

Utilisez la commande \qmlmodule pour créer une page de module QML. Une page de module QML regroupe des types QML ou tout autre élément associé. La commande prend en argument un numéro d'<VERSION>, facultatif, et fonctionne de manière similaire à la commande group.

Un type QML est associé à un module en ajoutant la \inqmlmodule commande au bloc de commentaires qui documente le type. Vous pouvez créer un lien vers n’importe quel membre d’un module QML en utilisant le nom du module précédé de deux 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 ses membres.

/*!
    \qmlmodule ClickableComponents

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

\inqmlmodule

Pour indiquer qu’un type QML est disponible dans le cadre d’une importation spécifique d’un module QML, il suffit d’insérer la commande \inqmlmodule dans un \qmltype topic. 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 (\qmlmodule ).

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

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

QDoc génère une ligne de déclaration d'importation : import <qmlmodule> dans un tableau situé en haut de la page de référence des types 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 {ClickableComponents::}{ClickableButton}

Liens vers la page de référence des types, avec « ClickableButton » comme texte du lien.

\instantiates

La commande « \instantiates » est obsolète depuis Qt 6.8. Utilisez \nativetype à la place.

\nativetype

La commande \nativetype doit être utilisée conjointement avec la \qmltype commande `topic`. Cette commande prend une classe C++ comme argument. Si QDoc ne parvient pas à trouver la classe C++, il affiche un avertissement. Cette commande a été introduite avec Qt 6.8.

Utilisez la commande « \nativetype » pour préciser le nom du type en C++. Cela garantit que la section « Prérequis » générée dans la documentation pour le type QML contienne une entrée « En C++ ». La classe C++ disposera d'une entrée correspondante « En 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 \qmltype rubrique explique \nativetype pour préciser qu’un Transform s’appelle « QGraphicsTransform » en C++.

\typealias

La commande « \typealias » est similaire à \typedef, mais elle est spécifique à la documentation d’un alias de type C++ :

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

Cela 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 » sert à documenter une définition de type (typedef) en C++. L’argument est le nom de la définition de type. La documentation relative à cette définition de type 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 la définition de type est déclarée. Pour associer l'\typedef ion à une classe, un espace de noms ou un fichier d'en-tête, le commentaire « \typedef » doit contenir une \relates commande.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

Les autres typedefs 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 » sert à documenter une variable membre d'une classe ou une constante. L'argument est le nom de la variable ou de la constante. Le commentaire généré par la commande « \variable » inclut une \brief commande. QDoc génère la documentation à partir du texte fourni par la commande \brief.

La documentation sera placée 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 des constantes à l'aide de la commande « \variable ». Par exemple, supposons que vous disposiez des constantes « Type » et « UserType » dans la classe « QTreeWidgetItem » :

enum { Type = 0, UserType = 1000 };

Pour celles-ci, la commande ` \variable ` peut être utilisée comme suit :

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