Introduction à QDoc

QDoc est un outil utilisé par les développeurs de Qt pour générer de la documentation pour les projets logiciels. Il fonctionne en extrayant les commentaires QDoc des fichiers source du projet et en formatant ensuite ces commentaires en pages HTML ou en documents DocBook XML. QDoc trouve les commentaires QDoc dans les fichiers .cpp et .qdoc. QDoc ne recherche pas les commentaires QDoc dans les fichiers .h. Un commentaire QDoc commence toujours par un point d'exclamation (!)). Par exemple, un commentaire QDoc commence toujours par un point d'exclamation ( !):

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

À partir du commentaire QDoc ci-dessus, QDoc génère la page HTML QObject class reference.

Ce manuel explique comment utiliser les commandes QDoc dans les commentaires QDoc pour intégrer une bonne documentation dans vos fichiers source. Il explique également comment créer un fichier de configuration QDoc, que vous transmettrez à QDoc sur la ligne de commande.

Exécution de QDoc

Le nom du programme QDoc est qdoc. Pour exécuter QDoc à partir de la ligne de commande, donnez-lui le nom d'un fichier de configuration :

$ ../../bin/qdoc ./config.qdocconf

QDoc reconnaît le suffixe .qdocconf comme un fichier de configuration QDoc. C'est dans le fichier de configuration que vous indiquez à QDoc où trouver les fichiers source du projet, les fichiers d'en-tête et les fichiers .qdoc. C'est également là que vous indiquez à QDoc le type de sortie à générer (HTML, DocBook XML...) et l'endroit où placer la documentation générée. Le fichier de configuration contient également d'autres informations pour QDoc.

Voir Le fichier de configuration de QDoc pour savoir comment configurer un fichier de configuration de QDoc.

Exécution de QDoc en mode d'exécution unique

À partir de Qt 5.5, une nouvelle façon d'exécuter QDoc est disponible et permet de réduire le temps de génération de la documentation Qt5 de 90 %. La nouvelle façon d'exécuter QDoc est le mode d'exécution unique. Le mode d'exécution unique n'est pas actuellement disponible dans le système de construction de Qt5, qui utilise toujours le mode standard. Le mode d'exécution unique n'est disponible que lorsque vous exécutez QDoc vous-même, ce que vous voudrez faire souvent lorsque vous documenterez votre module et intégrerez votre documentation avec les autres modules Qt.

Pour lancer QDoc en mode d'exécution unique, ajoutez -single-exec à la ligne de commande et transmettez à QDoc un fichier maître qdocconf qui est simplement une liste de chemins d'accès aux fichiers qdocconf de tous les modules Qt5. Par exemple, le fichier qdocconf

/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec

Le fichier qdocconf, master.qdocconf, liste simplement les fichiers qdocconf de tous les modules Qt5 à traiter :

/Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf
/Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf
/Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf
/Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf
/Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf
/Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf
/Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf
/Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf
/Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf
/Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf
/Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf
/Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf
/Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf
/Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf
/Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf
/Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf
/Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf
/Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf
/Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf
/Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf
/Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf
/Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf
/Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf
/Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf
/Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf
/Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf
/Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf
/Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf
/Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf
/Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf
/Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf
/Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf
/Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf
/Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf
/Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf
/Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf

Pourquoi le mode standard est lent

Actuellement, le système de construction de Qt5 n'utilise pas le mode d'exécution unique de QDoc pour générer la documentation de Qt5. Il exécute QDoc en mode standard. Le mode standard a été créé parce que c'était le moyen le plus facile de convertir le QDoc de Qt4 pour gérer la modularisation de Qt dans Qt5. Dans Qt4, QDoc s'exécute une fois sur toutes les sources de Qt4 pour générer la documentation HTML de Qt. En générant la documentation de Qt, QDoc Qt4 générait également un fichier d'index pour Qt. Ce fichier d'index était destiné à être utilisé lors des exécutions ultérieures de QDoc pour générer la documentation HTML d'autres bibliothèques/produits logiciels basés sur Qt. Le fichier d'index de Qt permettait à QDoc de lier la documentation écrite pour ces autres bibliothèques/produits à la documentation de Qt4.

Lorsque Qt5 est arrivé, Qt a été divisé en modules. Depuis, de nombreux nouveaux modules ont été ajoutés à Qt. Depuis la version 5.5, il existe plus de 40 modules distincts dans Qt5, chacun ayant sa propre documentation qui renvoie à (dépend de) la documentation d'autres modules Qt.

En mode standard, QDoc s'exécute deux fois pour chaque module. La première exécution de QDoc pour un module Qt particulier analyse tous les fichiers source du module et utilise ensuite les informations pour générer le fichier d'index du module. Elle est appelée phase de préparation car elle prépare le fichier d'index du module. La deuxième exécution de QDoc pour le module analyse également tous les fichiers source du module et génère ensuite les pages de documentation du module. Cette phase est appelée phase de génération car elle génère la documentation du module.

La documentation du module contiendra probablement des liens HTML vers la documentation d'un ou plusieurs autres modules Qt. Par exemple, la plupart des modules Qt5 contiennent des liens vers la documentation de QtCore. Lorsqu'un module Qt contient des liens vers la documentation d'autres modules Qt, on dit que ce module dépend de ces autres modules Qt. Par conséquent, lorsque QDoc exécute la phase de génération pour ce module, il doit également charger les fichiers d'index de ces modules afin de pouvoir créer ces liens.

Ainsi, lorsque le système de construction de Qt génère la documentation de Qt, il exécute d'abord QDoc une fois pour chaque module afin d'exécuter la phase de préparation pour générer tous les fichiers d'index. Ensuite, il exécute QDoc une fois pour chaque module pour effectuer la phase de génération, où il utilise les fichiers d'index dépendants pour générer la documentation du module, y compris tous les liens entre modules qu'il trouve. Chaque exécution de QDoc, qu'il s'agisse de la phase de préparation ou de la phase de génération, analyse tous les fichiers sources inclus dans le module et, dans la phase de génération, analyse également les fichiers d'indexation des modules dépendants. Rien n'est conservé ou conservable entre les exécutions de QDoc.

Pourquoi le mode d'exécution unique est beaucoup plus rapide

Comme son nom l'indique, le mode d'exécution unique utilise un seul processus QDoc pour générer toute la documentation Qt5. Le processus QDoc unique exécute toujours une phase de préparation pour chaque module, puis une phase de génération pour chaque module, mais il y a quelques différences. Il commence par lire le fichier qdocconf principal. Il lit ensuite chaque fichier qdocconf de la liste principale et exécute la phase de préparation pour chaque module. Au cours de la phase de préparation, tous les fichiers sources du module sont analysés afin de construire un arbre syntaxique pour le module. Le fichier d'index du module est ensuite généré, bien que QDoc ne relise pas les fichiers d'index lors de la phase de génération. La différence importante est que l'arbre syntaxique du module est conservé après la génération du fichier d'index, de sorte qu'après l'exécution de la phase de préparation pour tous les modules, QDoc dispose encore de tous les arbres syntaxiques qu'il a construits.

QDoc traite ensuite à nouveau chaque module pour la phase de génération. Mais QDoc n'a plus besoin d'analyser à nouveau les fichiers source de chaque module, car l'arbre syntaxique du module est toujours en mémoire. QDoc n'a pas non plus besoin de relire les fichiers d'index pour les modules dépendants, car il a toujours les arbres syntaxiques de ces modules en mémoire. Il ne lui reste plus qu'à parcourir l'arbre syntaxique de chaque module pour générer les pages de documentation.

QDoc analyse donc chaque fichier source une fois et une seule et n'a pas besoin de lire les fichiers d'index. C'est ce qui rend le mode d'exécution unique beaucoup plus rapide que le mode standard. Il est prévu que le système de construction de Qt exécute éventuellement QDoc en mode d'exécution unique. Cependant, des modifications du fichier qdocconf principal pourraient être nécessaires, de sorte que la méthode décrite ci-dessus pour exécuter QDoc en mode d'exécution unique pourrait devoir être modifiée, surveillez cet espace pour les mises à jour.

Comment fonctionne QDoc

QDoc commence par lire le fichier de configuration que vous avez spécifié sur la ligne de commande. Il stocke toutes les variables du fichier de configuration en vue d'une utilisation ultérieure. L'une des premières variables utilisées est outputformats. Cette variable indique à QDoc les générateurs de sortie qu'il doit exécuter. La valeur par défaut est HTML, donc si vous ne définissez pas outputformats dans votre fichier de configuration, QDoc générera une sortie HTML. C'est généralement ce que vous voulez de toute façon, mais vous pouvez aussi spécifier DocBook pour obtenir une sortie DocBook à la place.

Ensuite, QDoc utilise les valeurs de la variable headerdirs et/ou de la variable headers pour trouver et analyser tous les fichiers d'en-tête de votre projet. QDoc n' analyse pas les fichiers d'en-tête à la recherche de commentaires QDoc. Il analyse les fichiers d'en-tête pour construire un arbre principal de tous les éléments qui devraient être documentés, en d'autres termes, les éléments pour lesquels QDoc devrait trouver des commentaires QDoc.

Après avoir analysé tous les fichiers d'en-tête et construit l'arbre principal des éléments à documenter, QDoc utilise la valeur de la variable sourcedirs et/ou la valeur de la variable sources pour trouver et analyser tous les fichiers .cpp et .qdoc de votre projet. C'est dans ces fichiers que QDoc recherche les commentaires QDoc. Rappelez-vous qu'un commentaire QDoc commence par un point d'exclamation : /* !.

Pour chaque commentaire QDoc qu'il trouve, il recherche dans l'arborescence principale l'élément auquel la documentation appartient. Il interprète ensuite les commandes QDoc contenues dans le commentaire et stocke les commandes interprétées et le texte du commentaire dans le nœud de l'arbre correspondant à l'élément.

Enfin, QDoc parcourt l'arbre principal. Pour chaque nœud, si le nœud a stocké de la documentation, QDoc appelle le générateur de sortie spécifié par la variable outputformats pour formater et écrire la documentation dans le répertoire spécifié dans le fichier de configuration dans la variable outputdir.

Types de commandes

QDoc interprète trois types de commandes :

Les commandes de sujet identifient l'élément que vous documentez, par exemple une classe C++, une fonction, un type ou une page de texte supplémentaire qui ne correspond pas à un élément C++ sous-jacent.

Les commandes de contexte indiquent à QDoc comment l'élément documenté est lié à d'autres éléments documentés, par exemple les liens vers les pages suivantes et précédentes, l'inclusion dans des groupes de pages ou des modules de bibliothèque. Les commandes de contexte peuvent également fournir des informations sur l'élément documenté que QDoc ne peut pas obtenir à partir des fichiers source, par exemple, si l'élément est thread-safe, s'il s'agit d'une fonction surchargée ou réimplémentée, ou s'il a été déprécié.

Les commandes de balisage indiquent à QDoc comment les éléments de texte et d'image du document doivent être rendus, ou la structure du document.

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