Variables de configuration génériques

Les variables de configuration générales de QDoc vous permettent de définir l'emplacement où QDoc trouvera les différents fichiers source dont il a besoin pour générer la documentation, ainsi que le répertoire dans lequel la documentation générée sera placée. Vous pouvez également effectuer quelques modifications mineures sur QDoc lui-même, en contrôlant sa sortie et son comportement de traitement.

codeindent

La variable codeindent spécifie le niveau d'indentation utilisé par QDoc lors de l'écriture d'extraits de code.

À l'origine, QDoc utilisait une valeur codée en dur de quatre espaces pour l'indentation du code afin de garantir que les extraits de code puissent être facilement distingués du texte environnant. Étant donné que nous pouvons utiliser des feuilles de style pour ajuster l'apparence de certains types d'éléments HTML, ce niveau d'indentation n'est pas toujours nécessaire.

langages de programmation

La variable ` codelanguages ` spécifie une liste de langages de code source non reconnus par QDoc qui peuvent être utilisés dans les blocs ` \code ` ... ` \endcode `. Cela permet d'écrire des blocs de code dans des langages que QDoc ne peut pas analyser, et de générer du code HTML pouvant être mis en évidence ou traité par d'autres outils.

codelanguages = Python Rust Java Swift "C#"

Comme QDoc prend en charge le C++ (Cpp), le QML et le texte, ces langages n’ont pas besoin d’être spécifiés dans cette liste. Les noms de langages contenant des caractères spéciaux, tels que C#, doivent être placés entre guillemets doubles lorsqu’ils sont inclus dans cette liste.

La variable ` codelanguages ` a été introduite dans QDoc 6.11 afin de permettre à la documentation Qt en ligne d’utiliser la coloration syntaxique pour un sous-ensemble des langages pris en charge par highlight.js.

Voir aussi \code.

codeprefix, codesuffix

Les variables codeprefix et codesuffix spécifient une paire de chaînes de caractères dans lesquelles chaque extrait de code est encadré.

définit

La variable defines spécifie les symboles du préprocesseur C++ que QDoc reconnaîtra et auxquels il réagira.

Lorsqu’un symbole de préprocesseur est spécifié à l’aide de la variable defines, vous pouvez également utiliser la \if commande pour encadrer la documentation qui ne sera incluse que si le symbole du préprocesseur est défini.

defines = QT_GUI_LIB

Cela garantit que QDoc traitera le code qui nécessite que ces symboles soient définis. Par exemple :

#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endif

Vous pouvez également définir manuellement des symboles de préprocesseur sur la ligne de commande à l'aide de l'option -D. Par exemple :

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

Dans ce cas, l’option -D garantit que le symbole de préprocesseur « qtforpython » est défini lorsque QDoc traite les fichiers source définis dans le fichier qtgui.qdocconf.

Voir également les fausses déclarations et \if.

dépend

La variable depends définit une liste d’autres projets de documentation dont dépend le présent projet pour résoudre les cibles de liens liés à l’héritage de types et tout autre élément vers lequel la documentation doit renvoyer.

À l’instar de Qt lui-même, la documentation de Qt est répartie sur plusieurs modules. Dans un projet de documentation à plusieurs modules, l’ensemble minimal de dépendances pour un module donné est constitué des dépendances de compilation proprement dites. De plus, s’il existe un projet de documentation (module) qui sert de point d’entrée de premier niveau pour l’ensemble de la documentation et fournit des liens de navigation, la documentation de chaque module doit l’inclure en tant que dépendance.

Lorsque QDoc génère la documentation d’un projet, il génère également un fichier ` .index ` contenant les URL de chaque entité pouvant faire l’objet d’un lien dans le projet. Chaque dépendance correspond au nom (en minuscules) d’un projet. Ce nom doit correspondre au nom de base du fichier d’index généré pour ce projet.

depends = \
    qtdoc \
    qtcore \
    qtquick

Lorsque l’on lance QDoc sur un projet comportant des dépendances et utilisant la variable ` depends `, un ou plusieurs chemins d’accès ` --indexdir ` doivent être passés en tant qu’options de ligne de commande. QDoc utilise ces chemins pour rechercher les fichiers d’index des dépendances.

qdoc mydoc.qdocconf --outputdir $PWD/html --indexdir $QT_INSTALL_DOCS

Dans ce cas, QDoc recherchera un fichier $QT_INSTALL_DOCS/qtdoc/qtdoc.index pour une dépendance de qtdoc. Si aucun fichier d'index n'est trouvé pour une dépendance, QDoc affichera un avertissement.

La commande depends accepte également la valeur spéciale « * ». Cela indique à QDoc de charger tous les fichiers d'index trouvés dans les répertoires d'index spécifiés ; en d'autres termes, « dépend de tout ».

depends = *

Voir également : indexes, project et url.

documentationinheaders

Définissez « documentationinheaders = true » pour indiquer à QDoc d’analyser également les commentaires de documentation dans les fichiers d’en-tête lors de la génération de la documentation pour les projets basés sur le C++.

Cette fonctionnalité a été introduite dans QDoc avec Qt 6.9.

exampledirs

La variable ` exampledirs ` spécifie les répertoires contenant le code source des fichiers d'exemple.

Les variables « examples » et « exampledirs » sont utilisées par la \quotefromfile, \quotefile et \example . Si les variables `examples` et `exampledirs` sont toutes deux définies, QDoc effectuera la recherche dans les deux répertoires, en commençant par `examples`, puis en passant à `exampledirs`.

QDoc parcourra les répertoires dans l'ordre indiqué et retiendra le premier fichier correspondant qu'il trouvera. Il n'effectuera la recherche que dans les répertoires spécifiés, et non dans leurs sous-répertoires.

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

Lors du traitement

\quotefromfile widgets/calculator/calculator.cpp

QDoc vérifie s’il existe un fichier nommé « calculator.cpp » répertorié comme valeur dans la examples variable. Si ce n'est pas le cas, il effectuera une recherche dans la variable exampledirs et vérifiera d'abord s'il existe un fichier nommé

$QTDIR/doc/src/widgets/calculator/calculator.cpp

Si ce n'est pas le cas, QDoc continuera à rechercher un fichier nommé

$QTDIR/examples/widgets/calculator/calculator.cpp

et ainsi de suite.

Voir également les exemples.

exemples

La variable examples vous permet de spécifier des fichiers d'exemple individuels en plus de ceux situés dans les répertoires indiqués par la exampledirs variable.

Les variables examples et exampledirs sont utilisées par la \quotefromfile, \quotefile et \example . Si les variables « examples » et exampledirs sont définies, QDoc effectuera la recherche dans les deux, d’abord dans examples puis dans exampledirs.

QDoc parcourra les valeurs répertoriées pour la variable examples, dans l’ordre spécifié, et acceptera la première qu’il trouvera.

Pour un exemple détaillé, consultez la exampledirs commande. Notez toutefois que si vous savez que le fichier figure dans la variable ` examples `, vous n’avez pas besoin de préciser son chemin d’accès :

\quotefromfile calculator.cpp

Voir également exampledirs.

examplesinstallpath

La variable « examplesinstallpath » définit le chemin d'accès racine des exemples de ce projet dans le répertoire d'exemples installé.

En supposant que le chemin d'installation racine de tous les exemples soit QT_INSTALL_EXAMPLES, alors le chemin

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

sera utilisé pour désigner le chemin d’accès d’un exemple donné au sein de ce projet de documentation. Ces chemins sont enregistrés dans le fichier manifeste des exemples, lu par Qt Creator.

Pour garantir l’exactitude des chemins d’accès, examplesinstallpath doit correspondre à l’un des répertoires répertoriés dans exampledirs. Le chemin d’accès passé en argument à chaque \example commande est relatif au chemin d’accès indiqué dans exampledirs.

Par exemple :

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

Et avec la commande suivante « \example » :

/*!
    \example basic/hello
    ...
*/

Le chemin d’accès mymodule/basic/hello est alors enregistré dans le fichier manifeste de cet exemple.

Voir aussi: exampledirs, \example, et \meta.

exemples.extensions_de_fichiers

La variable « examples.fileextensions » spécifie les extensions de fichiers que QDoc recherchera lors de la collecte des fichiers d’exemples destinés à être affichés dans la documentation.

Les extensions par défaut sont *.cpp, *.h, *.js, *.xq, *.svg, *.xml et *.ui.

Les extensions sont indiquées sous forme d'expressions standard avec des caractères génériques. Vous pouvez ajouter une extension de fichier au filtre à l'aide de « += ». Par exemple :

examples.fileextensions += *.qrc

Voir également headers.fileextensions.

examples.warnaboutmissingimages

Lors du traitement de la documentation d'exemples, QDoc peut émettre des avertissements si un exemple ne contient aucune image. Cet avertissement peut être désactivé en définissant la variable de configuration suivante dans le fichier .qdocconf du projet :

examples.warnaboutmissingimages = false

Cette variable de configuration a été introduite dans QDoc avec Qt 6.9.

Voir également examples.warnaboutmissingprojectfiles.

examples.warnaboutmissingprojectfiles

Lors du traitement de la documentation d'exemples, QDoc peut émettre des avertissements si un exemple ne contient pas de fichier de projet. Cet avertissement peut être désactivé en définissant la variable de configuration suivante dans le fichier .qdocconf du projet :

examples.warnaboutmissingprojectfiles = false

Cette variable de configuration a été introduite dans QDoc avec Qt 6.9.

Voir également examples.warnaboutmissingimages.

excludedirs

La variable ` excludedirs ` sert à répertorier les répertoires qui ne doivent pas être traités par QDoc, même si ces mêmes répertoires sont inclus par les variables `sourcedirs ` ou `headerdirs `.

Par exemple :

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

Lorsqu’il est exécuté, QDoc exclura les répertoires répertoriés de son analyse. Les fichiers contenus dans ces répertoires ne seront pas lus par QDoc.

Voir également excludefiles.

excludefiles

La variable « excludefiles » vous permet de spécifier les fichiers individuels qui ne doivent pas être traités par QDoc.

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

Si vous incluez ce qui précède dans votre fichier qdocconf pour qtbase, aucune documentation de classe ne sera générée pour QWidget.

Depuis Qt 5.6, les caractères génériques simples (« * » et « ? ») sont également reconnus par ` excludefiles`. Par exemple, pour exclure l'analyse de tous les fichiers d'en-tête Qt privés, définissez ce qui suit :

excludefiles += "*_p.h"

Voir également excludedirs.

extraimages

La variable extraimages indique à QDoc d'intégrer des images spécifiques dans la documentation générée.

QDoc copie automatiquement un fichier image depuis imagedirs vers le répertoire de sortie s'il est référencé par la variable \image ou \inlineimage . Si vous souhaitez copier des images supplémentaires, vous devez les spécifier à l'aide de la variable extraimages.

La syntaxe générale est la suivante format.extraimages = image.

Exemple :

HTML.extraimages = images/qt-logo.png

Voir également images et imagedirs.

fausses informations

La variable « falsehoods » définit la valeur de vérité de certains symboles du préprocesseur comme étant « false ».

Les valeurs de cette variable sont des expressions régulières (voir QRegularExpression pour plus de détails). Si cette variable n’est pas définie pour un symbole du préprocesseur, QDoc considère que sa valeur de vérité est « vrai ». La seule exception est « 0 », qui est toujours considéré comme « faux ».

QDoc reconnaîtra et pourra évaluer la syntaxe de préprocesseur suivante :

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

Cependant, face à une syntaxe inconnue telle que

#if NOTYET
    ...
#endif

QDoc l'évaluera par défaut comme étant vrai, à moins que le symbole du préprocesseur ne soit spécifié dans l'entrée de la variable ` falsehoods ` :

falsehoods = NOTYET

Voir également « defines ».

generateindex

La variable generateindex contient une valeur booléenne qui indique s’il faut générer un fichier d’index lors de la création de la documentation HTML.

Par défaut, un fichier d'index est toujours généré avec la documentation HTML ; cette variable n'est donc généralement utilisée que pour désactiver cette fonctionnalité (en définissant la valeur sur « false ») ou pour activer la génération d'index pour la sortie WebXML (en définissant la valeur sur « true »).

headerdirs

La variable headerdirs spécifie les répertoires contenant les fichiers d'en-tête associés aux fichiers source .cpp utilisés dans la documentation.

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

Lorsqu’il est exécuté, QDoc commence par lire les en-têtes spécifiés dans la headers variable, ainsi que ceux situés dans les répertoires indiqués par la variable headerdir (y compris tous les sous-répertoires), afin de construire une structure interne des classes et de leurs fonctions.

Il lira ensuite les fichiers source spécifiés dans la sources, ainsi que ceux situés dans les répertoires spécifiés dans la sourcedirs (y compris tous les sous-répertoires), en fusionnant la documentation avec la structure extraite des fichiers d'en-tête.

Si les variables headers et headerdirs sont toutes deux définies, QDoc les parcourra toutes les deux, en commençant par headers puis headerdirs.

Dans les répertoires spécifiés, QDoc ne lira que les fichiers dont l’ fileextensions est spécifiée dans la headers.fileextensions variable. Les fichiers spécifiés par headers seront lus sans tenir compte de leurs extensions.

Voir également headers et headers.fileextensions.

headers

La variable « headers » vous permet de spécifier des fichiers d'en-tête individuels en plus de ceux situés dans les répertoires indiqués par la headerdirs variable.

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

Lors du traitement de la variable headers, QDoc se comporte de la même manière que lors du traitement de la headerdirs variable. Pour plus d’informations, consultez la headerdirs variable.

Voir également headerdirs.

extensions_de_fichiers_d'en-têtes

La variable « headers.fileextensions » spécifie l'extension utilisée par les en-têtes.

Lors du traitement des fichiers d'en-tête spécifiés dans la headerdirs variable, QDoc ne lira que les fichiers dont les extensions sont spécifiées dans la variable headers.fileextensions. De cette manière, QDoc évite de perdre du temps à lire des fichiers non pertinents.

Les extensions par défaut sont *.ch, *.h, *.h++, *.hh, *.hpp et *.hxx.

Les extensions sont indiquées sous forme d'expressions standard avec des caractères génériques. Vous pouvez ajouter une extension de fichier au filtre à l'aide de « += ». Par exemple :

header.fileextensions += *.H

Voir également headerdirs.

includepaths

La variable ` includepaths ` sert à transmettre des chemins d'inclusion supplémentaires à l'analyseur Clang utilisé par QDoc pour analyser le code C++ à la recherche de commentaires de documentation.

Cette variable accepte une liste de chemins, préfixés par -I (chemin d'inclusion), -F (chemin d'inclusion des frameworks macOS) ou -isystem (chemin d'inclusion système). Si aucun préfixe n'est indiqué, -I est utilisé par défaut.

Les chemins relatifs au fichier .qdocconf courant sont convertis en chemins absolus. Les chemins qui n’existent pas dans le système de fichiers sont ignorés.

Voir aussi moduleheader.

includeprivate

Utilisez « includeprivate » pour inclure les membres privés des classes C++ dans votre documentation. QDoc exclut normalement les fonctions, types et variables privés de la documentation générée.

Pour inclure tous les membres privés, définissez l'option « includeprivate » sur « true » :

includeprivate = true

Vous pouvez également activer des types de membres spécifiques :

# Include only private functions
includeprivate.functions = true

# Include only private types (classes, enums, typedefs)
includeprivate.types = true

# Include only private variables
includeprivate.variables = true

Les paramètres spécifiques prévalent sur le paramètre global. Par exemple :

includeprivate = true
includeprivate.types = false

Cette configuration inclut les fonctions et variables privées, mais exclut les types privés.

QDoc a introduit l'includeprivate dans Qt 6.11.

internalfilepatterns

La variable internalfilepatterns spécifie des modèles de chemins d'accès aux fichiers permettant d'identifier les fichiers d'implémentation internes. Les classes déclarées dans des fichiers correspondant à ces modèles sont automatiquement marquées comme « internes », tout comme l'ensemble de leurs membres (propriétés, fonctions, énumérations, types imbriqués). Les fonctions libres, les énumérations et les typedefs au niveau de la portée du fichier ne sont pas affectés par ce paramètre.

Lorsque `showinternal` est défini sur ` false ` (valeur par défaut), ces entités sont exclues de la validation de la documentation. Lorsque ` showinternal ` est défini sur ` true`, elles sont incluses dans la documentation mais conservent leur statut « Interne », ce qui permet aux générateurs de leur appliquer une mise en forme différente (par exemple, en ajoutant des indicateurs visuels pour les API internes).

Ceci est utile pour les en-têtes d’implémentation privés qui contiennent des classes ne faisant pas partie de l’interface publique documentée. Dans Qt, cela inclut les en-têtes privés se terminant par _p.h.

Syntaxe des modèles

Les modèles prennent en charge deux syntaxes :

• Motifs glob de type Shell: caractères génériques simples où « * » correspond à n'importe quel caractère et « ? » correspond à exactement un caractère. Les motifs glob sont comparés uniquement au nom de fichier, et non au chemin d'accès complet, ce qui les rend idéaux pour des motifs tels que « *_p.h ».
• Expressions régulières: pour la correspondance basée sur le chemin d’accès, utilisez la syntaxe des expressions régulières. Tout motif contenant des métacaractères d’expressions régulières (^$[]{}()|+\\.) est traité comme une expression régulière et comparé au chemin d’accès complet normalisé du fichier.

Les motifs sont comparés en utilisant des barres obliques (/) comme séparateurs de répertoires. QDoc normalise les séparateurs de chemin en interne ; utilisez donc toujours / dans les motifs, quelle que soit la plateforme.

Lorsqu’une classe est marquée comme « Interne » en raison de l’emplacement de son fichier, le statut « Interne » se propage automatiquement à tous ses membres à travers la hiérarchie des nœuds.

Exemple - Convention Qt (glob) :

internalfilepatterns = *_p.h

Correspond à tout fichier se terminant par _p.h, quel que soit le niveau de répertoire.

Exemple - Modèles de noms de fichiers multiples (glob) :

internalfilepatterns = *_p.h *_impl.h *_pch.h

Correspond aux fichiers se terminant par _p.h, _impl.h ou _pch.h.

Exemple - Correspondance basée sur un répertoire (expressions régulières) :

internalfilepatterns = .*/internal/.*\.h

Correspond à n'importe quel fichier .h situé dans n'importe quel répertoire internal, à n'importe quel niveau de la structure.

Exemple - Motifs multiples :

internalfilepatterns = *_p.h .*/private/.*\.h

Combine des modèles glob pour les cas simples et des expressions régulières pour les chemins d'accès complexes.

QDoc a introduit la fonctionnalité « internalfilepatterns » dans Qt 6.11.

Voir aussi : excludedirs et excludefiles.

ignorewords

La variable ignorewords permet de spécifier une liste de chaînes de caractères que QDoc ignorera lors de la résolution des cibles des liens hypertextes.

QDoc dispose d’une fonctionnalité de création automatique de liens, qui tente de créer des liens pour les mots ressemblant à des entités C++ ou QML. Plus précisément, une chaîne est éligible à la création automatique de liens si elle comporte au moins trois caractères, ne contient aucun espace et si elle

• est un mot en camelCase, c'est-à-dire qu'elle contient au moins un caractère majuscule à un indice supérieur à zéro, ou
• contient la sous-chaîne « () » ou « :: », ou
• contient au moins un caractère spécial, @ ou _.

L'ajout d'un mot qualifié à ignorewords empêche QDoc de créer automatiquement un lien vers ce mot. Par exemple, si le mot OpenGL est une cible de lien valide (une section, \pageou \externalpage titre), il est possible d’éviter la création d’un lien hypertexte à chaque occurrence grâce à

ignorewords += OpenGL

La création explicite de liens avec \l continue de fonctionner pour les mots ignorés.

La variable ` ignorewords ` a été introduite dans QDoc 5.14.

ignoresince

La variable ignoresince sert à définir une valeur seuil pour les versions transmises à la \since commande. Toutes les commandes « \since » qui définissent une version inférieure à cette valeur seuil sont ignorées et ne génèrent aucun résultat.

Les valeurs de seuil sont spécifiques à chaque projet. Le nom du projet peut être défini en tant que sous-variable. Le nom de projet par défaut est Qt. Par exemple :

ignoresince      = 5.0
ignoresince.QDoc = 5.0

Ces commandes ignoreront les commandes ` \since ` pour lesquelles la version majeure est égale ou inférieure à 4 et où le projet est soit ` QDoc `, soit non défini.

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

La variable ignoresince a été introduite dans QDoc 5.15.

Voir aussi \since.

imagedirs

La variable ` imagedirs ` spécifie les répertoires contenant les images utilisées dans la documentation.

Les images variables et imagedirs sont utilisées par la \image commandes \inlineimage . Si les deux variables images et imagedirs sont définies, QDoc effectuera la recherche dans les deux. D'abord dans images, puis dans imagedirs.

QDoc parcourra les répertoires dans l’ordre indiqué et retiendra le premier fichier correspondant qu’il trouvera. Il n’effectuera la recherche que dans les répertoires spécifiés, et non dans leurs sous-répertoires.

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

Lors du traitement

\image calculator-example.png

QDoc vérifiera alors s’il existe un fichier nommé calculator-example.png répertorié comme valeur dans la variable images. Si ce n’est pas le cas, il recherchera dans la variable imagedirs:

$QTDIR/doc/src/images/calculator-example.png

Si le fichier n’existe pas, QDoc recherchera un fichier nommé

$QTDIR/examples/calculator-example.png

imagesoutputdir

La variable imagesoutputdir contrôle le nom du sous-répertoire, situé dans le répertoire de sortie, que QDoc utilise pour stocker les images.

La valeur par défaut de imagesoutputdir est images.

Les fichiers image passés en argument à \image et \inlineimage sont copiés dans ce répertoire.

La définition d'un répertoire de sortie personnalisé pour les images est utile dans le cadre de la compilation de documentation multi-modules, lorsque plusieurs projets de documentation sont configurés pour utiliser un répertoire de sortie partagé. Par exemple, avec la configuration (partagée) suivante :

imagesoutputdir = images/${project}

Chaque projet de documentation de la compilation utilise <outputdir>/images/<project name> pour stocker les images, ce qui évite que des fichiers image portant le même nom ne se remplacent mutuellement.

Cette variable a été introduite dans QDoc avec Qt 6.11.

langue

La variable language spécifie la langue du code source utilisé dans la documentation. Plus précisément, elle définit la langue par défaut pour l'analyse du code source au sein des blocs \code.. \endcode.

language = Cpp

La langue par défaut est le C++ (Cpp) ; il n’est pas nécessaire de la spécifier explicitement. Si les extraits de code de la documentation sont principalement constitués de code QML, définissez QML comme langue par défaut :

language = QML

Voir aussi \code.

informations sur la localisation

La variable booléenne « locationinfo » détermine si les informations de localisation détaillées relatives à chaque entité sont enregistrées dans les fichiers « .index » et « .webxml » (lorsqu’on utilise le format de sortie WebXML).

Les informations de localisation comprennent le chemin d'accès complet et le numéro de ligne de la déclaration ou du bloc de commentaires de documentation dans le code source.

En définissant cette variable sur « false », les informations de localisation sont désactivées :

locationinfo = false

La valeur par défaut est « true ».

La variable « locationinfo » a été introduite dans QDoc 5.15.

logwarnings

La variable booléenne logwarnings détermine si QDoc écrit les messages d'avertissement dans un fichier journal en plus de les afficher sur stderr.

Lorsqu’elle est définie sur ` true`, QDoc crée un fichier journal nommé ` <project>-qdoc-warnings.log ` dans le répertoire de sortie et y consigne tous les messages d’avertissement. Les avertissements sont également toujours consignés sur `stderr`, comme d’habitude.

Le fichier journal comprend un en-tête contenant des informations sur le projet et, par défaut, les arguments de ligne de commande utilisés pour lancer QDoc, à des fins de reproductibilité.

La valeur « true » active la journalisation des avertissements :

logwarnings = true

La valeur par défaut est « false ».

Cette fonctionnalité est utile pour les ensembles de documentation volumineux ou les environnements d'intégration continue (CI), où les avertissements peuvent être nombreux et défiler trop rapidement pour être analysés de manière systématique.

La variable logwarnings a été introduite dans QDoc 6.11.

logwarnings.disablecliargs

La sous-variable booléenne logwarnings.disablecliargs permet de déterminer si les arguments de l'interface en ligne de commande (CLI) doivent être omis des en-têtes des fichiers journaux d'avertissements.

logwarnings.disablecliargs = true

Lorsqu’elle est définie sur ` true`, les arguments de ligne de commande sont omis de l’en-tête du fichier de journal, ce qui rend les fichiers de journal portables d’un environnement à l’autre. Cela s’avère utile pour les suites de tests et les systèmes d’intégration continue (CI) où les arguments de ligne de commande contiennent des chemins d’accès spécifiques à l’environnement et des répertoires temporaires.

La valeur par défaut est « false ». La variable « logwarnings.disablecliargs » a été introduite dans QDoc 6.11.

macro

La variable macro permet de créer vos propres commandes QDoc simples. La syntaxe est la suivante : macro.command = definition. La commande est limitée à une combinaison de lettres et de chiffres, mais ne peut contenir aucun caractère spécial tel que le tiret ou le trait de soulignement. La définition s’écrit en utilisant la syntaxe QDoc.

L'utilisation d'une variable de macro peut être limitée à un seul type de génération de sortie. En ajoutant « .HTML » au nom de la macro, par exemple, celle-ci n'est utilisée que lors de la génération d'une sortie HTML.

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

La première macro définit la commande « \key » pour afficher son argument en caractères gras. La deuxième macro définit la commande « \raisedaster » pour afficher un astérisque en exposant, mais uniquement lors de la génération de code HTML.

Une macro peut également prendre jusqu’à sept paramètres :

macro.hello            = "Hello \1!"

Les paramètres sont transmis aux macros de la même manière qu’aux autres commandes :

\hello World

Lorsque vous utilisez plusieurs paramètres, ou lorsqu'un argument contient des espaces, placez chaque argument entre accolades :

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

Une option de macro spéciale, `match`, peut être ajoutée pour permettre une correspondance supplémentaire avec des expressions régulières pour les macros développées.

Par exemple,

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

Cela crée une macro « \qtminorversion » qui se développe en indiquant la version mineure en fonction de la variable d'environnement QT_VER.

Une macro qui définit un motif de correspondance affiche tous les groupes de capture (parenthèses) concaténés, ou la chaîne exacte correspondant au motif si celui-ci ne contient aucun groupe de capture.

Pour plus d’informations sur les macros prédéfinies, consultez la section Macros.

manifestmeta

La variable « manifestmeta » spécifie du méta-contenu supplémentaire pour les fichiers de manifeste d'exemple générés par QDoc.

Pour plus d'informations, consultez la section « Contenu méta du manifeste ».

moduleheader

La variable « moduleheader » définit le nom de l'en-tête d'un module C++ documenté.

Les projets qui documentent des API C++ nécessitent un en-tête au niveau du module qui inclut toutes les classes publiques, tous les espaces de noms et tous les fichiers d'en-tête du module. L'analyseur Clang de QDoc utilise ce fichier pour générer un en-tête précompilé (PCH) pour le module, afin d'accélérer l'analyse des fichiers source.

Par défaut, le nom du projet est également utilisé comme nom de l'en-tête de module.

project = QtCore

Avec le nom de projet ci-dessus, QDoc recherche un en-tête de module nommé QtCore dans tous les chemins d’inclusion connus ; il utilise d’abord les chemins passés en arguments de ligne de commande, puis ceux répertoriés dans la variable `includepaths`.

QDoc émettra un avertissement si l'en-tête de module n'est pas trouvé. Il tentera alors de créer un en-tête de module artificiel à partir des en-têtes répertoriés dans la variable `headerdirs`.

Pour les projets de documentation Qt, le système de compilation fournit généralement à QDoc les chemins d’inclusion corrects permettant de localiser l’en-tête de module, à condition que la variable ` project ` soit correctement définie. La variable ` moduleheader ` fournit un nom de fichier alternatif que QDoc doit rechercher.

Pour les projets ne contenant aucune documentation C++, utilisez la parsecppcomments pour désactiver l’analyse syntaxique du C++. Définir ` moduleheader ` sur une chaîne vide produit le même effet et est pris en charge pour des raisons de compatibilité ascendante :

# No C++ code to document in this project
moduleheader =

Voir également parsecppcomments, ` includepaths` et ` project`.

langage naturel

La variable « naturallanguage » spécifie la langue naturelle utilisée pour la documentation générée par QDoc.

naturallanguage = zh-Hans

Par défaut, la langue naturelle est « en » pour des raisons de compatibilité avec l'ancienne documentation.

QDoc ajoutera les informations relatives à la langue naturelle au code HTML qu’il génère, à l’aide des attributs lang et xml:lang.

Voir également sourceencoding, outputencoding, C.7. Les attributs lang et xml:lang et la bonne pratique n° 13 : Utilisation des codes Hans et Hant.

navigation

Les sous-variables « navigation », si elles sont définies, déterminent la page d'accueil, la page de destination, la page des classes C++ et la page des types QML qui apparaissent dans la barre de navigation générée pour chaque page.

Dans un projet comportant plusieurs sous-projets (par exemple, des modules Qt), chaque sous-projet définit généralement sa propre page d'accueil, tandis que la même page d'accueil est utilisée pour tous les sous-projets.

Sous-variables

Par exemple :

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

La configuration ci-dessus génère la barre de navigation suivante pour le type QML « Item » :

Qt 5.10 > Qt Quick > QML Types > Item QML Type

Table des matières et liens de navigation

S'il existe une ou plusieurs pages faisant office de table des matières (TDM), répertoriez leurs titres dans navigation.toctitles afin d'automatiser la génération des liens de navigation (pageprécédente et suivante ) pour toutes les pages répertoriées dans une TDM.

QDoc attend une \list de liens sur chaque page de TOC. Les sous-listes imbriquées sont autorisées.

Par exemple,

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
        \list
            \li \l {What's new in v1.3} {v1.3}
            \li \l {What's new in v1.2} {v1.2}
            \li \l {What's new in v1.1} {v1.1}
        \endlist
\endlist

Depuis la version 6.10 de QDoc, \generatelist peuvent apparaître dans la table des matières :

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
    \generatelist [descending] whatsnew
\endlist

Ici, le résultat est similaire à celui de la première \list, en supposant que les trois pages « Nouveautés » fassent partie du même groupe whatsnew.

Voir aussi \ingroup.

signaux-surchargés-cible

Valeur par défaut : connecting-overloaded-signals

La variable ` overloadedsignalstarget ` spécifie la cible de lien utilisée dans les notes générées automatiquement pour les signaux surchargés.

Lorsque QDoc rencontre un signal surchargé, il génère une note contenant un lien vers la documentation d'aide sur la connexion aux signaux surchargés. Par défaut, ce lien pointe vers une cible nommée connecting-overloaded-signals.

Les projets peuvent personnaliser ce paramètre pour créer un lien vers leur propre documentation :

# Link to a target within the project
overloadedsignalstarget = signals-guide.html#overloaded-signals

# Link to external documentation
overloadedsignalstarget = https://example.com/docs/signals.html#overloaded-signals

La cible peut être :

• Un simple nom de cible (à utiliser avec les \target les commandes) : connecting-overloaded-signals
• Une URL relative : signals-guide.html#overloaded-signals
• Une URL absolue : https://example.com/docs/signals.html#overloaded-signals

Voir également overloadedslotstarget.

overloadedslotstarget

Valeur par défaut : connecting-overloaded-slots

La variable « overloadedslotstarget » spécifie la cible du lien utilisée dans les notes générées automatiquement pour les emplacements surchargés.

Lorsque QDoc rencontre un slot surchargé, il génère une note contenant un lien vers la documentation d'aide sur la connexion aux slots surchargés. Par défaut, ce lien pointe vers une cible nommée connecting-overloaded-slots.

Les projets peuvent personnaliser ce paramètre pour créer un lien vers leur propre documentation :

# Link to a target within the project
overloadedslotstarget = signals-guide.html#overloaded-slots

# Link to external documentation
overloadedslotstarget = https://example.com/docs/slots.html#overloaded-slots

La cible peut être :

• Un simple nom de cible (à utiliser avec les \target les commandes) : connecting-overloaded-slots
• Une URL relative : signals-guide.html#overloaded-slots
• Une URL absolue : https://example.com/docs/slots.html#overloaded-slots

Voir également overloadedsignalstarget.

outputdir

La variable outputdir spécifie le répertoire dans lequel QDoc placera la documentation générée.

outputdir = $QTDIR/doc/html

place la documentation de référence Qt générée dans $QTDIR/doc/html. Par exemple, la documentation de la classe QWidget se trouve dans

$QTDIR/doc/html/qwidget.html

Les images associées seront placées dans un sous-répertoire images.

encodage_de_sortie

La variable outputencoding spécifie l'encodage utilisé pour la documentation générée par QDoc.

outputencoding = UTF-8

Par défaut, l'encodage de sortie est ISO-8859-1 (Latin1) pour des raisons de compatibilité avec l'ancienne documentation. Lors de la génération de documentation pour certaines langues, en particulier les langues non européennes, cela n'est pas suffisant et un encodage tel que UTF-8 est nécessaire.

QDoc encodera le code HTML à l’aide de cet encodage et générera les déclarations appropriées pour indiquer aux navigateurs quel encodage est utilisé. La variable de configuration `naturallanguage` doit également être spécifiée afin de fournir aux navigateurs un ensemble complet d’informations sur l’encodage des caractères et la langue.

Voir également outputencoding et naturallanguage.

outputformats

La variable « outputformats » spécifie le ou les formats de la documentation générée.

outputformats Depuis Qt 5.11, QDoc prend en charge les formats HTML et WebXML ; depuis Qt 5.15, il peut également générer la documentation au format DocBook. Si aucun format de sortie n'est spécifié, QDoc génère la documentation au format HTML (format par défaut). Tous les formats de sortie peuvent être spécifiés, avec des répertoires de sortie dédiés et d'autres paramètres. Par exemple :

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

Cela génère une documentation HTML en utilisant les paramètres par défaut, ainsi qu'une documentation WebXML dans le sous-répertoire de sortie webxml.

outputprefixes

La variable outputprefixes spécifie une correspondance entre les types de fichiers et les préfixes à ajouter au début des noms de fichiers de sortie dans la documentation générée.

QDoc prend en charge l'ajout d'un préfixe de sortie aux noms de fichiers des pages de référence des types QML, des classes C++, des espaces de noms et des fichiers d'en-tête.

outputprefixes     = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-

Par défaut, les fichiers contenant la documentation API des types QML sont préfixés par « qml- ». Dans l'exemple ci-dessus, c'est le préfixe « uicomponents- » qui est utilisé à la place.

De même, les pages de documentation sur les types C++ sont précédées du préfixe components- dans l'exemple ci-dessus. Par défaut, les pages sur les types C++ n'ont pas de préfixe.

outputsuffixes

La variable outputsuffixes définit une correspondance entre les types de fichiers et les suffixes à ajouter au nom du module ou du type tels qu’ils apparaissent dans les noms des fichiers de sortie.

QDoc prend en charge l'ajout d'un suffixe de sortie aux noms de fichiers des pages de modules, des types QML, des classes C++, des espaces de noms et des pages de référence des fichiers d'en-tête.

Par défaut, aucun suffixe n’est utilisé. Le suffixe de sortie QML, s’il est défini, est appliqué au nom du module tel qu’il apparaît dans les noms de fichiers des pages de types QML et de modules QML.

Les noms de fichiers des types C++ n'incluent pas le nom du module. Le suffixe de sortie CPP, s'il est défini, est appliqué en tant que suffixe au nom du type.

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

Avec les définitions ci-dessus, pour un nom de module QML « FooBar » et le préfixe de sortie par défaut (qml-), le nom du fichier généré pour un type QML « FooWidget » est « qml-foobar-tp-foowidget.html ».

De même, pour une classe C++ QFoobar, QDoc génère qfoobar-tp.html.

La variable outputsuffixes a été introduite dans QDoc 5.6.

parsecppcomments

La variable parsecppcomments détermine si QDoc analyse les fichiers source C++ à l'aide de l'analyseur syntaxique C++ basé sur Clang.

Lorsqu’elle est définie sur ` false`, QDoc ignore l’analyse Clang et la génération de fichiers PCH pour le projet, et traite à la place les fichiers ` .cpp ` à l’aide de l’analyseur de documentation pur. Cela s’avère utile pour les projets qui documentent uniquement des API QML, dans lesquels les fichiers source C++ contiennent des commentaires QDoc mais aucune entité C++ à documenter.

La valeur par défaut est « true ».

parsecppcomments = false

La variable parsecppcomments a été introduite dans QDoc à partir de Qt 6.12.

Voir aussi moduleheader.

qhp

Les sous-variables « qhp » servent à définir les informations à écrire dans les fichiers du projet « Qt Help » (qhp).

Reportez-vous au chapitre « Création de fichiers de projet d’aide » pour plus d’informations sur ce processus.

Depuis QDoc 6.6, le fait de définir la variable de base qhp sur true implique qu’une configuration de projet d’aide valide est attendue :

qhp = true

Ainsi, si une configuration de projet ne définit pas qhp.projects, QDoc affiche un avertissement. Cela permet de s'assurer que tous les projets de documentation partageant un fichier .qdocconf de niveau supérieur (comme dans Qt) sont correctement configurés.

Pour désactiver cet avertissement, définissez la variable sur false.

showautogenerateddocs

La variable booléenne showautogenerateddocs détermine si la documentation générée automatiquement par QDoc pour les fonctions membres spéciales explicitement définies par défaut ou supprimées apparaît dans la sortie.

QDoc génère cette documentation lorsqu’aucun \fn bloc ne documente pas une telle fonction. La documentation rédigée avec \fn a toujours la priorité sur le texte généré et n’est pas affectée par cette variable.

En définissant cette variable sur « false », la documentation générée automatiquement est omise :

showautogenerateddocs = false

La valeur par défaut est « true ».

La variable showautogenerateddocs a été introduite dans QDoc 6.12.

sourcedirs

La variable sourcedirs spécifie les répertoires contenant les fichiers .cpp ou .qdoc utilisés dans la documentation.

sourcedirs  += .. \
               ../../../examples/gui/doc/src

Lorsqu’il est exécuté, QDoc commence par lire les en-têtes spécifiés dans la header variable, ainsi que celles situées dans les répertoires indiqués par la variable headerdir (y compris tous les sous-répertoires), afin de construire une structure interne des classes et de leurs fonctions.

Il lira ensuite les fichiers source spécifiés dans la sources, ainsi que ceux situés dans les répertoires indiqués par la sourcedirs variable (y compris tous les sous-répertoires), en fusionnant la documentation avec la structure extraite des fichiers d'en-tête.

Si les variables sources et sourcedirs sont toutes deux définies, QDoc les parcourra toutes les deux, en commençant par sources puis sourcedirs.

Dans les répertoires spécifiés, QDoc ne lira que les fichiers dont l’ fileextensions est spécifiée dans la sources.fileextensions variable. Les fichiers spécifiés par sources seront lus quelle que soit leur extension.

Voir également sources et sources.fileextensions.

sourceencoding

La variable « sourceencoding » spécifie l'encodage utilisé pour le code source et la documentation.

sourceencoding = UTF-8

Par défaut, l'encodage source est ISO-8859-1 (Latin1) pour des raisons de compatibilité avec l'ancienne documentation. Pour certaines langues, en particulier les langues non européennes, cela n'est pas suffisant et un encodage tel que UTF-8 est nécessaire.

Bien que QDoc utilise cet encodage pour lire les fichiers source et de documentation, les limitations des compilateurs C++ peuvent vous empêcher d’utiliser des caractères non ASCII dans les commentaires du code source. Dans ce genre de cas, il est possible de rédiger la documentation de l’API entièrement dans les fichiers de documentation.

Voir également naturallanguage et outputencoding.

sources

La variable « sources » vous permet de spécifier des fichiers source individuels en plus de ceux situés dans les répertoires indiqués par la variable « sourcedirs ».

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

Lors du traitement de la variable ` sources `, QDoc se comporte de la même manière que lors du traitement de la variable `sourcedirs `. Pour plus d’informations, consultez la section consacrée à la variable ` sourcedirs `.

Voir également sourcedirs.

sources.fileextensions

La variable « sources.fileextensions » permet de filtrer les fichiers d'un répertoire source.

Lors du traitement des fichiers source spécifiés dans la sourcedirs variable, QDoc ne lira que les fichiers dont l'extension correspond à celles spécifiées dans la variable sources.fileextensions. QDoc évite ainsi de perdre du temps à lire des fichiers non pertinents.

Les extensions par défaut sont *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml et *.qdoc.

Les extensions sont indiquées sous forme d'expressions standard avec des caractères génériques. Vous pouvez ajouter une extension de fichier au filtre à l'aide de « += ». Par exemple :

sources.fileextensions += *.CC

Voir également sourcedirs et sources.

faux

La variable ` spurious ` exclut de la sortie les avertissements QDoc spécifiés. Les avertissements sont spécifiés à l'aide d'expressions standard avec caractères génériques.

spurious = "Cannot find .*" \
"Missing .*"

garantit que les avertissements correspondant à l’une ou l’autre de ces expressions ne figureront pas dans la sortie lors de l’exécution de QDoc. Par exemple, l’avertissement suivant serait-il omis de la sortie :

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

La variable syntaxhighlighting spécifie si QDoc doit effectuer la mise en évidence de la syntaxe sur le code source cité dans la documentation qu'il génère.

syntaxhighlighting = true

activera la mise en évidence de la syntaxe pour tous les langages de programmation pris en charge.

tabsize

La variable tabsize définit la taille d'un caractère de tabulation.

tabsize = 4

donnera au caractère de tabulation une taille équivalente à 4 espaces. La valeur par défaut de la variable est 8 ; il n'est pas nécessaire de la spécifier.

fichier de balises

La variable ` tagfile ` spécifie le fichier de balises Doxygen à générer lors de la création du code HTML.

version

La variable version spécifie le numéro de version du logiciel documenté.

version = 5.6.0

Lorsqu’un numéro de version est spécifié (à l’aide de la version ou versionsym dans un fichier ` .qdocconf `), celui-ci est accessible via la commande ` \version ` correspondante pour être utilisé dans la documentation.

Voir aussi versionsym.

versionsym

La variable « versionsym » spécifie un symbole du préprocesseur C++ qui définit le numéro de version du logiciel documenté.

versionsym = QT_VERSION_STR

QT_VERSION_STR Elle est définie dans qglobal.h comme suit

#define QT_VERSION_STR   "5.14.1"

Lorsqu’un numéro de version est spécifié (à l’aide de la version ou versionsym dans un fichier d'.qdocconf ), il est accessible via la commande \version correspondante pour être utilisé dans la documentation.

Voir aussi \version.

warninglimit

La variable ` warninglimit ` définit le nombre maximal d'avertissements de documentation autorisés. Si cette limite est dépassée, QDoc continue de fonctionner normalement mais se termine en renvoyant le nombre d'avertissements comme code d'erreur. Si la limite n'a pas été dépassée ou si ` warninglimit ` n'a pas été définie, le processus QDoc se termine avec le code 0, à condition qu'il n'y ait pas eu d'autres erreurs critiques.

Définir la variable warninglimit sur 0 entraîne un échec dès le premier avertissement.

Par exemple,

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

La variable warninglimit a été introduite dans Qt 5.11.