Comment résoudre les avertissements de QDoc
QDoc peut émettre des avertissements lors de la génération de votre documentation. 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 a été marquée comme interne alors que le texte du lien ne l'était 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 ...\Ndans un bloc de tableau, il émet cet avertissement. L'avertissement est suivi du texte Déplacer la commande \target à l'intérieur de la commande \li pour résoudre cet avertissement.
Impossible de trouver le 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érifier que le nom du fichier de l'extrait 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
exampledirsdans 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.
Extrait inattendu
QDoc émet cet avertissement s'il ne parvient pas à localiser le fichier d'extrait cité dans une commande \snippet.
<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 aux commandes \inqmlmodule ou \qmlproperty associées à 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.
Aucun <type> de ce type dans QML <module>
QDoc émet cet avertissement si un argument de commande \qmlproperty, \qmlmethod, ou \qmlsignal utilise un identifiant de module QML, mais que le \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 l'identifiant du 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.
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 donné après une commande \a ne correspond à aucun des paramètres nommés dans la déclaration du fichier d'en-tête de la fonction ou de la méthode documentée.
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 de \c{...} pour éviter cet avertissement contre les séquences d'échappement.
Échec de la recherche d'une fonction lors de l'analyse de \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.
Note : La signature \fn pour un ami caché doit être entièrement qualifiée avec la portée de la classe qui déclare la fonction.
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 possède 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 topic 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 des commandes de l'espace de nommage 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 soit en documentant <espace de noms>, soit, s'il est déjà documenté dans un autre module, en s'assurant que ce module en dépend.
Voir aussi depends et {indexes-variable}{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 à l'aide de la commande \inmodule.
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 soit \inmodule pour l'associer à son contexte plus large. Cet avertissement est levé si ce n'est pas le cas.
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 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 <identifier>.
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>
La déclaration d'une propriété \qmlproperty ne contient 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 il appartient).
Incorrect : le nom ::-joined après le nom de la classe à laquelle il appartient :
\qmlproperty MyWidget::count
Correct :
\qmlproperty int MyWidget::count
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> 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 elle a été écrite a changé de signature ou 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. Cette situation 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 ou de signature, ou au fait que la base ne déclare plus la méthode comme étant virtuelle.
<classe> tente d'hériter d'elle-même
La commande \inherits est utilisée pour documenter 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 listé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 \Nquotefromfile, \Nsnippet, \Ninclude) qui lui indique 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 non lisible, 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.
Note : <filename> peut inclure un préfixe de nom de répertoire ; le <filename> entier est ajouté à chaque répertoire dans le chemin de recherche.
Nom de format manquant après \raw
La commande \raw et la commande \endraw correspondante délimitent un bloc de code brut de langage de balisage. La commande \raw doit être suivie du nom du format.
Une macro ne peut pas avoir à la fois des définitions spécifiques à un format et des définitions de syntaxe qdoc
Une macro \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 en tant que 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 la commande \target ou \keyword. 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.
Note : <filename> peut inclure un préfixe de nom de répertoire ; le <filename> entier est ajouté à chaque répertoire dans le chemin de recherche.
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 \include <file> ou {snippet-command}{\snippet} <file>.
Extrait qdoc vide <tag> dans <file>
Le snippet <tag> a été trouvé dans le \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
\endlistAvertissement QDoc "Can't use '\table' in '\list'" (Impossible d'utiliser '\table' dans '\list').
Absence de <outer> avant <inner>
Quelques exemples :
- La commande \li ne peut être utilisée qu'à l'intérieur d'une \list ou d'une \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 \n-liste de fin sans \n-liste précédente. 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 non trouvée 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>
Les entrées \value ou \omitvalue de <enum list> n'incluent pas une entrée pour <enum>, qui est nommée 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 (liste d'exemples annotés)
- \generatelist annotatedattributions (liste des attributions annotées)
- \generatelist classes <préfixe>
- \generatelist classesbymodule <nom du module>
- \generatelist qmltypesbymodule <nom du module>
- \generatelist functionindex
- \generatelist legalese
- \generatelist overviews
- \generatelist attributions
- \generatelist related
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 leur commentaire \class ou \qmltype.
QDoc émet ce message d'avertissement si aucune entité ne possède cette déclaration \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 sujet QDoc, par exemple {commande de titre}{\titre} <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 cette cible de lien 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. 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
L'instruction \brief ne se termine pas par un point
L'argument de la commande \brief est une phrase, résumant le sujet documenté, et doit donc se terminer par un point. Il devrait donc se terminer par un point. Il devrait é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>
\list peut 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 :
En cas d'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 52QDoc ne parvient souvent pas à analyser les snippets 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 trouvé aucune occurrence de cette étiquette dans ce fichier de snippets.
Autre exemple :
Command '\skipto' failed at end of file 'styling/CMakeLists.txt".
\skipto + <pattern> déplace le curseur à la ligne suivante contenant ce motif. Si \skipto ne le trouve pas, QDoc émet cet avertissement.
Échec de l'ouverture de <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 un 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 tient 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.]
Remarque : Étant donné qu'un contenu trop long n'est pas analysé dans son intégralité, QDoc peut émettre des avertissements qui sont de faux positifs. Résolvez tous les avertissements de ce type avant de résoudre les autres avertissements.
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>.
Voir aussi Fichier d'inclusion qdoc introuvable <nom de fichier> et Fichier à citer impossible à ouvrir : <nom de fichier>.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.