Ces commandes offrent diverses fonctions liées à la présentation de la documentation et au processus de génération de celle-ci.

\annotatedlist

La commande « \annotatedlist » affiche la liste des membres d’un groupe, chaque membre étant accompagné d’une brève description. Voici un exemple tiré de la documentation de référence Qt :

/*!
   ...
   \section1 Drag and Drop Classes

   These classes deal with drag and drop and the necessary mime type
   encoding and decoding.

   \annotatedlist draganddrop
*/

Cela génère une liste de toutes les classes C++ et/ou de tous les types QML appartenant au groupe « draganddrop ». Une classe C++ ou un type QML appartenant au groupe « draganddrop » aura pour valeur « draganddrop » dans le champ « \ingroup » de sa \class ou \qmltype commentaire.

Les éléments du groupe sont triés par ordre croissant, en fonction du nom ou du titre visible par l'utilisateur. Depuis QDoc 6.8, \annotatedlist et \generatelist prennent également en charge le tri personnalisé.

Voir aussi \generatelist et Tri des membres du groupe.

\cmakepackage

Utilisez la commande « \cmakepackage » pour ajouter des informations sur les paquets CMake aux classes et aux espaces de noms. Ces informations apparaîtront alors dans un tableau en haut de la page de documentation de la classe ou de l'espace de noms. Par exemple :

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc affichera cela sous la forme suivante :

Espace de noms Foo

Un espace de noms. En savoir plus…

En-tête :	#include <Bar>
CMake :	find_package(Baz REQUIRED) target_link_libraries(mytarget PRIVATE Baz::Baz)

Voir aussi \module et \cmakecomponent}

\cmakecomponent

Utilisez la commande « \cmakecomponent » pour ajouter des informations sur les composants CMake aux classes et aux espaces de noms. Ces informations apparaîtront ensuite dans un tableau en haut de la page de documentation de la classe ou de l'espace de noms. Par exemple :

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDoc affichera cela sous la forme suivante :

Espace de noms Foo

Un espace de noms. En savoir plus…

En-tête :	#include <Bar>
CMake :	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::Baz)

Voir aussi \module et \cmakepackage}

\cmaketargetitem

Utilisez la commande « \cmaketargetitem » pour remplacer la partie « item » des informations d’ target_link_libraries s CMake ajoutées aux classes et aux espaces de noms. Cette commande doit être utilisée conjointement avec la commande \module et \cmakecomponent . Par exemple :

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \cmaketargetitem Qt6::BazPrivate
    \brief A namespace.

    ...
*/

QDoc générera le résultat suivant :

Espace de noms Foo

Un espace de noms. En savoir plus…

En-tête :	#include <Bar>
CMake :	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)

Voir aussi \module et \cmakecomponent}

\qtcmakepackage

Utilisez la commande « \qtcmakepackage » pour ajouter des informations sur les paquets CMake aux classes et aux espaces de noms. Ces informations apparaîtront ensuite dans un tableau en haut de la page de documentation de la classe ou de l'espace de noms. Par exemple :

/*!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc affichera cela sous la forme suivante :

Espace de noms Foo

Un espace de noms. En savoir plus…

En-tête :	#include <Bar>
CMake :	find_package(Qt6 REQUIRED COMPONENTS Baz)

\qtcmaketargetitem

Utilisez la commande \qtcmaketargetitem pour remplacer la partie « item » des informations d'target_link_libraries s CMake ajoutées aux classes et aux espaces de noms. Cette commande doit être utilisée conjointement avec la commande \module et \qtcmakepackage .

Voir aussi \module et \qtcmakepackage}

\generatelist

La commande « \generatelist » génère une liste de liens vers les entités de documentation regroupées sous une \ingroup commande ou d’entités correspondant à l’un des arguments énumérés ci-dessous. Voici un exemple tiré de la documentation de référence de Qt :

/*!
   \page classes.html
   \title All Classes

   For a shorter list that only includes the most
   frequently used classes, see \l{Qt's Main Classes}.

   \generatelist classes Q
*/

Cela génère la page « Toutes les classes ». La commande accepte les arguments suivants :

<group-name>

Si le seul argument fourni est un nom de groupe, QDoc répertorie toutes les entités qui utilisent la commande « \ingroup <group-name> ».

Tri des membres d'un groupe

Lors de la génération d'une liste des membres d'un groupe, ceux-ci sont triés par ordre croissant, en fonction du nom ou du titre visible par l'utilisateur. Depuis la version 6.8 de QDoc, l'ordre de tri par défaut peut être modifié :

\generatelist [descending] changelogs

En supposant que le groupe « changelogs » soit composé de pages détaillant les modifications apportées aux différentes versions, cela génère la liste par ordre décroissant (la version la plus récente en premier).

Clé de tri

Depuis QDoc 6.8, il est possible d’attribuer une clé de tri personnalisée à un ou plusieurs éléments d’un groupe à l’aide de la \meta commande suivante :

\meta sortkey {sort key}

Le tri (par ordre croissant ou décroissant) s'effectue alors en fonction de cette ou ces clés, plutôt qu'en fonction des titres visibles par l'utilisateur.

annotatedclasses

L'argument ` annotatedclasses ` fournit un tableau contenant les noms de toutes les classes, ainsi qu'une description de chacune d'entre elles. Chaque nom de classe est un lien vers la documentation de référence de la classe. Par exemple :

Une classe C++ est documentée à l'aide de la \class commande. L'annotation de la classe est extraite de l'argument de la commande de commentaire de classe \brief .

annotatedexamples

L'argument « annotatedexamples » fournit une liste complète de tous les exemples sous la forme d'un ensemble de tableaux contenant les titres de tous les exemples, ainsi qu'une description de chaque exemple. Chaque titre est un lien vers la documentation de l'exemple.

Un tableau distinct est généré pour chaque module (disposant d’exemples documentés), à condition que le module ait défini une variable de configuration `navigation.landingpage`. La variable `landingpage` est utilisée comme titre pour un en-tête qui précède chaque tableau.

annotatedattributions

L'argument ` annotatedattributions ` fournit une liste complète de toutes les attributions sous la forme d'un ensemble de tableaux contenant les titres de toutes les attributions, ainsi qu'une description de chacune d'entre elles. Chaque titre est un lien vers la page de l'attribution correspondante.

Un tableau distinct est généré pour chaque module (comportant des attributions), à condition que le module ait défini une variable de configuration `navigation.landingpage`. La variable `landingpage` est utilisée comme titre pour un en-tête qui précède chaque tableau.

classes <prefix>

L'argument ` classes ` fournit une liste alphabétique complète des classes. Le deuxième argument, <prefix>, est le préfixe commun aux noms de classes. Les noms de classes seront triés en fonction du caractère suivant le préfixe commun. Par exemple, le préfixe commun aux classes Qt est Q. L'argument du préfixe commun est facultatif. Si aucun préfixe commun n'est fourni, les noms de classes seront triés en fonction de leur premier caractère.

Chaque nom de classe devient un lien vers la documentation de référence de la classe. Cette commande est utilisée pour générer la page « Toutes les classes » de la manière suivante :

/*!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
*/

Une classe C++ est documentée à l'aide de la \class commande.

classesbymodule

Lorsque cet argument est utilisé, un deuxième argument est requis : il spécifie le module dont les classes doivent être répertoriées. QDoc génère un tableau contenant ces classes. Chaque classe est répertoriée avec le texte de sa \brief commande.

Par exemple, cette commande peut être utilisée sur la page d’un module comme suit :

/*!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

    ...
*/

Chaque classe appartenant au module spécifié doit être marquée à l'aide de la \inmodule dans son commentaire « \class ».

qmltypesbymodule

Similaire à l’argument « classesbymodule », mais utilisé pour répertorier les types QML (à l’exclusion des types de valeur QML) du module QML spécifié par le deuxième argument.

qmlvaluetypesbymodule

Similaire à l'argument « qmltypesbymodule », mais répertorie à la place les types de valeurs QML.

functionindex

L'argument functionindex fournit une liste alphabétique complète de toutes les fonctions membres documentées. Il est généralement utilisé uniquement pour générer la page d'index des fonctions Qt, de la manière suivante :

/*!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
*/

legalese

L'argument legalese indique à QDoc de générer une liste des licences présentes dans le projet de documentation actuel. Chaque licence est identifiée à l'aide de la \legalese commande.

overviews

L'argument overviews est utilisé pour demander à QDoc de générer une liste en concaténant le contenu de toutes les \group pages. Qt s'en sert pour générer la page « Aperçus » de la manière suivante :

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

L'argument « attributions » sert à indiquer à QDoc de générer une liste des mentions de copyright dans la documentation.

related

L'argument « related » s'utilise en combinaison avec l'argument \group et \ingroup pour répertorier toutes les présentations générales liées à un groupe spécifié. Par exemple, la page « Programmation avec Qt » est générée de la manière suivante :

/*!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
*/

Chaque page répertoriée sur cette page de groupe contient la commande :

\ingroup qt-basic-concepts

Voir aussi \annotatedlist.

\if

La commande « \if » et la commande correspondante « \endif » encadrent des parties d’un commentaire QDoc qui ne seront incluses que si la condition spécifiée par l’argument de la commande est vraie.

La commande lit le reste de la ligne et l'analyse comme une instruction #if en C++.

/*!
   \if defined(opensourceedition)

   \note This edition is for the development of
   \l{Qt Open Source Edition} {Free and Open Source}
   software only; see \l{Qt Commercial Editions}.

   \endif
*/

Ce commentaire QDoc ne sera affiché que si le symbole de préprocesseur opensourceedition est défini et spécifié dans la variable `defines` du fichier de configuration, afin que QDoc traite le code situé entre `#ifdef` et `#endif` :

defines = opensourceedition

Vous pouvez également définir manuellement ce symbole de préprocesseur sur la ligne de commande. Pour plus d’informations, consultez la documentation relative à la variable ` defines`.

Voir aussi \endif, \else, « defines » et « falsehoods ».

\endif

La commande « \endif » et la commande correspondante « \if » encadrent des parties d’un commentaire QDoc qui seront incluses si la condition spécifiée par l’ \if argument de la commande est vraie.

Pour plus d’informations, consultez la documentation de la \if commande.

Voir également \if, \else, « defines » et « falsehoods ».

\else

La commande « \else » spécifie une alternative si la condition de la \if commande est fausse.

La commande « \else » ne peut être utilisée qu’au sein des commandes «\if » ... « \endif », mais elle s’avère utile lorsqu’il n’y a que deux alternatives.

\include

La commande ` \include ` envoie tout ou partie du fichier spécifié par son premier argument vers le flux d'entrée QDoc afin qu'il soit traité comme un extrait de commentaire QDoc.

Cette commande est utile lorsqu’un extrait de commandes ou de texte doit être réutilisé à plusieurs endroits dans la documentation. Utilisez la commande ` \include ` partout où vous souhaitez insérer un extrait dans la documentation. Le fichier contenant l’extrait à inclure doit se trouver sous l’un des chemins indiqués dans les variables de configuration QDoc `sourcedirs ` ou `exampledirs`. Il peut s’agir soit d’un fichier source analysé par QDoc (ou même du même fichier que celui où la commande ` \include ` est utilisée), soit de tout autre fichier texte. Pour stocker des extraits dans un fichier séparé qui n’est pas destiné à être analysé par QDoc, utilisez une extension de fichier qui ne figure pas dans la liste `sources.fileextensions` ; par exemple, ` .qdocinc`.

La commande peut prendre un ou plusieurs arguments. Le premier argument est toujours un nom de fichier. Le contenu du fichier doit être une entrée QDoc, c’est-à-dire une séquence de commandes QDoc et de texte, mais sans les délimiteurs de commentaire QDoc /*! ... */ . Si vous souhaitez inclure l’intégralité du fichier nommé, laissez le deuxième argument vide. Si vous souhaitez n'inclure qu'une partie du fichier, consultez la forme à deux arguments ci-dessous. Voici un exemple de la forme à un argument :

/*!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
*/

\include nom-de-fichier identifiant-extrait

C'est une perte de temps de créer un fichier .qdocinc distinct pour chaque extrait QDoc que vous souhaitez utiliser à plusieurs endroits dans la documentation, d'autant plus que vous devrez probablement insérer la mention de copyright/licence dans chacun de ces fichiers. Si vous avez plusieurs extraits à inclure, vous pouvez les regrouper dans un seul fichier et entourer chacun d'entre eux de :

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

Vous pouvez ensuite utiliser la forme à deux arguments de la commande :

\include examples/signalandslots.qdocinc snippet-id2
\include examples/objectmodel.qdocinc another-snippet-id

La séquence de commandes QDoc et de texte située entre les deux balises portant le même nom que le deuxième argument est envoyée au flux d'entrée de QDoc. Vous pouvez même avoir des extraits imbriqués.

Arguments supplémentaires

Depuis QDoc 6.3, tous les arguments supplémentaires passés à la commande \include sont utilisés pour insérer des chaînes de caractères dans le contenu inclus. Pour insérer une chaîne à un emplacement spécifique dans le contenu, ajoutez une barre oblique inversée suivie d’un chiffre (1 à 9). Les chiffres correspondent à l’ordre de la liste d’arguments. Placez les arguments entre accolades pour vous assurer que QDoc affiche l’argument dans son intégralité, y compris les éventuels espaces, comme vous le souhaitez.

Par exemple, considérons l'extrait de code suivant dans un fichier includes.qdocinc:

//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]

La ligne \include suivante :

\include includes.qdocinc {usage} {detailed output} {Verbose}

Affiche

Pour activer l’affichage détaillé, sélectionnez « Verbose » > « Enable ».

\meta

La commande « \meta » sert à ajouter des métadonnées à la documentation. Elle comporte deux arguments : le premier est le nom de l’attribut de métadonnées, et le second est la valeur de cet attribut. Chaque argument doit être placé entre accolades, comme le montre cet exemple :

/*!
    \example demos/coffee
    \title Coffee Machine
    \brief A Qt Quick application with a state-based custom user interface.

    \meta {tags} {quick,embedded,states,touch}
    \meta {category} {Application Examples}
*/

Un certain nombre d'attributs de métadonnées ont une fonction spécifique :

Exemple de métadonnées

La commande « \meta » permet également d'inclure des métadonnées (balises) dans la \example documentation. Par défaut, QDoc génère des balises d’exemple en fonction du \title et du module. Ces balises s’affichent dans le mode « Bienvenue » d’ Qt Creator, aidant ainsi les utilisateurs à parcourir la liste des exemples.

Des balises supplémentaires peuvent être créées à l'aide de \meta {tag} {tag1} ou de \meta {tags} {tag1,[tag2,...]}. Par exemple :

/*!
    \example helloworld
    \title Hello World Example
    \meta {tags} {tutorial,basic}
*/

Cela donnerait les balises suivantes : tutorial,basic,hello,world. Les mots courants tels que « example » sont ignorés.

Exclusion des exemples

Marquer un exemple comme « défectueux » l'exclura du fichier manifeste généré, ce qui le supprimera de fait du mode « Bienvenue » de Qt Creator.

\meta {tag} {broken}

Exemples de chemins d'installation

La commande \meta, combinée à l’argument installpath, spécifie l’emplacement d’un exemple installé. Cette valeur remplace celle définie à l’aide de la variable de configuration examplesinstallpath.

/*!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
*/

Voir également examplesinstallpath.

État

Un argument « status » pour la commande « \meta » ajoute une description de statut personnalisée pour un \class ou un \qmltype. Cette description apparaîtra alors dans un tableau en haut de la page de référence du type.

/*!
    \class QNativeInterface::QAndroidApplication
    \meta {status} {Android-specific}
*/

Voir également les commandes liées à l'état.

Métadonnées du document

L'argument « keywords » de la commande « \meta » ajoute les mots-clés spécifiés en tant que métadonnées au document généré :

\meta {keywords} {reference, internal}

Dans la sortie HTML, ces mots-clés sont générés sous la forme d’un élément ` <meta name="keywords" content="..."> `.

\noautolist

La commande \noautolist indique que la liste annotée des classes C++ ou des types QML, générée automatiquement au bas de la page du module C++ ou QML, doit être omise, car ces classes ou types ont été répertoriés manuellement. Cette commande peut également être utilisée avec la \group commande pour omettre la liste des membres d'un groupe, lorsque ceux-ci sont répertoriés manuellement.

La commande doit figurer sur une ligne distincte. Voir Qt Quick Controls QML Types pour un exemple. La page est générée à partir de qtquickcontrols2-qmlmodule.qdoc. Vous y trouverez un commentaire QDoc contenant la commande \qmlmodule pour le module QtQuick.Controls. Ce même commentaire contient une commande \noautolist pour désactiver la génération automatique de la liste, ainsi qu’une commande \generatelist pour répertorier les types QML dans une section spécifique du document.

Cette commande a été introduite dans QDoc 5.6.

Depuis Qt 5.10, cette commande peut également être appliquée à la \example la documentation, où elle entraîne l'omission de la liste générée automatiquement des fichiers et des images appartenant à un projet d'exemple.

\omit

La commande ` \omit ` et la commande correspondante ` \endomit ` permettent de délimiter les parties de la documentation que vous souhaitez que QDoc ignore. Par exemple :

/*!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
*/

\raw (à éviter !)

La commande « \raw » et la commande correspondante « \endraw » délimitent un bloc de code brut en langage de balisage.

La commande prend un argument spécifiant le format du code.

QDoc ne génère le code fourni que lors de la génération du format spécifié par l'utilisateur.

Par exemple, «\raw HTML » ne générera du code que lorsque QDoc produira de la documentation HTML.

\sincelist

La commande « \sincelist » fournit une liste détaillée des nouveaux éléments ajoutés à l’API documentée dans une version spécifiée. Exemple d’utilisation :

/*!
   \page newclasses612.html
   \title New Classes and Functions in 6.12
   \brief A comprehensive list of new classes and functions in 6.12.

   \sincelist 6.12
*/

\sincelistprend un seul argument, une chaîne de caractères indiquant la version. Le résultat généré inclut toutes les fonctionnalités marquées d’une \since commande ou d’une clause « since » correspondant à cette chaîne de version.

\unicode

La commande \unicode vous permet d’insérer un caractère Unicode arbitraire dans le document.

La commande prend un argument spécifiant le caractère sous forme d’entier. Par défaut, la base 10 est supposée, sauf si un préfixe « 0x » ou « 0 » est spécifié (pour les bases 16 et 8, respectivement).