Divers

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

\Liste annotée

La commande \annotatedlist se développe en une liste des membres d'un groupe, chaque membre étant listé avec son 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 du groupe draganddrop aura \ingroup draganddrop dans son commentaire \class ou \qmltype.

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 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 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 surcharger 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 conjointement avec les commandes \module et \cmakecomponent}. Par exemple :

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

    ...
*/

QDoc produira ceci sous la forme

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 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
    \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 surcharger 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 conjointement 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 avec 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.

Remarque : tout membre du groupe ayant une clé de tri est listé avant les membres sans clé (dans l'ordre croissant par défaut). Cela permet d'élever un ou plusieurs membres du groupe en haut de la liste.

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 :

QDialContrôle de plage arrondie (comme un indicateur de vitesse ou un potentiomètre)
QDialogLa classe de base des fenêtres de dialogue
QDirAccès aux structures de répertoire et à leur contenu

Une classe C++ est documentée par la commande \class. L'annotation de la classe est tirée de l'argument de la commande \brief du commentaire 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.

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 commande \brief.

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 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.

Note : La prise en charge de cet argument a été introduite dans QDoc 5.6.

qmlvaluetypesbymodule

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

Note : La prise en charge de cet argument a été introduite dans QDoc 6.7.

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.

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. Qt l'utilise pour générer la page de présentation de cette manière :

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

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

L'argument related est utilisé en combinaison avec les commandes \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.

\NFormule

La commande \if et la commande \endif correspondante entourent 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 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 entourent les parties d'un commentaire QDoc qui seront incluses si la condition spécifiée par l'argument de la commande \if est vraie.

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

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

\N-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 alternatives.

\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 où 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 filename snippet-identifier

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.

Remarque : les identificateurs de snippets fonctionnent également dans les blocs de commentaires de documentation (/* ! .. */), il n'est donc pas nécessaire d'utiliser un fichier .qdocinc distinct. Lors du traitement d'un bloc de commentaires, QDoc supprime toutes les lignes de commentaires //! de la sortie générée.

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 à un endroit spécifique du contenu, ajoutez une barre oblique inverse suivie d'un chiffre (1..9). Les chiffres correspondent à l'ordre de la liste d'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.

Important : chaque argument supplémentaire (y compris l'ID de l'extrait) doit être placé entre accolades. Si vous souhaitez inclure le fichier entier, utilisez un ID d'extrait vide : {}.

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

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

Ensuite, la ligne \include suivante :

\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 est d'inclure des métadonnées (balises) dans la documentation d'un exemple. Par défaut, QDoc génère des balises d'exemple basées sur le titre de l'exemple 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 d'état personnalisée pour une \class ou 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.

\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 répertoriés manuellement.

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

/*!
    \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 du langage de balisage.

Avertissement : Évitez d'utiliser cette commande si possible. Si vous essayez de générer un comportement spécial pour un tableau ou une liste, essayez d'obtenir le comportement que vous souhaitez en utilisant les commandes \span et \div dans votre \table ou \list.

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.

Remarque : l'utilisation des commandes de QDoc permet souvent d'atteindre l'objectif visé, tout en réduisant les risques d'erreurs ou de non-maintien du contenu.

\sincelist

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

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

   \sincelist 6.10
*/

\sincelist prend un seul argument, une chaîne de version. La sortie générée inclut toutes les fonctionnalités marquées par une commande \since ou une clause since correspondant à la chaîne de version.

\NUnicode

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).

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.