Ces commandes fournissent des fonctions diverses liées à l'aspect visuel de la documentation et au processus de génération de la documentation.

\annotatedlist

La commande \annotatedlist permet d'obtenir une liste des membres d'un groupe, chaque membre étant accompagné d'un bref texte. Voici un exemple tiré de la documentation de référence de Qt :

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

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

   \annotatedlist draganddrop
*/

Cette commande génère une liste de toutes les classes C++ et/ou de tous les types QML du groupe draganddrop. Une classe C++ ou un type QML dans le groupe draganddrop aura \ingroup draganddrop dans son fichier \class ou \qmltype commentaire.

Les membres du groupe sont triés par ordre croissant, sur la base 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 Trier les membres d'un groupe.

\cmakepackage

Utilisez la commande \cmakepackage pour ajouter des informations sur les paquets CMake aux classes et aux espaces de noms. Ces informations apparaissent 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 cette information sous la forme suivante

Espace de noms Foo

Un espace de noms. 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 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
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDoc affichera cette information sous la forme suivante

Espace de noms Foo

Un espace de noms. 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 CMake target_link_libraries qui sont ajoutées aux classes et aux espaces de noms. Cette commande doit être utilisée en conjonction avec les commandes \module et \cmakecomponent (en anglais). Par exemple :

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

    ...
*/

QDoc affichera ceci sous la forme suivante

Espace de noms Foo

Un espace de noms. 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 le paquetage CMake aux classes et aux espaces de noms. Ces informations apparaissent 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
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc affichera cette information sous la forme suivante

Espace de noms Foo

Un espace de noms. 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 CMake target_link_libraries qui sont ajoutées aux classes et aux espaces de noms. La commande doit être utilisée en conjonction avec les commandes \module et \qtcmakepackage .

Voir aussi \module et \qtcmakepackage}

\generatelist

La commande \generatelist se développe en une liste de liens vers les entités de la documentation regroupées par une commande \ingroup ou les entités qui correspondent à l'un des arguments énumérés ci-dessous. 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
*/

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

<group-name>

Avec un nom de groupe comme seul argument, 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, sur la base du nom ou du titre visible par l'utilisateur. Depuis QDoc 6.8, l'ordre de tri par défaut peut être modifié :

\generatelist [descending] changelogs

En supposant que le groupe changelogs se compose de pages détaillant les modifications apportées à différentes versions, la liste est générée dans l'ordre décroissant (la version la plus récente en premier).

Clé de tri

Depuis QDoc 6.8, une clé de tri personnalisée peut être attribuée à un ou plusieurs membres du groupe à l'aide de la commande \meta à l'aide de la commande

\meta sortkey {sort key}

Le tri (croissant ou décroissant) est alors effectué sur la base de cette (ces) clé(s), plutôt que sur les titres visibles par l'utilisateur.

annotatedclasses

L'argument annotatedclasses fournit un tableau contenant les noms de toutes les classes et 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, le nom d'une classe est un lien vers la documentation de référence de la classe :

Une classe C++ est documentée avec la commande \class pour documenter une classe C++. L'annotation de la classe est tirée de l'argument de la commande \brief de la classe.

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 et 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 (qui possède des 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 l'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 et une description de chacune d'entre elles. Chaque titre est un lien vers la page de l'attribution.

Un tableau distinct est généré pour chaque module (qui a des attributions), à condition que le module ait défini une variable de configuration navigation.landingpage. La variable landingpage est utilisée comme titre pour l'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 des noms de classes. Les noms de classe seront triés en fonction du caractère qui suit le préfixe commun. Par exemple, le préfixe commun pour les classes Qt est Q. L'argument du préfixe commun est facultatif. Si aucun préfixe commun n'est fourni, les noms de classe seront triés sur 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 cette manière :

/*!
    \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 avec la commande \class avec la commande

classesbymodule

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

Par exemple, cette commande peut être utilisée sur une page de 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 membre du module spécifié doit être marquée par la commande \inmodule dans son commentaire \class.

qmltypesbymodule

Similaire à l'argument classesbymodule, mais utilisé pour lister les types QML (à l'exclusion des types de valeurs QML) du module QML spécifié avec le deuxième argument.

qmlvaluetypesbymodule

Similaire à l'argument qmltypesbymodule, mais liste les types de valeurs QML à la place.

functionindex

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

/*!
    \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 de licences dans le projet de documentation actuel. Chaque licence est identifiée à l'aide de la commande \legalese pour identifier chaque licence.

overviews

L'argument overviews est utilisé pour indiquer à QDoc de générer une liste en concaténant le contenu de toutes les pages. \group pages. Qt l'utilise pour générer la page d'aperçu de cette manière :

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

L'argument attributions est utilisé pour indiquer à QDoc de générer une liste d'attributions dans la documentation.

related

L'argument related est utilisé en combinaison avec les arguments \group et \ingroup pour dresser la liste de toutes les vues d'ensemble relatives à un groupe donné. Par exemple, la page Programmation avec Qt est générée de cette manière :

/*!
    \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 listée sur cette page de groupe contient la commande :

\ingroup qt-basic-concepts

Voir aussi \annotatedlist.

\if

La commande \if et la commande \endif correspondante contiennent 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 déclaration #if 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 rendu que si le symbole de préprocesseur opensourceedition est défini et spécifié dans la variable defines du fichier de configuration pour que QDoc traite le code contenu dans #ifdef et #endif :

defines = opensourceedition

Vous pouvez également définir le symbole de préprocesseur manuellement sur la ligne de commande. Pour plus d'informations, voir la documentation de la variable defines.

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

\endif

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

Pour plus d'informations, voir la documentation de la commande \if pour plus d'informations.

Voir aussi \if, \else, les définitions et les faussetés.

\else

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

La commande \else ne peut être utilisée qu'à l'intérieur des commandes \if... \endif, mais elle est utile lorsqu'il n'y a que deux possibilités.

\include

La commande \include envoie tout ou partie du fichier spécifié par son premier argument au flux d'entrée de QDoc pour être traité comme un extrait de commentaire QDoc.

Cette commande est utile lorsqu'un extrait de commande ou de texte doit être utilisé à plusieurs endroits dans la documentation. Utilisez la commande \include chaque fois que vous souhaitez insérer un extrait dans la documentation. Le fichier contenant l'extrait à inclure doit être situé dans le(s) chemin(s) indiqué(s) dans la variable de configuration QDoc sourcedirs ou exampledirs. Il peut s'agir de n'importe quel fichier source analysé par QDoc (ou même de celui dans lequel la commande \include est utilisée), ou de n'importe quel 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 n'est pas listée dans sources.fileextensions; par exemple, .qdocinc.

La commande peut avoir 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 et de texte QDoc, 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 ne souhaitez inclure qu'une partie du fichier, consultez le formulaire à 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 identificateur-de-scripts

C'est une perte de temps que de créer un fichier .qdocinc distinct pour chaque extrait d'inclusion QDoc que vous souhaitez utiliser à plusieurs endroits dans la documentation, d'autant plus que vous devrez probablement insérer l'avis de copyright/licence dans chacun de ces fichiers. Si vous avez plusieurs snippets à inclure, vous pouvez les mettre dans un seul fichier et entourer chacun d'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 le texte trouvé entre les deux balises portant le même nom que le deuxième argument sont envoyés au flux d'entrée QDoc. Vous pouvez même avoir des extraits imbriqués.

Arguments supplémentaires

Depuis QDoc 6.3, tout argument supplémentaire passé à la commande \include est utilisé pour injecter des chaînes dans le contenu inclus. Pour injecter une chaîne de caractères à un endroit précis du contenu, ajoutez une barre oblique inverse suivie d'un chiffre (1..9). Les chiffres correspondent à l'ordre de la liste des arguments. Mettez les arguments entre accolades pour vous assurer que QDoc rendra l'intégralité de l'argument, y compris les éventuels caractères d'espacement, comme vous l'attendez.

Par exemple, si l'extrait suivant se trouve dans un fichier includes.qdocinc:

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

Puis, la ligne suivante \include:

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

Rendu

Pour activer la sortie détaillée, sélectionnez Verbose > Enable.

\meta

La commande \meta est utilisée pour ajouter des métadonnées à la documentation. La commande a deux arguments : le premier est le nom de l'attribut de métadonnées et le second est la valeur de l'attribut. Chaque argument doit être placé entre crochets, comme indiqué dans 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 un but spécifique :

Exemple de métadonnées

Une autre utilisation de la commande \meta consiste à inclure des métadonnées (balises) dans la documentation. \example documentation. Par défaut, QDoc génère des balises d'exemple basées sur le nom de l'exemple et le nom du module. \title et le nom du module. Ces balises sont affichées dans le mode d'accueil de Qt Creator et aident les utilisateurs à naviguer dans la liste des exemples.

Des balises supplémentaires peuvent être créées avec \meta {tag} {tag1} ou \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 exemple sont ignorés.

Exclusion d'exemples

Marquer un exemple comme cassé l 'exclura du fichier manifest généré, le retirant de fait du mode Welcome de Qt Creator.

\meta {tag} {broken}

Chemins d'installation des exemples

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

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

Voir aussi examplesinstallpath.

Statut

L'argument status de la commande \meta ajoute une description personnalisée de l'état d'un fichier \class ou d'un \qmltype. Cette description apparaît alors dans un tableau en haut de la page de référence du type.

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

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

Métadonnées du document

Un argument keywords pour la commande \meta ajoute les mots-clés spécifiés en tant que métadonnées pour le 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, qui est automatiquement générée au bas de la page du module C++ ou QML, doit être omise, car les classes ou les types ont été listés manuellement. Cette commande peut également être utilisée avec la commande \group pour omettre la liste des membres du groupe, lorsqu'ils sont listés manuellement.

La commande doit être placée sur sa propre ligne. Voir l'exemple de la commande 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. Le même commentaire contient une commande \noautolist pour désactiver la génération automatique de listes, et une commande \generatelist pour dresser la liste des 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 documentation. \example où elle permet d'omettre la liste générée automatiquement des fichiers et des images appartenant à un projet d'exemple.

\omit

La commande \omit et la commande \endomit correspondante délimitent les parties de la documentation que vous souhaitez que QDoc ignore. Par exemple, la commande

/*!
    \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 \endraw correspondante 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 donné que lorsqu'il génère le format spécifié par l'utilisateur.

Par exemple, "\raw HTML " ne génère du code que lorsque QDoc génère de la documentation HTML.

\sincelist

La commande \sincelist permet d'obtenir une description détaillée des nouveaux éléments ajoutés à l'API documentée dans une version donnée. Exemple d'utilisation :

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

   \sincelist 6.11
*/

\sincelistprend un seul argument, une chaîne de version. La sortie générée comprend toutes les fonctionnalités marquées par une commande \since ou une clause since correspondant à la chaîne de la 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 en tant qu'entier. Par défaut, la base 10 est utilisée, à moins qu'un préfixe '0x' ou '0' ne soit spécifié (pour la base 16 et 8, respectivement).