Dépannage des avertissements de QDoc

QDoc peut émettre des avertissements lors de la génération de votre jeu de documents. Cette section décrit la signification de ces avertissements et comment les résoudre. Ce document ne décrit pas les avertissements générés par Clang.

Impossible de faire un lien vers <target>

QDoc émet 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 autre, la cible du lien. Cela peut être dû à une erreur de frappe dans la référence ou à un changement de nom (pour une fonction ou un type) ou de titre (pour une autre section) de la cible.

Recherchez dans le code source la cible du lien en question. Si vous n'obtenez aucun résultat, précisez progressivement la 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, lorsque cela est spécifié, la signature) utilisé là où il est documenté ne correspond pas au nom utilisé dans sa déclaration.
• La cible du lien est marquée comme \internal alors que le texte du lien ne l'est pas.

Trouvé une commande \target 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 dans un bloc\table... \endtable , il émet cet avertissement. L'avertissement est suivi du texte suivant Déplacer le \target à l'intérieur du \li pour résoudre cet avertissement.

Impossible de trouver un fichier de snippets à citer

QDoc émet cet avertissement s'il ne parvient pas à trouver le fichier nommé après une commande \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 de l'extrait à chacun des répertoires indiqués dans le chemin de recherche, afin d'obtenir un nom de chemin pour un fichier candidat à rechercher. Il produit cette erreur si aucun de ces candidats n'existe.
• Vérifiez le chemin de recherche des snippets, indiqué par la variable de configuration exampledirs dans le fichier *.qdocconf. Il se peut que vous deviez ajouter une entrée à ce chemin ou corriger une entrée existante.
• Vérifiez si le fichier de snippets existe, ou s'il a été déplacé, renommé ou supprimé, ce qui peut se produire en cas de modification du code source à partir duquel QDoc tente de faire une citation.

Inattendu \snippet

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

<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 sur la base de l'identifiant transmis à la commande \inqmlmodule ou \qmlproperty associé à un type QML.

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

No such <type> in QML <module>

QDoc émet cet avertissement si un \qmlproperty, \qmlmethod, ou \qmlsignal utilise un identifiant de module QML, mais que l'élément associé <type> n'appartient pas à ce module. \qmltype associé n'appartient pas à ce module.

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

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

Paramètre non documenté

QDoc exige que la documentation d'une fonction ou d'une méthode décrive chaque paramètre. Il le reconnaît à chaque nom de paramètre (tel qu'il est spécifié lorsque la fonction ou la méthode est déclarée dans un fichier d'en-tête) apparaissant après une commande \a après une commande

Cette exigence n'est pas imposée pour la documentation des surcharges de fonctions, à condition que la surcharge soit marquée par la commande \overload et qu'il existe une fonction entièrement documentée portant le même nom.

Aucun paramètre de ce type

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

Macro inconnue

QDoc émet cet avertissement lorsqu'il voit une barre oblique inverse, \, suivie d'un élément qu'il ne reconnaît pas comme étant le nom d'une commande intégrée ou d'une macro définie par l'utilisateur. Lorsque vous citez un code qui contient des séquences d'échappement de caractères, vous devez entourer le code dans \c{...} pour éviter cet avertissement contre les séquences d'échappement.

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

Lorsque Clang analyse une signature de fonction suivant une commande \fn il la compare à la déclaration dans le fichier d'en-tête. Si Clang découvre des divergences, il émet ce message d'avertissement.

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

Aucune sortie générée pour <entity> parce que <parent> n'est pas documenté

QDoc émet cet avertissement lorsqu'il analyse un commentaire de documentation pour une entité de l'API telle qu'un membre de classe, mais ne peut produire aucun résultat parce que le parent associé (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 commande \dontdocument ou utilisez la commande

Type QML <NomDeType> documenté avec <NomDeClasse> comme type natif. Remplacement de <NomDeClasse> par <AutreClasse>

Si la commande \nativetype 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, veillez à n'utiliser la commande \nativetype qu'une seule fois pour chaque classe C++.

Impossible de lier cette documentation à quoi que ce soit

QDoc a trouvé un commentaire /* ! ... */, sans commande topic, qui n'était pas immédiatement suivi d'une définition de classe, de fonction ou de propriété. Il ne sait donc pas ce que le commentaire documente.

Ce commentaire qdoc ne contient pas de commande de sujet (par exemple, \module, \page).

Si un commentaire QDoc ne contient pas de commande de sujet, QDoc ne sait pas ce que le commentaire documente et émet cet avertissement. Très similaire à Cannot tie this documentation to anything, mais spécifique aux commentaires qui ne sont pas dans des fichiers C++ ou QML.

<nom> documenté plus d'une fois

QDoc émet cet avertissement lorsqu'il trouve deux commentaires qui documentent le même élément. L'emplacement du commentaire précédent est indiqué dans les détails de l'avertissement.

Par exemple, cet avertissement apparaît lorsqu'une fonction a un commentaire de documentation précédant sa définition et un commentaire \fn distinct ailleurs.

<topic> ne peut pas être mélangé avec d'autres commandes de sujet

QDoc autorise l'utilisation de plusieurs commandes de rubrique dans un seul commentaire de documentation pour certains cas d'utilisation. L'utilisation de plusieurs commandes topic de différentes catégories entraîne l'affichage de cet avertissement, et le topic ne génère aucune sortie.

Espace de noms <nom> documenté plus d'une fois

Cet avertissement signifie qu'un jeu de documentation contient deux commentaires contenant les commandes suivantes \namespace avec le même argument, <nom>.

<nom> est documenté, mais l'espace de nommage <espace de nommage> n'est documenté dans aucun module.

La documentation pour <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 trouver de documentation.

Ce problème peut être résolu en documentant <espace de noms> ou, s'il est déjà documenté dans un autre module, en s'assurant que ce module en dépend.

Voir aussi depends et indexes.

N'a pas 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 avec la commande \inmodule à un module avec la commande

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

Cannot find <name> specified with \<command> in any header file (Impossible de trouver <nom> spécifié avec \<commande> dans un fichier d'en-tête)

Cela signifie que QDoc ne trouve pas de déclaration de <nom> dans un fichier d'en-tête, mais qu'il a trouvé un commentaire qui prétend le documenter.

Un exemple :

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

Un commentaire de documentation prétend décrire un enum, mais QDoc n'a pas trouvé de définition de cet enum dans un fichier d'en-tête.

Cela peut également être dû à

• une faute de frappe dans <nom> ou <commande>
• un espace de noms ou un préfixe de classe manquant
• <nom> a été déplacé vers un autre espace de noms ou une autre classe.

un qualificatif de module/type QML non reconnaissable pour <identificateur>.

Un paramètre passé à \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 n'a pas de propriété appelée DragAxis.

Type de propriété manquant pour <nom>

Une déclaration d'un \qmlproperty n'a pas de type de propriété.

La commande \qmlproperty s'attend à être suivie du type de propriété, puis du nom pleinement qualifié de la propriété (c'est-à-dire le nom ::-joint après le nom de la classe à laquelle elle appartient).

Incorrect :

\qmlproperty MyWidget::count

Correct :

\qmlproperty int MyWidget::count

Propriété non documentée "<nom>

Cet avertissement indique qu'une classe C++ possède une déclaration Q_PROPERTY qui n'est pas documentée. Les propriétés font partie de l'API publique d'une classe et doivent être documentées à l'aide de la commande \property pour décrire leur objectif, leurs valeurs valides et leur comportement.

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

QDoc utilise cet avertissement lorsqu'il trouve deux commentaires QDoc qui documentent la même propriété QML, soit en apparaissant juste avant sa définition, soit en utilisant la commande \qmlproperty commande.

Commande <commande> 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 seul commentaire de documentation pour documenter un groupe de propriétés dont le dernier élément du chemin d'accès est <group>.<property>. Toute autre commande de rubrique déclenche cet avertissement.

Fonction de base introuvable pour <méthode> dans <classe>

QDoc produit cet avertissement si \reimp est utilisé pour documenter une méthode, en tant que remplacement d'une méthode virtuelle, alors qu'aucune classe de base n'a de méthode virtuelle avec le nom et la signature donnés. Cela peut être dû au fait que la méthode sur laquelle la méthode a été écrite a changé de signature ou qu'elle n'est plus virtuelle.

Illegal \reimp; pas de fonction virtuelle documentée pour <commande>

Qdoc tente de créer un lien vers la fonction que cette commande réimplémente, mais il n'a pas pu trouver la cible du lien, probablement parce que cette fonction n'est pas documentée. Ce problème peut également survenir 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 ou de signature ou au fait que la classe de base ne déclare plus la méthode comme étant virtuelle.

Plusieurs définitions de surcharges primaires pour <fonction>

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

L'avertissement inclut les signatures des fonctions et leurs sources afin de faciliter l'identification de toutes les surcharges primaires concurrentes. QDoc déterminera la surcharge primaire réelle en utilisant une comparaison lexicographique (ordre alphabétique des signatures de fonction) parmi les fonctions marquées comme primaires.

Pour résoudre cet avertissement, supprimez l'argument primary de toutes les commandes \overload primary du groupe de surcharges, à l'exception d'une seule.

Exemple qui déclenche 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 fonction primaire :

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

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

<classe> tente d'hériter d'elle-même

La commande \inherits est utilisée pour documenter le fait qu'un type QML hérite d'un autre type QML. Cet avertissement est émis si cet autre type QML est le même que le type QML documenté.

Exemple :

\qmltype Foo
\inherits Foo

\nativetype n'est autorisé que dans \qmltype

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

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

Lorsque l'on documente des groupes de propriétés QML, toutes les propriétés énumérées dans le bloc de commentaires doivent appartenir au même type QML.

Fichier de projet introuvable pour l'exemple <nom>

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 où le nom de base correspond à celui du répertoire de l'exemple. Par exemple, examples/mymodule/helloworld/helloworld.pro.

Impossible d'ouvrir le fichier à citer à partir de : <nom de fichier>

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

QDoc n'a pas réussi à trouver un fichier nommé dans une commande (telle que \quotefromfile, \snippet, \include) qui lui demande de récupérer le contenu du fichier nommé. Il recherche dans chaque répertoire nommé dans le chemin de recherche. S'il n'y a pas de fichier portant ce nom dans l'un de ces répertoires, ou si le fichier est trouvé mais illisible, QDoc émet cet avertissement. Vérifiez que la combinaison chemin de recherche et <nom de fichier> est correctement orthographiée et que vous disposez des droits de lecture pour le fichier.

Nom de format manquant après \raw

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

La macro ne peut pas avoir à la fois des définitions spécifiques au format et des définitions de la syntaxe qdoc.

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

Exemple de configuration qui déclenche cet avertissement :

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

Commande inconnue <nom>

Lorsqu'un commentaire QDoc utilise une barre oblique inverse suivie d'un élément qui n'est pas une commande intégrée de QDoc et qui n'a pas été défini comme une macro-commande personnalisée, QDoc émet cet avertissement. Vérifiez l'orthographe du nom de la commande et vérifiez si votre configuration QDoc n'inclut pas ce qui l'aurait définie, s'il s'agit d'une commande personnalisée.

Par exemple, l'auteur peut avoir 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îne C telles que '\n' sans avoir échappé l'antislash. Échapper la barre oblique inverse comme \ pour inclure une barre oblique inverse littérale dans la documentation, ou entourer le fragment de code dans \c{...}, ce qui supprime l'interprétation des barres obliques inverses comme introduisant des commandes QDoc.

Duplication du nom de la cible <target>

Cet avertissement est émis si vous définissez deux cibles avec le même paramètre, en utilisant soit l'option \target ou la commande \keyword ou de la commande Le nom de la cible donné en paramètre à ces commandes doit être unique. L'avertissement est suivi de "L'occurrence précédente est ici : [emplacement]", où l'emplacement contient un nom de fichier et un numéro de ligne.

Cannot find qdoc include file <filename> (Impossible de trouver le fichier d'inclusion de qdoc)

QDoc n'a pas réussi à trouver un fichier include nommé dans une commande. QDoc recherche dans chaque répertoire nommé dans le chemin de recherche. S'il n'y a pas de 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 émet cet avertissement. Vérifiez que la combinaison du chemin de recherche et de <nom de fichier> est correctement orthographiée et que vous disposez des droits de lecture pour le fichier.

Cannot find <tag> in <file> (Impossible de trouver <tag> dans <fichier>)

Cela signifie que QDoc ne peut pas trouver l'identifiant <id> dans le fichier <file> ou {snc}. \include <file> ou {snippet-command}{\snippet} <file>.

Extrait qdoc vide <tag> dans <file>

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

Impossible d'imbriquer des commandes <commande>

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 à l'intérieur du texte auquel elle s'applique. En voici un 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

Résultat de l'avertissement QDoc "Can't use '\table' in '\list'".

<outer> manquant avant <inner>

Quelques exemples :

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

Commande de fin inattendue

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

Virgule manquante dans \sa

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

La macro <commande> n'a pas de définition par défaut

QDoc tente d'étendre une macro et s'attend à ce que cette macro ait une définition par défaut. Certaines macros peuvent n'avoir que des définitions spécifiques au format.

Exemple :

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

Dans certains cas, 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 elles doivent avoir des définitions par défaut.

Macro <macro> invoquée avec trop peu d'arguments (attendue <nombre>, obtenue <peu>)

La macro donnée a besoin de plus de paramètres qu'elle n'en a reçu. Voir la définition de la macro dans la configuration pour plus de détails.

Parenthèses déséquilibrées dans <text>

Pointe vers un '(' sans un ')' correspondant, ou vice versa.

Pas de documentation pour <nom>

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 où cet espace de noms a été documenté.

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

Exemple :

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

QDoc émet cet avertissement lorsqu'il trouve une directive \value dans un commentaire \enum qui nomme une valeur qui ne se trouve pas dans le fichier d'en-tête qui a déclaré le type énuméré documenté.

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

L'élément <enum> d'une <liste d'énumérations> est non documenté. \value ou \omitvalue de <enum list> ne contient pas d'entrée pour <enum>, qui est nommé dans la déclaration de <enum list> dans le fichier d'en-tête.

Échec de la recherche de qhp.<project>.subprojects.<subproject>.indexTitle

QDoc n'a pas réussi à trouver un titre pour une page désignée comme page d'index pour <subproject> dans la configuration du projet d'aide Qt.

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

Pour plus d'informations, voir Création de fichiers de projet d'aide.

\generatelist <group> est vide

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

• \generatelist annotatedexamples
• \generatelist attributions annotées
• \generatelist classes <préfixe>
• \generatelist classesbymodule <nom du module>
• \generatelist qmltypesbymodule <nom du module>
• \generatelist functionindex
• \generatelist legalese
• \generatelist vues d'ensemble
• \generatelist attributions
• \generatelist apparenté

QDoc émet 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> no such group

Cet avertissement est émis si l'argument de \generatelist est un groupe inexistant.

Exemple :

\generatelist draganddrop

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

QDoc émet ce message d'avertissement si aucune entité ne possède cette instruction \ingroup draganddrop.

Image manquante : <imagefile>

Le chemin de recherche de l'image est incorrect ou le fichier image n'existe pas.

Impossible d'établir un lien avec <target>

Les causes peuvent être diverses :

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

Impossible de résoudre l'instruction d'importation QML pour le type <nom>.

QDoc émet cet avertissement si vous documentez un type QML, mais omettez la commande \inqmlmodule mais que vous avez omis la 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

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

L'argument de la commande \brief est une phrase qui résume le sujet documenté et doit donc se terminer par un point. Il doit donc se terminer par un point. Il doit également être bref.

QtDeclarative n'est pas installé ; ne peut pas analyser QML

QDoc émet cet avertissement s'il a été compilé sans support pour l'analyse QML. Cela ne devrait pas se produire à moins que vous n'ayez une version personnalisée de QDoc.

Expression régulière invalide <regex>

Certaines commandes de QDoc prennent des expressions régulières comme paramètres. QDoc émet 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 spéciale dans les expressions régulières, 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 commande \printuntil imprime 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.

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

Utilisation de <indexfile> comme fichier d'index pour la dépendance <depend>

Plusieurs chemins d'accès -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 choisit automatiquement celui dont l'horodatage est le plus récent.

Généralement, cet avertissement indique qu'il reste des artefacts d'une précédente compilation de la documentation.

Cannot locate index file for dependency <depend> (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 pu localiser activeqt.index dans aucun des répertoires d'index spécifiés. Dans ce cas, les répertoires d'index spécifiés sont indiqués dans qmake.qdocconf.

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

QDoc s'attendait à voir un ou plusieurs arguments -indexdir sur la ligne de commande. Sans eux, QDoc ne peut pas localiser les fichiers d'index des modules dépendants définis avec la variable de configuration 'depends'.

Remplace un document précédent

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

Style de liste non reconnu <nom>

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

Unable to parse QML snippet : <code> at line <y>, column <x> (Impossible d'analyser l'extrait QML : <code> à la ligne <y>, colonne <x>)

Les commentaires QDoc peuvent contenir du code QML. Ce code peut se trouver dans un extrait 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 suivant

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

Les snippets peuvent également contenir du QML et c'est là aussi que le code est vérifié. Si, par exemple, il manque une accolade dans le code, QDoc émet l'avertissement suivant

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

QDoc ne parvient souvent pas à analyser les extraits QML incomplets ; dans ce cas, il est souvent possible de remplacer les commandes \qml... \endqml par \code... \endcode pour supprimer cet avertissement.

La commande <commande> a échoué à la fin du fichier <nom du fichier>.

Exemple :

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

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

Autre exemple :

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

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

Failed to open <file> for writing (Échec de l'ouverture du <fichier> en écriture)

Cet avertissement signifie clairement qu'il ne peut pas ouvrir un fichier en écriture, probablement en raison d'un chemin d'accès erroné ou de l'autorisation d'écrire dans un certain répertoire.

Ce titre de page existe dans plus d'un fichier

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

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

QDoc émet cet avertissement si un certain titre est utilisé dans plus d'une page.

Le contenu est trop long

QDoc utilise une mémoire tampon de taille fixe lors de la symbolisation des fichiers source. Si un seul élément du fichier contient plus de caractères que la limite maximale, QDoc émet cet avertissement.

Pendant que QDoc poursuit l'analyse du fichier, seule la partie du jeton qui entre dans la mémoire tampon est prise en compte, ce qui signifie que la sortie peut être tronquée.

Pour résoudre cet avertissement, le contenu concerné doit être réduit en taille, soit en le divisant, si possible, soit en supprimant certaines de ses parties.

La quantité maximale de caractères pour un seul élément est indiquée à 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.]

Aucune documentation générée pour la fonction <nom> dans la portée globale

QDoc a pu faire correspondre la documentation d'une fonction <nom> à sa déclaration, mais aucune sortie n'a été générée parce que la fonction est déclarée dans l'espace de noms global.

Utilisez la commande \relates pour associer la fonction à un type documenté, à un espace de noms ou à un fichier d'en-tête. La fonction est alors répertoriée en tant que non-membre connexe sur la page de référence associée.

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

Une configuration d'aide Qt Help valide était attendue mais n'a pas été fournie dans le fichier .qdocconf du projet.

Voir aussi Création de fichiers de projet d'aide et qhp.

Fichier déjà généré pour ce projet

Lors de la génération de la documentation d'un projet, QDoc garde en mémoire les noms des fichiers qu'il a générés. QDoc émet un avertissement lorsqu'il ouvre un fichier en écriture s'il sait que ce fichier a été généré précédemment, dans l'exécution en cours. Cela peut se produire si une commande \page utilise le même nom que \group par exemple.

Vous pouvez définir la variable d'environnement QDOC_ALL_OVERWRITES_ARE_WARNINGS pour qu'un avertissement inconditionnel soit émis pour tous les événements de ce type. Cela peut s'avérer utile pour retrouver les définitions incriminées.

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 survient généralement lorsque les développeurs font référence au type Qt sous-jacent utilisé pour mettre en œuvre un type QML, par exemple QStringList au lieu de list<string>.

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

Le type QML a été incorrectement défini comme son propre type de base, éventuellement à l'aide de la commande \inherits commande.

Héritage cyclique d'un type : <type>

L'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 original. 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 qu'un cycle a été détecté dans la hiérarchie de l'héritage. Vous devez examiner la commande \inherits pour le type et suivre la piste des types de base jusqu'à ce que vous en trouviez un qui hérite d'un type que vous avez déjà rencontré. Vous devez alors rompre le cycle en corrigeant la commande incorrecte pour l'un des types identifiés. \inherits incorrecte pour l'un des types identifiés.

Lien redondant vers soi dans la commande \sa pour <nom>.

Un document contient un lien vers lui-même dans les références définies dans sa commande \sa dans les références définies dans sa commande <nom>.

Ce problème tend à se produire lorsqu'il existe une collection de propriétés ou de méthodes apparentées qui se réfèrent les unes aux autres et que les commandes \sa ont été copiées entre elles, comme dans cet exemple :

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

Il est utile de remplacer le lien d'autoréférence par un lien vers une autre propriété ou méthode apparentée.

Il se peut aussi 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)

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

Le nom du type déclaré comme type de base pour un type QML n'a pas été trouvé ou n'a pas été déclaré avec la commande \inherits ou n'a pas été déclaré à l'aide de la commande

Langage de balisage non reconnu

Cet avertissement se produit lorsqu'un langage de programmation non reconnu par QDoc est spécifié pour une commande \code. Par exemple, ce bloc de code QML s'est vu attribuer le langage "QL" non valide :

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