Dépannage des avertissements de QDoc

QDoc peut émettre des avertissements lors de la génération de votre ensemble de documentation. Cette section décrit la signification de ces avertissements et la manière de les résoudre. Ce document ne traite pas des avertissements générés par Clang.

Toutes les propriétés d'un groupe doivent appartenir au même type : <name>

Lors de la documentation des groupes de propriétés QML, toutes les propriétés répertoriées dans le bloc de commentaires doivent appartenir au même type QML.

Fichier <file> déjà généré pour ce projet

Lors de la génération de la documentation d’un projet, QDoc garde une trace des noms des fichiers qu’il a générés. QDoc émettra un avertissement lorsqu’il ouvrira un fichier en écriture si ce fichier est connu pour avoir déjà été généré au cours de l’exécution en cours. Cela peut se produire si une \page commande utilise le même nom que \group par exemple.

Vous pouvez définir la variable d’environnement QDOC_ALL_OVERWRITES_ARE_WARNINGS pour recevoir un avertissement inconditionnel à chaque fois qu’un tel événement se produit. Cela peut s’avérer utile pour localiser les définitions en cause.

\brief L'instruction ne se termine pas par un point

L'argument de la commande \brief est une phrase résumant le sujet documenté ; il doit donc se terminer par un point. Il doit également être concis.

Impossible de créer un lien vers <cible>

QDoc affiche cet avertissement lorsqu’une partie de la documentation (identifiée dans le message d’avertissement) tente de faire référence à une autre, mais ne spécifie pas correctement cette dernière, c’est-à-dire la cible du lien. Cela peut être dû à une faute de frappe dans la référence ou au fait que la cible a changé de nom (pour une fonction ou un type) ou de titre (pour une autre section).

Plusieurs causes sont possibles :

• La cible du lien n’a pas été définie à l’aide d’une commande de rubrique QDoc, par exemple {title-command}{\title} <target>.
• La <cible> contient une faute de frappe.
• Le document contenant cette cible de lien n’a pas été compilé.
• Le document contenant cette cible de lien se trouve dans un module qui n’est pas inclus dans le chemin de compilation.
• La cible du lien se trouve dans un autre module, et aucune dépendance vers ce module n’a été définie dans la configuration, ou bien QDoc n’a pas réussi à localiser le fichier d’index correspondant à cette dépendance.

Recherchez cette cible de lien spécifique dans le code source. Si vous n’obtenez aucun résultat, affinez progressivement votre recherche jusqu’à ce que vous trouviez une correspondance.

Si la cible du lien ressemble au nom d’un type ou d’une fonction, cela peut également être dû à :

• Le nom (ou, pour les fonctions, la signature lorsqu’elle est spécifiée) utilisé à l’endroit où il est documenté ne correspond pas au nom utilisé dans sa déclaration.
• La cible du lien a été marquée comme \internal alors que le texte de lien ne l’était pas.

Impossible de trouver la fonction de base pour <méthode> dans <classe>

QDoc génère cet avertissement si \reimp est utilisé pour documenter une méthode, en tant que redéfinition d’une méthode virtuelle, alors qu’aucune classe de base ne possède de méthode virtuelle portant le nom et la signature indiqués. Cela peut se produire parce que la méthode que l’on souhaitait redéfinir a changé de signature ou n’est plus virtuelle.

Impossible de trouver <nom> spécifié avec \<commande> dans aucun fichier d'en-tête

Cela signifie que QDoc ne trouve aucune déclaration de <name> dans aucun fichier d'en-tête, mais a trouvé un commentaire qui prétend la documenter.

Exemple :

Cannot find 'Color::Red' specified with '\enum' in any header file.

Un commentaire de documentation prétend décrire une énumération, mais QDoc n’a pas trouvé de définition de cette énumération dans un fichier d’en-tête.

Cela peut également être dû à :

• une faute de frappe dans <nom> ou <commande>
• un préfixe d'espace de noms ou de classe manquant
• le déplacement de <nom> vers un autre espace de noms ou une autre classe

Impossible de trouver le fichier de projet pour l'exemple <name>

Dans le répertoire source de l'exemple, QDoc s'attend à trouver un fichier de projet nommé CMakeLists.txt, ou un fichier avec une extension .pro, .qmlproject ou .pyproject, dont le nom de base correspond à celui du répertoire de l'exemple. Par exemple, examples/mymodule/helloworld/helloworld.pro.

Impossible de trouver le fichier de snippets à citer

QDoc affiche cet avertissement s’il ne parvient pas à trouver le fichier portant le nom d’un \snippet ou \quotefromfile .

Voici quelques étapes utiles pour corriger ce problème :

• Vérifiez que le nom du fichier d’extraits est correct. QDoc ajoute le nom du fichier d’extraits à chacun des répertoires indiqués dans le chemin de recherche, afin d’obtenir un chemin d’accès vers un fichier candidat à rechercher. Il génère cette erreur lorsqu’aucun de ces candidats n’existe.
• Vérifiez le chemin de recherche des extraits, défini par la variable de configuration « exampledirs » dans le fichier « *.qdocconf ». Vous devrez peut-être ajouter une entrée à ce chemin ou corriger une entrée existante.
• Vérifiez si le fichier d’extrait existe, ou s’il a été déplacé, renommé ou supprimé, ce qui peut se produire en cas de modifications du code source à partir duquel QDoc tente d’extraire des extraits.

Impossible de trouver le fichier d'inclusion qdoc <nom_fichier>

QDoc n'a pas réussi à trouver un fichier d'inclusion nommé dans une commande. QDoc recherche chaque répertoire indiqué dans le chemin de recherche. S'il n'y a aucun fichier portant ce nom dans l'un de ces répertoires, ou si le fichier trouvé lors de cette recherche n'est pas lisible, QDoc affiche cet avertissement. Vérifiez que la combinaison du chemin de recherche et de <nom_fichier> est correctement orthographiée, et que vous disposez des droits de lecture sur le fichier.

Impossible de trouver <tag> dans <file>

Cela signifie que QDoc ne parvient pas à trouver l’identifiant <id> dans le \include <fichier> ou {snippet-command}{\snippet} <fichier>.

Impossible de localiser le fichier d'index pour la dépendance <depend>

Exemple :

"QMake" Cannot locate index file for dependency "activeqt"

Le projet de documentation QMake n'a pas pu localiser le fichier activeqt.index dans aucun des répertoires d'index spécifiés. Dans ce cas, les répertoires d'index spécifiés sont définis dans qmake.qdocconf.

Impossible d’imbriquer des commandes <command>

Cet avertissement concerne les commandes de mise en forme : bold, italic, index, link, span, subscript, superscript, teletype, uicontrol, underline. Une commande de mise en forme ne peut pas être utilisée au sein du texte auquel elle s'applique. Exemple :

There is \b{no \b{super-}bold}.
\encode

\section1 Can't use <inner> in <outer>

This warning is issued for commands that cannot be nested.

Example:
\badcode
    \list
        \li \table
            \row \li Hello \li Hi
            \endtable
    \endlist

Cela génère l'avertissement QDoc « Impossible d'utiliser '\table' dans '\list' ».

Impossible d’ouvrir le fichier à citer : <filename>

Le chemin de recherche pour <filename> est défini par les variables suivantes dans le fichier .qdocconf: sources, sourcedirs et exampledirs.

QDoc n'a pas réussi à trouver un fichier mentionné dans une commande (telle que \quotefromfile, \snippet, \include) lui demandant de récupérer le contenu du fichier en question. Il effectue une recherche dans chaque répertoire indiqué dans le chemin de recherche. Si aucun fichier portant ce nom n’existe dans l’un de ces répertoires, ou si le fichier est trouvé mais n’est pas accessible en lecture, QDoc affiche cet avertissement. Vérifiez que la combinaison du chemin de recherche et de <filename> est correctement orthographiée, et que vous disposez des droits de lecture sur le fichier.

Impossible de lier cette documentation à quoi que ce soit

QDoc a trouvé un commentaire /*! ... */ ne contenant aucune commande de rubrique et n’a pas pu associer la déclaration ou la définition suivant immédiatement ce commentaire à une entité documentée. Cela peut se produire s’il n’y a pas de déclaration ou de définition après le commentaire, ou si l’entité n’est pas visible par QDoc, par exemple lorsque la déclaration se trouve derrière une condition de préprocesseur que QDoc n’évalue pas.

<class> tente d’hériter d’elle-même

La \inherits commande sert à indiquer qu’un type QML hérite d’un autre type QML. Cet avertissement s’affiche si cet autre type QML est identique au type QML documenté.

Exemple :

\qmltype Foo
\inherits Foo

Échec de la commande <command> à la fin du fichier <filename>

Exemple :

Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".

Dans ce cas, l'avertissement signifie que la \snippet commande n’a pas trouvé de deuxième balise « //! [2] » pour marquer la fin de l’extrait. Cela peut également signifier qu’elle n’a trouvé aucune occurrence de cette balise d’extrait dans ce fichier d’extrait.

Autre exemple :

Command '\skipto' failed at end of file 'styling/CMakeLists.txt".

La \skipto + <pattern> déplace le curseur sur la ligne suivante contenant ce motif. Si \skipto ne le trouve pas, QDoc affiche cet avertissement.

Commande <command> non autorisée avec les commandes de propriétés QML

Exemple :

\qmlproperty real QtQuick.Controls::RangeSlider::first.value
\qmlproperty real QtQuick.Controls::RangeSlider::first.position
\qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
\qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
\qmlsignal void QtQuick.Controls::RangeSlider::second.moved()

Message d'erreur :

Command '\\qmlsignal' not allowed with QML property commands

Cet avertissement est spécifique à la documentation des groupes de propriétés. QDoc autorise plusieurs commandes de rubrique `qmlproperty` ou `qmlattachedproperty` dans un même commentaire de documentation pour documenter un groupe de propriétés dont le dernier élément du chemin est `<group>.<property>`. Toute autre commande de rubrique déclenche cet avertissement.

Impossible de résoudre l’instruction d’importation QML pour le type <name>

QDoc émet cet avertissement si vous documentez un type QML, mais que vous omettez la \inqmlmodule commande. Exemple :

Could not resolve QML import statement for type 'ItemSelectionModel'
\encode

Incorrect:
  \badcode
  \qmltype ItemSelectionModel
  \nativetype QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

Correct :

\qmltype ItemSelectionModel
\nativetype QItemSelectionModel
\inqmlmodule QtQml.Models
\since 5.5
\ingroup qtquick-models

Héritage cyclique de types : <type>

Un héritage cyclique ou circulaire se produit lorsqu'un type QML hérite d'un type de base qui hérite lui-même du type d'origine. Cela peut se produire entre deux types qui s'héritent mutuellement, ou il peut y avoir des types intermédiaires entre eux.

Cet avertissement indique l’endroit où un cycle a été détecté dans la hiérarchie d’héritage. Vous devez examiner la \inherits commande du type et remonter la chaîne des types de base jusqu’à ce que vous trouviez un type héritant d’un type que vous avez déjà rencontré. Vous devez ensuite briser le cycle en corrigeant la \inherits commande de l’un des types identifiés.

Des modules dépendants ont été spécifiés, mais aucun répertoire d'index n’a été défini.

QDoc s'attend à trouver un ou plusieurs arguments –indexdir sur la ligne de commande. Sans eux, QDoc ne peut pas localiser les fichiers d'index des dépendances définies avec la variable de configuration « depends ».

La configuration de la documentation pour <project> ne définit pas de projet d’aide (qhp)

Une configuration de Qt Help valide était attendue, mais n’a pas été fournie dans le fichier .qdocconf du projet.

Voir également Création de fichiers de projet d’aide et qhp.

Nom de cible en double <target>

Cet avertissement s'affiche si vous définissez deux cibles avec le même paramètre, que ce soit à l'aide de l' \target ou la \keyword . Le nom de cible fourni en paramètre à ces commandes doit être unique. L’avertissement est suivi de « L’occurrence précédente se trouve ici : [emplacement] », où emplacement contient un nom de fichier et un numéro de ligne.

Extrait qdoc vide <tag> dans <fichier>

L'extrait <tag> a été trouvé dans le \snippet <fichier>, mais il est vide.

Échec de la recherche de la fonction lors de l’analyse de la signature <signature> d’ \fn

Lorsque Clang analyse une signature de fonction à la suite d’une \fn commande, il la compare à la déclaration figurant dans le fichier d’en-tête. Si Clang détecte des divergences, il affiche ce message d’avertissement.

La signature doit être entièrement qualifiée. Les problèmes courants incluent des arguments de modèle manquants ou incorrects, un type de retour erroné ou des qualificatifs tels que `const`.

Impossible de trouver qhp.<projet>.sous-projets.<sous-projet>.indexTitle

QDoc n’a pas réussi à trouver de titre pour une page désignée comme page d’index pour <SOUS-projet> dans la configuration du projet Qt Help.

Les titres d’index des sous-projets doivent être propres au projet de documentation actuel. L’utilisation d’un titre de page provenant d’un autre projet, chargé en tant que dépendance, entraîne également cet avertissement.

Pour plus d’informations, consultez la section Création de fichiers de projet d’aide.

Échec de l'ouverture de <fichier> en écriture

Cet avertissement signifie clairement qu’il est impossible d’ouvrir un fichier en écriture, probablement en raison d’un chemin d’accès erroné ou d’un problème d’autorisation d’écriture dans un répertoire donné.

Commande « \target » détectée en dehors d’un élément de tableau dans un tableau

Si QDoc rencontre une commande « \target » qui n’est pas précédée d’une commande « \li » au sein d’un bloc «\table... \endtable », il affiche cet avertissement. L’avertissement est suivi du texte « Déplacez la commande « \target » à l’intérieur de la commande « \li » pour résoudre cet avertissement.

\generatelist <group> est vide

Voici un bref aperçu de tous les arguments possibles pour \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist classes <préfixe>
• \generatelist classes par module <nom du module>
• \generatelist types QML par module <nom du module>
• \generatelist index des fonctions
• \generatelist mentions légales
• \generatelist présentations
• \generatelist crédits
• \generatelist connexes

QDoc affiche cet avertissement si vous spécifiez « \generatelist <group> » et que le groupe ne contient aucun élément, ou si vous spécifiez « \generatelist <group> <pattern> » et qu'aucun élément du groupe ne correspond au modèle.

\generatelist <group> groupe introuvable

Cet avertissement s'affiche si l'argument de \generatelist est un groupe inexistant.

Exemple :

\generatelist draganddrop

Cette instruction génère une liste des classes ou des types QML du groupe « draganddrop ». Les classes ou les types QML sont ajoutés au groupe « draganddrop » par la commande « \l {ingroup-command}{\ingroup} draganddrop » dans leur \class ou \qmltype commentaire.

QDoc affiche ce message d'avertissement si aucune entité ne comporte cette instruction « \ingroup draganddrop ».

Absence de commande « \inmodule »

QDoc émet cet avertissement si les commentaires QDoc ne relient pas une classe, un espace de noms ou un fichier d'en-tête à un module à l'aide de la \inmodule commande.

Si le commentaire QDoc décrit une entité qui n'est pas membre d'une autre entité (généralement un espace de noms ou une classe), il doit utiliser soit \relates ou \inmodule pour l’associer à son contexte plus large. Cet avertissement est généré si ce n’est pas le cas.

\reimp illégale ; aucune fonction virtuelle documentée pour <commande>

QDoc tente de créer un lien vers la fonction que celle-ci réimplémente, mais n’a pas pu trouver la cible du lien, probablement parce que cette fonction n’est pas documentée. Cela peut également se produire si aucune classe de base ne possède de méthode virtuelle portant ce nom et cette signature ; ce qui peut être dû à un changement de nom, à une modification de la signature ou au fait que la classe de base ne la déclare plus comme virtuelle.

Type de propriété QML non valide

Le type utilisé pour déclarer une propriété QML n’était pas un type de valeur QML ou un type d’objet QML valide, ou bien il s’agissait d’un type C++ ou Qt.

Cet avertissement se produit généralement lorsque les développeurs font référence au type Qt sous-jacent utilisé pour implémenter un type QML, par exemple QStringList au lieu de list<string>.

Expression régulière <regex> non valide

Certaines commandes QDoc acceptent des expressions régulières en tant que paramètres. QDoc affiche cet avertissement lorsque le texte fourni comme paramètre n'est pas une expression régulière valide, généralement parce qu'il contient des caractères ayant une signification particulière dans les expressions régulières et qui auraient dû être échappés.

Exemple :

notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'

\quotefromfile webenginewidgets/notifications/data/index.html
\skipuntil resetPermission

Expression régulière non valide :

\printuntil /^})$/

Expression régulière valide :

\printuntil /^\}\)$/

La \printuntil commande affiche le contenu jusqu’à ce qu’elle rencontre une ligne composée uniquement d’une accolade droite suivie d’une parenthèse droite. Dans ce cas, l’accolade et la parenthèse doivent être échappées car elles ont une signification particulière dans les expressions régulières.

Une macro ne peut pas comporter à la fois des définitions spécifiques au format et des définitions de syntaxe qdoc

Une \macro qui spécifie un format de sortie ne peut pas également avoir de définition générique.

Exemple de configuration déclenchant cet avertissement :

macro.gui = \b
macro.gui.HTML = "<b>\1</b>"

La macro <commande> ne possède pas de définition par défaut

QDoc tente de développer une macro et s'attend à ce que celle-ci dispose d'une définition par défaut. Certaines macros peuvent ne disposer que de définitions spécifiques à un format.

Exemple :

macro.pi.HTML = "π"    # encodes the pi symbol for HTML output format

Il existe toutefois des cas où l’expansion d’une macro nécessite une macro indépendante du format. Par exemple, vous pouvez avoir des macros dans les titres de section, mais celles-ci doivent disposer de définitions par défaut.

La macro <macro> a été appelée avec trop peu d'arguments (<many> attendus, <few> fournis)

La macro indiquée nécessite plus de paramètres que ceux qui lui ont été fournis. Consultez la définition de la macro dans la configuration pour plus de détails.

Virgule manquante dans \sa

Les titres répertoriés pour une \sa commande doivent être séparés les uns des autres par des virgules.

Nom de format manquant après \raw

La \raw commande et la \endraw délimitent un bloc de code brut en langage de balisage. La commande \raw doit être suivie du nom du format.

Image manquante : <fichier_image>

Le chemin d’accès à l’image est incorrect ou le fichier image n’existe pas.

<outer> manquant avant <inner>

Quelques exemples :

• La \li commande ne peut être utilisée qu’à l’intérieur d’un \list ou d'un \row d’un \table.
• La \row et \header ne peuvent être utilisées qu’au sein d’un \table.

Type de propriété manquant pour <nom>

La déclaration d’un \qmlproperty ne comporte pas de type de propriété.

La commande ` \qmlproperty ` doit être suivie du type de propriété, puis du nom complet de la propriété (c'est-à-dire le nom précédé de deux points « ::- » après le nom de la classe à laquelle elle appartient).

Incorrect :

\qmlproperty MyWidget::count

Correct :

\qmlproperty int MyWidget::count

Plusieurs fichiers d'index trouvés pour la dépendance <indexfile>:<depend>

Utilisation de <fichier_index> comme fichier d’index pour la dépendance <depend>

Plusieurs chemins d'accès à la documentation ( -indexdir ) ont été transmis à QDoc en tant qu'options de ligne de commande, et plusieurs d'entre eux contenaient un fichier « .index » correspondant à une dépendance. QDoc sélectionne automatiquement celui dont l'horodatage est le plus récent.

En général, cet avertissement indique la présence d'artefacts de compilation issus d'une précédente génération de documentation.

Plusieurs définitions de surcharge principale pour <function>

QDoc émet cet avertissement lorsque plusieurs fonctions portant le même nom sont marquées avec \overload primary. Une seule fonction d’un groupe de surcharges doit être désignée comme surcharge principale.

L’avertissement inclut les signatures des fonctions et leurs emplacements dans le code source afin de faciliter l’identification de toutes les surcharges principales en concurrence. QDoc déterminera la surcharge principale effective à l’aide d’une comparaison lexicographique (tri alphabétique des signatures de fonctions) parmi les fonctions marquées comme principales.

Pour résoudre cet avertissement, supprimez l’argument primary de toutes les commandes \overload primary du groupe de surcharges, sauf une.

Exemple déclenchant cet avertissement :

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload primary
    Does something with a parameter.
*/
void doSomething(int value);

Approche correcte – une seule surcharge principale :

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload doSomething()
    Does something with a parameter.
*/
void doSomething(int value);

<nom> documenté plusieurs fois

QDoc génère cet avertissement lorsqu’il détecte deux commentaires documentant le même élément. L’emplacement du commentaire détecté précédemment est indiqué dans les détails de l’avertissement.

Par exemple, cet avertissement s'affiche lorsqu'une fonction comporte un commentaire de documentation précédant sa définition, ainsi qu'un commentaire « \fn » distinct situé ailleurs.

<name> est documenté, mais l'espace de noms <namespace> n'est documenté dans aucun module

La documentation relative à <nom> a été trouvée, mais <nom> est déclaré sous un espace de noms qui n'est pas documenté ou pour lequel QDoc n'a pas pu localiser la documentation.

Ce problème peut être résolu soit en documentant <namespace>, soit, s’il est déjà documenté dans un autre module, en s’assurant que ce module dépend de celui-ci.

Voir également « depends » et « indexes ».

L'espace de noms <name> est documenté plusieurs fois

Cet avertissement signifie qu’un ensemble de documentation contient deux commentaires comportant \namespace des commandes avec le même argument, <nom>.

\nativetype n'est autorisé que dans \qmltype

La \nativetype commande ne peut être utilisée que dans un commentaire QDoc documentant un type QML.

Aucune documentation pour <name>

Exemple :

Warning "No documentation for QNativeInterface."

QDoc détecte la déclaration de l'espace de noms QNativeInterface dans un fichier d'en-tête, mais ne trouve pas de commentaire QDoc dans lequel cet espace de noms a été documenté.

Aucune documentation générée pour la fonction <name> dans l'espace de noms global

QDoc a pu associer la documentation de la fonction <name> à sa déclaration, mais aucune sortie n’a été générée car la fonction est déclarée dans l’espace de noms global.

Utilisez la \relates commande pour associer la fonction à un type, un espace de noms ou un fichier d'en-tête documenté. La fonction apparaît alors comme élément non membre associé sur la page de référence correspondante.

Aucune sortie générée pour <entité> car <parent> n’est pas documenté

QDoc affiche cet avertissement lorsqu’il analyse un commentaire de documentation concernant une entité API, telle qu’un membre de classe, mais ne peut produire aucune sortie car le parent associé (la classe) n’est pas documenté. Assurez-vous que le parent est documenté et que QDoc est configuré pour analyser le fichier source contenant le commentaire de documentation.

Si le membre documenté appartient à une classe qui n’est pas censée être documentée, marquez la classe comme \internal ou utilisez la \dontdocument commande.

Élément d'énumération <nom> introuvable dans <classe>

Exemple :

Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
with \enum in any header file.

QDoc affiche cet avertissement lorsqu’il détecte une \value directive dans un \enum commentaire qui désigne une valeur introuvable dans le fichier d'en-tête ayant déclaré le type énuméré documenté.

Paramètre introuvable

QDoc émet cet avertissement lorsque le nom de paramètre indiqué après une \a commande ne correspond à aucun des paramètres mentionnés dans la déclaration, dans le fichier d'en-tête, de la fonction ou de la méthode en cours de documentation.

Type <type> introuvable dans le <module> QML

QDoc émet cet avertissement si un \qmlproperty, \qmlmethodou \qmlsignal utilise un identifiant de module QML, mais que le \qmltype n'appartient pas à ce module.

L’identifiant de module QML, s’il est défini, doit correspondre à l’ \inqmlmodule argument figurant dans la documentation du type QML. Dans la plupart des cas, QDoc est capable de localiser le type QML sans identifiant de module.

Remplace une documentation précédente

QDoc émet cet avertissement lorsqu’il détecte deux commentaires qui semblent décrire la même entité. L’emplacement du commentaire détecté précédemment est indiqué dans les détails de l’avertissement.

Propriété QML documentée plusieurs fois : <identifiant>

QDoc utilise cet avertissement lorsqu’il détecte deux commentaires QDoc documentant la même propriété QML, soit parce qu’ils apparaissent juste avant sa définition, soit parce qu’ils utilisent la \qmlproperty commande.

Type QML <TypeName> documenté avec <ClassName> comme type natif. Remplacement de <ClassName> par <OtherClass>

Si la \nativetype commande est utilisée avec le même argument dans plusieurs commentaires de documentation de type QML appartenant au même projet de documentation, QDoc émet cet avertissement. Pour résoudre ce problème, assurez-vous de n’utiliser la commande ` \nativetype ` qu’une seule fois pour chaque classe C++.

QtDeclarative n’est pas installé ; impossible d’analyser le QML

QDoc affiche cet avertissement s’il a été compilé sans prise en charge de l’analyse syntaxique du QML. Cela ne devrait pas se produire, sauf si vous disposez d’une version personnalisée de QDoc.

Lien redondant vers lui-même dans la commande « \sa » pour <name>

Un élément de documentation contient un lien vers lui-même dans les références définies dans sa \sa commande.

Ce problème a tendance à se produire lorsqu’il existe un ensemble de propriétés ou de méthodes liées qui se réfèrent les unes aux autres, et que les commandes « \sa » ont été copiées d’une à l’autre, comme dans cet exemple :

\fn void Items::append(const Item &)
...
\sa append(), count(), insert(), remove()

Il est utile de remplacer le lien autoréférent par un lien vers une autre propriété ou méthode associée.

Il se peut également que le lien ne soit pas suffisamment précis pour que QDoc puisse le résoudre, comme dans cet exemple :

\fn void MyPicture::setSize(int)
...
\sa setSize()

Dans ce cas, l’intention était peut-être de faire référence à une surcharge acceptant un argument « double » :

\fn void MyPicture::setSize(int)
...
\sa setSize(double)

Le contenu est trop long

QDoc utilise un tampon de taille fixe lors de l’analyse syntaxique des fichiers source. Si un seul token du fichier contient plus de caractères que la limite maximale, QDoc affiche cet avertissement.

Bien que QDoc poursuive l’analyse du fichier, seule la partie du token qui tient dans le tampon est prise en compte, ce qui signifie que la sortie risque d’être altérée.

Pour résoudre cet avertissement, il faut réduire la taille du contenu concerné, soit en le fractionnant, si possible, soit en supprimant certaines de ses parties.

Le nombre maximal de caractères autorisé pour un token est indiqué à côté de l'avertissement, par exemple :

file.qdoc:71154: (qdoc) warning: The content is too long.

[The maximum amount of characters for this content is 524288.
Consider splitting it or reducing its size.]

Ce titre de page existe dans plusieurs fichiers

La \title commande définit le titre d'une page.

\page activeqt-server.html
\title Building ActiveX servers in Qt

QDoc émet cet avertissement si un titre donné est utilisé dans plusieurs pages.

Ce commentaire QDoc ne contient aucune commande de rubrique (par exemple, \module, \page)

Si un commentaire QDoc ne contient pas de commande de rubrique, QDoc ne sait pas ce que le commentaire documente et affiche cet avertissement. Très similaire à « Impossible de relier cette documentation à quoi que ce soit », mais spécifique aux commentaires qui ne se trouvent pas dans des fichiers C++ ou QML.

<topic> ne peut pas être combiné avec d’autres commandes de sujet

QDoc autorise l’utilisation de plusieurs commandes de sujet dans un même commentaire de documentation pour certains cas d’utilisation. L’utilisation de plusieurs commandes de sujet issues de catégories différentes déclenche cet avertissement, et le sujet ne génère aucun résultat.

Le type est son propre type de base : <type>

Le type QML a été défini de manière incorrecte comme son propre type de base, probablement à l’aide de la \inherits commande.

Impossible d'analyser l'extrait de code QML : <code> à la ligne <y>, colonne <x>

Les commentaires QDoc peuvent contenir du code QML. Ce code peut se trouver dans un extrait de code ou dans les commentaires QDoc délimités par \qml et {endqml-command}{\endqml}.

Exemple :

S'il y a une erreur de syntaxe dans le code QML, QDoc émet l'avertissement

Unable to parse QML snippet: Syntax error at line 97, column 42

Les extraits de code peuvent également contenir du QML et, dans ce cas, le code est également vérifié. S'il manque par exemple une accolade dans le code, QDoc affiche l'avertissement

Unable to parse QML snippet: Expected token '{' at line 63, column 52

QDoc échoue souvent à analyser les extraits de code QML incomplets ; dans ces cas-là, il est souvent possible de remplacer les commandes \qml... \endqml par \code... \endcode pour supprimer cet avertissement.

Parenthèses mal appariées dans <text>

Indique la présence d’un « ( » sans « ) » correspondant, ou inversement.

Élément d'énumération non documenté <enum> dans <enum list>

<liste d’énumération> \value ou \omitvalue ne comportaient pas d’entrée pour <enum>, qui est nommé dans la déclaration de <liste d’énumération> dans le fichier d’en-tête.

Paramètre non documenté

QDoc exige que la documentation d’une fonction ou d’une méthode décrive chaque paramètre. Il vérifie cela en s’assurant que chaque nom de paramètre (tel que spécifié lors de la déclaration de la fonction ou de la méthode dans un fichier d’en-tête) apparaisse après une \a commande.

Cette exigence ne s’applique pas à la documentation des surcharges de fonctions, à condition que la surcharge soit marquée par la \overload et qu’il existe une fonction entièrement documentée portant le même nom.

Propriété non documentée « <nom> »

Cet avertissement indique qu’une classe C++ comporte une déclaration de propriété Q_PROPERTY qui ne dispose pas de documentation. Les propriétés font partie de l’API publique d’une classe et doivent être documentées à l’aide de la commande \property afin de décrire leur objectif, leurs valeurs valides et leur comportement.

<module> QML non documenté référencé par <type> ou ses membres

QDoc émet cet avertissement s’il ne parvient pas à localiser un module QML à partir de l’identifiant transmis à la \inqmlmodule ou \qmlproperty commandes associées à un type QML.

Cela signifie soit que la documentation du \qmlmodule est manquante, soit qu’un identifiant de module incorrect a été utilisé dans les commandes \qmlproperty, \qmlmethod ou \qmlsignal.

Valeur de retour non documentée

Pour les fonctions dont le type de retour n’est pas `void`, QDoc vérifie si la valeur de retour est documentée. Cet avertissement est émis si la documentation d’une fonction ou d’une méthode ne contient pas de mot commençant par « return ».

<end_command> inattendu

Cet avertissement est émis si, par exemple, vous avez une \endlist sans qu'elle soit précédée d'un \list. Il s'applique à toutes les commandes qui vont par paires (par exemple, startFoo/endFoo).

Inattendu \snippet

QDoc émet cet avertissement s’il ne parvient pas à localiser le fichier d’extrait cité dans une \snippet commande.

Base <nom> inconnue pour le type QML <type>

Le nom du type déclaré comme type de base pour un type QML est introuvable, ou n’a pas été déclaré avec la \inherits commande.

Commande inconnue <nom>

Lorsqu’un commentaire QDoc utilise une barre oblique inversée suivie d’un token qui n’est pas une commande intégrée à QDoc et qui n’a pas été défini comme macro de commande personnalisée, QDoc génère cet avertissement. Vérifiez l’orthographe du nom de la commande et assurez-vous que votre configuration QDoc n’inclut pas ce qui aurait pu la définir, s’il s’agit d’une commande personnalisée.

Cet avertissement peut également apparaître si du code est mis entre guillemets dans le commentaire QDoc ; par exemple, l'auteur a peut-être fait référence au caractère de fin de chaîne C '\0' ou à l'une des autres séquences d'échappement de chaînes C telles que '\n' sans échapper la barre oblique inversée. Pour inclure une barre oblique inversée littérale dans la documentation, échappez-la ainsi : \; vous pouvez également encadrer le fragment de code par \c{...}, ce qui empêche l'interprétation des barres obliques inversées comme des commandes QDoc.

Macro inconnue

QDoc émet cet avertissement lorsqu’il détecte une barre oblique inversée, \, suivie d’un token qu’il ne reconnaît ni comme le nom d’une commande intégrée ni comme celui d’une macro définie par l’utilisateur. Lorsque vous mettez entre guillemets du code contenant des séquences d’échappement de caractères, vous devez encadrer le code par \c{...} afin d’éviter cet avertissement concernant les séquences d’échappement.

Qualificateur de module/type QML non reconnu pour <identifiant>

Un paramètre transmis à \qmlproperty ou \qmlmethod contient une combinaison de qmlModule::qmlType::identifier qui n’est définie nulle part.

Exemple :

Unrecognizable QML module/type qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler ne dispose pas d’une propriété nommée DragAxis.

Style de liste non reconnu <name>

\listpeut prendre un argument facultatif : un nombre ou un caractère unique qui modifie le style de liste. Reportez-vous à la documentation {list-command}{\list} pour plus de détails. Si vous utilisez un argument non reconnu, QDoc affiche cet avertissement.

Langage de balisage non reconnu

Cet avertissement apparaît lorsqu'un langage de programmation est spécifié pour une commande \code que QDoc ne reconnaît pas. Par exemple, ce bloc de code QML s'est vu attribuer le langage « QL », qui n'est pas valide :

\code [QL]
Item {
    id: my_item
}
\endcode