Variables de configuration génériques

Les variables de configuration générales de QDoc vous permettent de définir où QDoc trouvera les différents fichiers sources 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 manipulations mineures de 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 s'assurer 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.

langues de code

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 langues que QDoc ne peut pas analyser et de générer du HTML qui peut être mis en évidence ou traité par d'autres outils.

codelanguages = Python Rust Java Swift "C#"

Étant donné que QDoc peut traiter C++ (Cpp), QML et du texte, il n'est pas nécessaire de spécifier ces langages dans cette liste. Les noms de langages contenant des caractères spéciaux, tels que C#, doivent être mis entre guillemets lorsqu'ils sont inclus dans cette liste.

La variable codelanguages a été introduite dans QDoc 6.11 pour permettre à la documentation en ligne de Qt d'utiliser la coloration syntaxique pour un sous-ensemble des langues prises 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 inclus.

définit

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

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

defines = QT_GUI_LIB

Cela garantit que QDoc traitera le code qui nécessite la définition de ces symboles. En voici un 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 les symboles de préprocesseur manuellement sur la ligne de commande à l'aide de l'option -D. En voici un 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 aussi faussetés et \if.

dépend

La variable depends définit une liste d'autres projets de documentation dont ce projet dépend pour la résolution des cibles de lien pour l'héritage de type et tout autre élément vers lequel la documentation doit être liée.

Comme Qt lui-même, la documentation pour Qt est distribuée à travers plusieurs modules. Dans un projet de documentation multi-modules, l'ensemble minimum de dépendances pour un seul module consiste en des dépendances de construction réelles. En outre, 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 qui fournit des liens de navigation, la documentation de chaque module doit l'inclure en tant que dépendance.

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

depends = \
    qtdoc \
    qtcore \
    qtquick

Lors de l'invocation de QDoc sur un projet ayant des dépendances et utilisant la variable depends, un ou plusieurs chemins -indexdir doivent être transmis en tant qu'option(s) 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

Avec l'option ci-dessus, QDoc recherchera un fichier $QT_INSTALL_DOCS/qtdoc/qtdoc.index pour une dépendance à qtdoc. Si un fichier d'index pour une dépendance n'est pas trouvé, QDoc affichera un avertissement.

La commande depends accepte également la valeur spéciale "*". Cette valeur indique à QDoc de charger tous les fichiers d'index trouvés dans les répertoires d'index spécifiés, c'est-à-dire qu'il "dépend de tout".

depends = *

Voir aussi index, projet et url.

documentation dans les en-têtes

Définir documentationinheaders = true pour demander à QDoc d'analyser les commentaires de documentation également 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.

exemples

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

Les variables examples et exampledirs sont utilisées par la commande \quotefromfile, \quotefile et \example sont utilisées par les commandes , et . Si les variables examples et exampledirs sont toutes deux définies, QDoc effectuera une recherche dans les deux, d'abord dans examples puis dans exampledirs.

QDoc recherchera dans les répertoires dans l'ordre spécifié et acceptera le premier fichier correspondant qu'il trouvera. Il ne cherchera que dans les répertoires spécifiés, pas dans les sous-répertoires.

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

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

Lors du traitement des

\quotefromfile widgets/calculator/calculator.cpp

QDoc vérifiera s'il existe un fichier appelé calculator.cpp listé en tant que valeur dans la examples comme valeur. Si ce n'est pas le cas, il cherchera dans la variable exampledirs, et verra d'abord s'il existe un fichier appelé

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

Si ce n'est pas le cas, QDoc continuera à chercher un fichier appelé

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

et ainsi de suite.

Voir aussi les exemples.

exemples

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

Les variables examples et exampledirs sont utilisées par les variables \quotefromfile, \quotefile et \example sont utilisées par les commandes , et . Si les variables examples et exampledirs sont définies, QDoc effectuera une recherche dans les deux, d'abord dans examples, puis dans exampledirs.

QDoc recherchera 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é, voir la commande exampledirs pour un exemple détaillé. Notez toutefois que si vous savez que le fichier est répertorié dans la variable examples, vous n'avez pas besoin de spécifier son chemin d'accès :

\quotefromfile calculator.cpp

Voir aussi exemples de fichiers.

chemin d'installation des exemples

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

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

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

sera utilisé pour faire référence au chemin d'un seul exemple dans ce projet de documentation. Ces chemins sont enregistrés dans le fichier manifeste de l'exemple, lu par Qt Creator.

Pour garantir des chemins corrects, examplesinstallpath doit correspondre à l'un des répertoires répertoriés dans exampledirs. Le chemin d'accès transmis en tant qu'argument pour chaque commande \example est relatif au chemin d'accès dans exampledirs.

Par exemple :

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

examplesinstallpath = mymodule

Et compte tenu de la commande suivante \example:

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

Le chemin mymodule/basic/hello est alors enregistré dans le fichier manifeste pour cet exemple.

Voir aussi: exampledirs, \exampleet \meta.

exemples.d'extensions de fichiers

La variable examples.fileextensions spécifie les extensions de fichiers que QDoc recherchera lors de la collecte des fichiers d'exemples à afficher dans la documentation.

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

Les extensions sont données sous forme d'expressions génériques standard. Vous pouvez ajouter une extension de fichier au filtre en utilisant '+='. Par exemple, vous pouvez ajouter une extension de fichier au filtre à l'aide de '+=' :

examples.fileextensions += *.qrc

Voir aussi headers.fileextensions.

exemples.warnaboutmissingimages

Lors du traitement de la documentation des exemples, QDoc peut émettre des avertissements si un exemple ne contient pas d'images. 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 aussi examples.warnaboutmissingprojectfiles.

exemples.warnaboutmissingprojectfiles

Lors du traitement de la documentation des 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 aussi examples.warnaboutmissingimages.

images exclues

La variable excludedirs permet de lister les répertoires qui ne doivent pas être traités par QDoc, même si ces mêmes répertoires sont inclus dans les variables sourcedirs ou headerdirs.

Par exemple :

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

Lorsqu'il est exécuté, QDoc exclut les répertoires répertoriés de toute considération ultérieure. Les fichiers de ces répertoires ne seront pas lus par QDoc.

Voir aussi excludefiles.

excludefiles

La variable excludefiles vous permet de spécifier des 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 tous les fichiers d'en-tête privés de Qt de l'analyse, définissez ce qui suit :

excludefiles += "*_p.h"

Voir aussi excludedirs.

extraimages

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

QDoc copie automatiquement un fichier image de imagedirs vers le répertoire de sortie s'il est référencé par la variable \image ou \inlineimage le référence. Si vous souhaitez copier d'autres images, 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 aussi images et imagedirs.

faussetés

La variable falsehoods définit la valeur de vérité des symboles du préprocesseur spécifiés comme étant fausse.

Les valeurs de la 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 de préprocesseur, QDoc considère que sa valeur de vérité est vraie. L'exception est '0', qui est toujours faux.

QDoc reconnaît et est capable d'évaluer la syntaxe de préprocesseur suivante :

#ifdef NOTYET
 ...
#endif

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

Cependant, face à une syntaxe inconnue comme

#if NOTYET
    ...
#endif

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

falsehoods = NOTYET

Voir aussi " defines".

generateindex

La variable generateindex contient une valeur booléenne qui indique s'il faut générer un fichier d'index lorsque la documentation HTML est générée.

Par défaut, un fichier d'index est toujours généré avec la documentation HTML, de sorte que cette variable n'est généralement utilisée que pour désactiver cette fonctionnalité (en fixant la valeur à false) ou pour activer la génération d'index pour la sortie WebXML (en fixant la valeur à 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 variable headers et ceux situés dans les répertoires spécifiés dans la variable headerdir (y compris tous les sous-répertoires), en construisant une structure interne des classes et de leurs fonctions.

Ensuite, il lira les sources spécifiées dans la variable sourceset celles situées dans les répertoires spécifiés dans la variable sourcedirs (y compris tous les sous-répertoires), en fusionnant la documentation avec la structure qu'il a récupérée dans les fichiers d'en-tête.

Si les variables headers et headerdirs sont toutes deux définies, QDoc les lira toutes les deux, d'abord headers puis headerdirs.

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

Voir aussi headers et headers.fileextensions.

en-têtes

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 spécifiés par la variable headerdirs spécifiée par la 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 variable headerdirs . Pour plus d'informations, voir la rubrique headerdirs variable.

Voir aussi headerdirs.

headers.fileextensions

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 variable headerdirs QDoc ne lira que les fichiers dont l'extension est spécifiée dans la variable headers.fileextensions. QDoc évite ainsi 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 données sous forme d'expressions génériques standard. Vous pouvez ajouter une extension de fichier au filtre en utilisant '+='. Par exemple, vous pouvez ajouter une extension de fichier au filtre à l'aide de '+=' :

header.fileextensions += *.H

Voir aussi headerdirs.

chemins d'inclusion

La variable includepaths est utilisée pour passer des chemins d'inclusion supplémentaires à l'analyseur Clang que QDoc utilise pour analyser le code C++ pour les commentaires de documentation.

La variable accepte une liste de chemins, préfixés par -I (chemin d'inclusion), -F (chemin d'inclusion du framework macOS), ou -isystem (chemin d'inclusion du système). Si un préfixe est omis, -I est utilisé par défaut.

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

Voir aussi moduleheader.

includeeprivate

Utilisez includeprivate pour inclure les membres privés d'une classe 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, remplacez includeprivate par 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 remplacent les paramètres globaux. 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 includeprivate dans Qt 6.11.

modèles de fichiers internes

La variable internalfilepatterns spécifie les modèles de chemin de fichier qui identifient les fichiers d'implémentation internes. Les classes déclarées dans des fichiers correspondant à ces motifs sont automatiquement marquées comme internes, ainsi que tous leurs membres (propriétés, fonctions, enums, types imbriqués). Les fonctions libres, les enums et les typedefs à l'échelle du fichier ne sont pas affectés par ce paramètre.

Lorsque showinternal vaut false (valeur par défaut), ces entités sont exclues de la validation de la documentation. Lorsque showinternal est true, elles sont incluses dans la documentation mais conservent leur statut Internal, ce qui permet aux générateurs de les styliser différemment (par exemple en ajoutant des indicateurs visuels pour les API internes).

Cela 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 XML, cela inclut les en-têtes privés se terminant par _p.h.

Syntaxe du motif

Les motifs prennent en charge deux syntaxes :

• Lesmotifs globaux de type Shell: Des caractères génériques simples où * correspond à n'importe quel caractère et ? correspond à un seul caractère. Les motifs globaux ne correspondent qu'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 les correspondances basées sur le chemin d'accès, utilisez la syntaxe des expressions rationnelles. Tout motif contenant des métacaractères regex (^$[]{}()|+\\.) est traité comme une expression régulière et comparé au chemin d'accès complet normalisé.

Les motifs sont comparés avec des barres obliques (/) comme séparateurs de répertoires. QDoc normalise les séparateurs de chemin en interne, c'est pourquoi il faut toujours utiliser / dans les motifs, quelle que soit la plate-forme.

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, quelle que soit la profondeur du répertoire.

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

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

Recherche les fichiers se terminant par _p.h, _impl.h, ou _pch.h.

Exemple - Correspondance basée sur un répertoire (regex) :

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

Correspond à n'importe quel fichier .h dans n'importe quel répertoire internal à n'importe quelle profondeur.

Exemple - Motifs multiples :

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

Combine les motifs globaux pour les cas simples et les expressions rationnelles pour les chemins d'accès complexes.

QDoc a introduit internalfilepatterns dans Qt 6.11.

Voir aussi : excludedirs et excludefiles.

mots ignorés

La variable ignorewords est utilisée pour spécifier une liste de chaînes de caractères que QDoc ignorera lors de la résolution des cibles des hyperliens.

QDoc dispose d'une fonction de liaison automatique, qui tente de lier les mots qui ressemblent à des entités C++ ou QML. Plus précisément, une chaîne peut faire l'objet d'un lien automatique si elle comporte au moins trois caractères, qu'elle ne contient pas d'espace blanc et qu'elle

• est un mot en camelCase, c'est-à-dire qu'il 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 lier ce mot automatiquement. Par exemple, si le mot OpenGL est une cible de lien valide (une section, \pageou \externalpage ), il est possible d'éviter la création d'un lien hypertexte pour chaque occurrence à l'aide de la commande

ignorewords += OpenGL

L'établissement d'un lien explicite avec \l continue de fonctionner pour les mots ignorés.

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

ignorepuis

La variable ignoresince est utilisée pour définir une valeur limite pour les versions transmises à la commande \since . Toutes les commandes \since qui définissent une version inférieure à la valeur limite sont ignorées et ne génèrent aucune sortie.

Les valeurs limites sont spécifiques au projet. Le nom du projet peut être défini comme une sous-variable. Le nom du projet par défaut est Qt. Par exemple :

ignoresince      = 5.0
ignoresince.QDoc = 5.0

Ces commandes ignoreront les commandes \since lorsque la version majeure est 4 ou inférieure et que le projet est QDoc ou 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 indique les répertoires contenant les images utilisées dans la documentation.

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

QDoc effectuera une recherche dans les répertoires dans l'ordre indiqué et acceptera le premier fichier correspondant qu'il trouvera. Il ne cherchera que dans les répertoires spécifiés, pas dans les sous-répertoires.

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

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

Lors du traitement des

\image calculator-example.png

QDoc vérifie s'il existe un fichier appelé calculatrice-exemple.png répertorié comme valeur dans la variable images. Si ce n'est pas le cas, il recherchera dans la variable imagedirs le fichier :

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

Si le fichier n'existe pas, QDoc recherchera un fichier appelé

$QTDIR/examples/calculator-example.png

imagesoutputdir

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

La valeur par défaut de imagesoutputdir est images.

Les fichiers images transmis en tant qu'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 pour les constructions de documentation multi-modules où 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 d'image portant le même nom ne s'écrasent les uns les autres.

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

langage

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 dans les blocs \code.. \endcode.

language = Cpp

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

language = QML

Voir aussi \code.

locationinfo

La variable booléenne locationinfo détermine si des informations détaillées sur la localisation de chaque entité sont écrites dans les fichiers .index et .webxml(lors de l'utilisation du format de sortie WebXML).

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

La valeur false désactive les informations de localisation :

locationinfo = false

La valeur par défaut est true.

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

avertissements

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

Lorsqu'elle vaut true, QDoc crée un fichier journal nommé <project>-qdoc-warnings.log dans le répertoire de sortie et écrit tous les messages d'avertissement dans ce fichier. Les avertissements sont également écrits sur stderr comme d'habitude.

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

La valeur true permet d'activer l'enregistrement des avertissements :

logwarnings = true

La valeur par défaut est false.

Cette fonction est utile pour les grands ensembles de documentation ou les environnements de CI où les avertissements peuvent être nombreux et défiler trop rapidement pour être analysés systématiquement.

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

logwarnings.disablecliargs

La sous-variable booléenne logwarnings.disablecliargs contrôle si les arguments de l'interface de programmation sont omis dans les en-têtes des fichiers d'avertissement.

logwarnings.disablecliargs = true

Lorsqu'elle vaut true, les arguments de la ligne de commande sont omis de l'en-tête du fichier journal, ce qui rend les fichiers journaux portables dans différents environnements. Ceci est utile pour les suites de tests et les systèmes de CI où les arguments de la ligne de commande contiennent des chemins 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 est utilisée pour 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 pas de caractères spéciaux comme le tiret ou le trait de soulignement. la définition est écrite en utilisant la syntaxe QDoc.

Une macro-variable peut être limitée à un seul type de génération de sortie. En ajoutant .HTML au nom de la macro, par exemple, la macro 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 rendre son argument en utilisant une police en gras. La deuxième macro définit la commande \raisedaster pour rendre un astérisque en exposant, mais uniquement lors de la génération 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 plus d'un paramètre, ou lorsqu'un argument contient des espaces, placez chaque argument entre accolades :

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

\verinfo {QFooBar} {1.0 beta}

Une option spéciale pour les macros, match, peut être ajoutée afin d'obtenir une correspondance supplémentaire entre les expressions régulières et les macros étendues.

Par exemple,

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

Ceci crée une macro \qtminorversion qui s'étend à la version mineure basée sur la variable d'environnement QT_VER.

Une macro qui définit un modèle de correspondance produit tous les groupes de capture (entre parenthèses) concaténés ensemble, ou la chaîne de caractères exacte si le modèle ne contient aucun groupe de capture.

Pour plus d'informations sur les macros prédéfinies, voir Macros.

manifestmeta

La variable manifestmeta spécifie un méta-contenu supplémentaire pour les exemples de fichiers manifestes générés par QDoc.

Voir la section Contenu méta du manifeste pour plus d'informations.

en-tête de module

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

Les projets qui documentent les API C++ nécessitent un en-tête au niveau du module qui inclut toutes les classes publiques, les espaces de noms et les fichiers d'en-tête du module. L'analyseur Clang de QDoc utilise ce fichier pour construire 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 d'en-tête du module.

project = QtCore

Avec le nom de projet ci-dessus, QDoc recherche un en-tête de module QtCore dans tous les chemins d'inclusion connus ; en utilisant d'abord les chemins passés comme arguments de ligne de commande, puis les chemins listés dans la variable includepaths.

QDoc émet un avertissement si l'en-tête du module n'est pas trouvé. Il tentera alors de construire un en-tête de module artificiel basé sur les en-têtes listés dans la variable headerdirs.

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

Si le projet ne contient pas de documentation C++, il convient d'indiquer à QDoc de ne pas générer de PCH en définissant moduleheader comme une chaîne vide :

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

Voir aussi includepaths et project.

langue naturelle

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 la documentation existante.

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 aussi sourceencoding, outputencoding, C.7. Les attributs lang et xml:lang et la meilleure pratique 13 : Utilisation des codes Hans et Hant.

navigation

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

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

Sous-variables

Voir aussi commande :

# 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 produit la barre de navigation suivante pour Item QML type :

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

Table des matières et liens de navigation

Si une ou plusieurs pages font office de table des matières (TOC), listez leurs titres dans navigation.toctitles pour automatiser la génération de liens de navigation( pageprécédente et suivante ) pour toutes les pages listées dans une TOC.

QDoc s'attend à ce que chaque page de la table des matières contienne un \list de liens sur chaque page de la table des matières. 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, on peut également trouver dans la liste de la table des matières \generatelist peut apparaître dans la liste de 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 à la première page \list, en supposant que les trois pages "Quoi de neuf" font partie du même groupe whatsnew.

Voir aussi \ingroup.

surcharge de la cible des signaux

Par défaut: connecting-overloaded-signals

La variable overloadedsignalstarget spécifie la cible du 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 avec un lien vers la documentation d'aide sur la connexion aux signaux surchargés. Par défaut, ce lien renvoie à une cible nommée connecting-overloaded-signals.

Les projets peuvent personnaliser ce lien pour qu'il renvoie à 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 commandes \target ) : connecting-overloaded-signals
• Une URL relative : signals-guide.html#overloaded-signals
• Une URL absolue : https://example.com/docs/signals.html#overloaded-signals

Voir aussi overloadedslotstarget.

overloadedslotstarget

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 créneaux surchargés.

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

Les projets peuvent personnaliser ce lien pour qu'il renvoie à 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 commandes \target ) : connecting-overloaded-slots
• Une URL relative : signals-guide.html#overloaded-slots
• Une URL absolue : https://example.com/docs/slots.html#overloaded-slots

Voir aussi overloadedsignalstarget.

répertoire de sortie

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

outputdir = $QTDIR/doc/html

localise la documentation de référence Qt générée dans $QTDIR/doc/html. Par exemple, la documentation de la classe QWidget est située 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 la documentation existante. 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 codera le HTML en utilisant ce codage et générera les déclarations correctes pour indiquer aux navigateurs quel codage est utilisé. La variable de configuration naturallanguage doit également être spécifiée pour fournir aux navigateurs un ensemble complet d'informations sur le codage des caractères et la langue.

Voir également outputencoding et naturallanguage.

formats de sortie

La variable outputformats spécifie le(s) format(s) de la documentation générée.

Depuis Qt 5.11, QDoc supporte les formats HTML et WebXML ; depuis Qt 5.15, il peut aussi générer la documentation en DocBook. Si aucune adresse outputformats n'est spécifiée, QDoc génère la documentation en HTML (le 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

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

préfixes de sortie

La variable outputprefixes spécifie une correspondance entre les types de fichiers et les préfixes à ajouter aux noms des 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 de l'API pour les types QML sont préfixés par qml-. Dans l'exemple ci-dessus, le préfixe uicomponents- est utilisé à la place.

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

préfixes de sortie

La variable outputsuffixes spécifie une correspondance entre les types de fichiers et les suffixes à appliquer au nom du module ou du type tels qu'ils apparaissent dans les noms de 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é en tant que suffixe au nom du module tel qu'il apparaît dans les noms de fichiers des pages de type QML et de module 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é comme suffixe au nom du type.

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

Avec les définitions ci-dessus, étant donné le 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.

qhp

Les sous-variables qhp sont utilisées pour définir les informations à écrire dans les fichiers du projet Qt Help (qhp).

Voir le chapitre Création de fichiers de projet d'aide pour plus d'informations sur ce processus.

Depuis QDoc 6.6, la définition de la variable base qhp à true signifie qu'une configuration de projet d'aide valide est attendue :

qhp = true

Si la configuration d'un projet ne définit pas qhp.projects, QDoc émet un avertissement. Ceci est utile pour s'assurer que tous les projets de documentation avec un fichier .qdocconf de haut niveau partagé (comme dans Qt) sont configurés correctement.

Pour désactiver l'avertissement, définissez la variable à false.

sourcedirs

La variable sourcedirs indique 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 variable header et ceux situés dans les répertoires spécifiés dans la variable headerdir (y compris tous les sous-répertoires), en construisant une structure interne des classes et de leurs fonctions.

Ensuite, il lira les sources spécifiées dans la variable sourceset celles situées dans les répertoires spécifiés dans la variable sourcedirs (y compris tous les sous-répertoires), en fusionnant la documentation avec la structure qu'il a récupérée dans les fichiers d'en-tête.

Si les variables sources et sourcedirs sont toutes deux définies, QDoc les lira toutes les deux, d'abord sources puis sourcedirs.

Dans les répertoires spécifiés, QDoc ne lira que les fichiers dont l'adresse fileextensions est spécifiée dans la variable sources.fileextensions dans la variable. Les fichiers spécifiés par sources seront lus indépendamment de leur extension.

Voir aussi 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, le code source est ISO-8859-1 (Latin1) pour des raisons de compatibilité avec la documentation existante. Pour certaines langues, en particulier les langues non européennes, ce n'est pas suffisant et un encodage tel que UTF-8 est nécessaire.

Bien que QDoc utilise le codage 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 de tels cas, il est possible d'écrire la documentation de l'API entièrement dans des fichiers de documentation.

Voir aussi naturallanguage et outputencoding.

sources

La variable sources vous permet de spécifier des fichiers sources individuels en plus de ceux situés dans les répertoires spécifié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, voir la variable sourcedirs.

Voir aussi sourcedirs.

sources.fileextensions

La variable sources.fileextensions filtre les fichiers d'un répertoire source.

Lors du traitement des fichiers source spécifiés dans la variable sourcedirs QDoc ne lira que les fichiers ayant les extensions spécifiées dans la variable sources.fileextensions. De cette manière, QDoc évite 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 données sous forme d'expressions génériques standard. Vous pouvez ajouter une extension de fichier au filtre en utilisant '+='. Par exemple, vous pouvez ajouter une extension de fichier au filtre à l'aide de '+=' :

sources.fileextensions += *.CC

Voir aussi les sources et les sources d'information.

fallacieux

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

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

permet de s'assurer que les avertissements correspondant à l'une ou l'autre de ces expressions ne feront pas partie de 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

mise en évidence de la syntaxe

La variable syntaxhighlighting indique si QDoc doit mettre en évidence la syntaxe du code source cité dans la documentation qu'il génère.

syntaxhighlighting = true

active la coloration syntaxique pour tous les langages de programmation pris en charge.

tabsize

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

tabsize = 4

La variable tabsize donne au caractère de tabulation la taille de 4 espaces. La valeur par défaut de la variable est 8, et n'a pas besoin d'être spécifiée.

fichier d'étiquettes

La variable tagfile spécifie le fichier de balises Doxygen à écrire lorsque le HTML est généré.

version

La variable version indique 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 variable version ou versionsym dans un fichier .qdocconf ), il est accessible par la commande \version correspondante pour être utilisé dans la documentation.

Voir aussi versionsym.

versionsym

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

versionsym = QT_VERSION_STR

QT_VERSION_STR est défini dans qglobal.h comme suit

#define QT_VERSION_STR   "5.14.1"

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

Voir aussi \version.

limite d'avertissement

La variable warninglimit définit le nombre maximum d'avertissements de documentation autorisés. Si cette limite est dépassée, QDoc continue normalement mais se termine avec 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éfini, le processus QDoc se termine par 0, en supposant qu'il n'y a pas eu d'autres erreurs critiques.

La définition de warninglimit à 0 signifie l'échec en cas d'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.