Wie man QDoc-Warnungen auflöst

QDoc kann bei der Erstellung Ihrer Dokumentation Warnungen ausgeben. Dieser Abschnitt beschreibt, was diese Warnungen bedeuten und wie man sie behebt. Dieses Dokument beschreibt keine Warnungen, die von Clang erzeugt werden.

Kann nicht auf <Ziel> verweisen

QDoc gibt diese Warnung aus, wenn ein Teil der Dokumentation (in der Warnmeldung identifiziert) versucht, auf einen anderen zu verweisen, aber diesen anderen Teil, das Ziel des Links, nicht korrekt angibt. Das kann daran liegen, dass der Verweis darauf falsch geschrieben ist oder dass das Ziel einen anderen Namen (für eine Funktion oder einen Typ) oder Titel (für einen anderen Abschnitt) hat.

Durchsuchen Sie den Quellcode nach diesem bestimmten Linkziel. Wenn Sie keine Ergebnisse erhalten, schränken Sie die Suche schrittweise ein, bis Sie eine Übereinstimmung finden.

Wenn das Linkziel wie der Name eines Typs oder einer Funktion aussieht, kann das auch daran liegen:

• Der Name (oder bei Funktionen, wo angegeben, die Signatur), der an der Stelle verwendet wird, an der er dokumentiert ist, stimmt nicht mit dem Namen überein, der in seiner Deklaration verwendet wird.
• Das Verknüpfungsziel wurde als \intern markiert, obwohl der Verknüpfungstext dies nicht war.

Ein \target-Kommando außerhalb eines Tabellenelements in einer Tabelle gefunden

Wenn QDoc auf einen \target-Befehl stößt, dem kein \li-Befehl innerhalb eines \table ... \endtable-Block steht, gibt es diese Warnung aus. Auf die Warnung folgt der Text Verschieben Sie das \target innerhalb des \li, um diese Warnung zu beheben.

Snippets-Datei zum Zitieren nicht gefunden

QDoc gibt diese Warnung aus, wenn es die Datei, die nach einem \snippet- oder \quotefromfile-Befehl benannt ist, nicht finden kann.

Einige nützliche Schritte zur Behebung dieses Problems:

• Überprüfen Sie, ob der Name der Snippet-Datei korrekt ist. QDoc hängt den Snippet-Dateinamen an jedes der im Suchpfad angegebenen Verzeichnisse an, um einen Pfadnamen für eine zu suchende Datei zu erhalten. Es erzeugt diesen Fehler, wenn keiner dieser Kandidaten existiert.
• Überprüfen Sie den Suchpfad für Snippets, der durch die Konfigurationsvariable exampledirs in der Datei *.qdocconf angegeben ist. Möglicherweise müssen Sie einen Eintrag zu diesem Pfad hinzufügen oder einen bestehenden Eintrag korrigieren.
• Überprüfen Sie, ob die Snippet-Datei existiert, oder ob sie verschoben, umbenannt oder entfernt wurde, was passieren kann, wenn es Änderungen am Quellcode gibt, aus dem QDoc zu zitieren versucht.

Unerwartetes \snippet

QDoc gibt diese Warnung aus, wenn es nicht in der Lage ist, die in einem \snippet-Befehl zitierte Snippet-Datei zu finden.

Undokumentiertes QML <Modul>, das von <Typ> oder seinen Mitgliedern referenziert wird

QDoc gibt diese Warnung aus, wenn es nicht in der Lage ist, ein QML-Modul auf der Grundlage des Bezeichners zu finden, der an die Befehle \inqmlmodule oder \qmlproperty übergeben wurde, die mit einem QML-Typ verbunden sind.

Dies bedeutet, dass entweder die Dokumentation für das \qmlmodule fehlt oder ein falscher Modulbezeichner in den Befehlen \qmlproperty, \qmlmethod oder \qmlsignal verwendet wurde.

Kein solcher <Typ> in QML <Modul>

QDoc gibt diese Warnung aus, wenn ein \qmlproperty-, \qmlmethod- oder \qmlsignal-Befehlsargument einen QML-Modulbezeichner verwendet, der zugehörige \qmltype aber nicht zu diesem Modul gehört.

Der QML-Modulbezeichner muss, falls definiert, mit dem Argument \inqmlmodule in der QML-Typdokumentation übereinstimmen. In den meisten Fällen ist QDoc in der Lage, den QML-Typ auch ohne einen Modulbezeichner zu finden.

Undokumentierter Rückgabewert

Bei Funktionen, deren Rückgabetyp nicht void ist, prüft QDoc, ob der Rückgabewert dokumentiert ist. Diese Warnung wird ausgegeben, wenn die Dokumentation für eine Funktion oder Methode kein Wort enthält, das mit "return" beginnt.

Undokumentierter Parameter

QDoc verlangt von der Dokumentation einer Funktion oder Methode, dass jeder Parameter beschrieben wird. QDoc erkennt dies daran, dass jeder Parametername (wie bei der Deklaration der Funktion oder Methode in einer Header-Datei angegeben) nach einem \a-Befehl erscheint.

Diese Anforderung gilt nicht für die Dokumentation von Funktionsüberladungen, vorausgesetzt, die Überladung ist mit dem \overload gekennzeichnet ist und eine vollständig dokumentierte Funktion mit demselben Namen existiert.

Kein solcher Parameter

QDoc gibt diese Warnung aus, wenn der nach einem \a-Befehl angegebene Parametername nicht mit einem der Parameter übereinstimmt, die in der Deklaration der zu dokumentierenden Funktion oder Methode in der Header-Datei genannt werden.

Unbekanntes Makro

QDoc gibt diese Warnung aus, wenn es einen Backslash, \, gefolgt von einem Token sieht, das es nicht als Name eines eingebauten Befehls oder eines benutzerdefinierten Makros erkennt. Wenn Sie Code zitieren, der Escape-Sequenzen enthält, sollten Sie den Code in \c{...} einschließen, um diese Warnung vor Escape-Sequenzen zu vermeiden.

Funktion konnte beim Parsen von \fn <Signatur> nicht gefunden werden

Wenn Clang eine Funktionssignatur parst, die einem \fn Befehl parst, prüft es diese gegen die Deklaration in der Header-Datei. Wenn Clang Diskrepanzen feststellt, gibt es diese Warnmeldung aus.

Die Signatur muss vollständig qualifiziert sein. Typische Probleme sind fehlende oder falsche Template-Argumente, Rückgabetypen oder Qualifier wie const.

QML-Typ <Typenname> dokumentiert mit <Klassenname> als seinem nativen Typ. Ersetzen von <Klassenname> durch <AndereKlasse>

Wenn der \nativetype Befehl mit demselben Argument in mehreren QML-Typ-Dokumentationskommentaren verwendet wird, die zum selben Dokumentationsprojekt gehören, gibt QDoc diese Warnung aus. Um dies zu beheben, stellen Sie sicher, dass Sie den \nativetype Befehl nur einmal für jede C++ Klasse verwenden.

Diese Dokumentation kann nicht mit etwas verknüpft werden

QDoc fand einen /*! ... */-Kommentar ohne Topic-Befehl, der nicht unmittelbar von einer Klassen-, Funktions- oder Eigenschaftsdefinition gefolgt wurde. Es weiß also nicht, was der Kommentar dokumentiert.

Dieser QDoc-Kommentar enthält keinen Topic-Befehl (z.B. \module, \page)

Wenn ein QDoc-Kommentar kein Topic Command enthält, weiß QDoc nicht, was der Kommentar dokumentiert, und gibt diese Warnung aus. Ähnlich wie Cannot tie this documentation to anything, aber spezifisch für Kommentare, die nicht in C++- oder QML-Dateien stehen.

<Name> mehr als einmal dokumentiert

QDoc gibt diese Warnung aus, wenn es zwei Kommentare findet, die dasselbe Element dokumentieren. Der Ort des zuvor gesehenen Kommentars wird in den Warnungsdetails angegeben.

Diese Warnung wird zum Beispiel angezeigt, wenn eine Funktion einen Dokumentationskommentar vor ihrer Definition und einen separaten \fn-Kommentar an anderer Stelle hat.

Namespace <Name> mehr als einmal dokumentiert

Diese Warnung bedeutet, dass eine Dokumentationsmenge zwei Kommentare enthält, die \namespace-Befehle mit demselben Argument, <name>, enthalten.

<name> ist dokumentiert, aber Namespace <namespace> ist in keinem Modul dokumentiert

Die Dokumentation für <name> wurde gefunden, aber <name> ist unter einem Namespace deklariert, der entweder nicht dokumentiert ist oder QDoc konnte die Dokumentation dafür nicht finden.

Dies kann gelöst werden, indem entweder <Namensraum> dokumentiert wird , oder, wenn er bereits in einem anderen Modul dokumentiert ist, sichergestellt wird, dass dieses Modul eine Abhängigkeit dazu hat.

Siehe auch depends und {indexes-variable}{indexes}.

Hat keinen \inmodule Befehl

QDoc gibt diese Warnung aus, wenn die QDoc-Kommentare eine Klasse, einen Namespace oder eine Headerdatei nicht mit einem Modul mit dem \inmodule-Kommando in Beziehung setzen.

Wenn der QDoc-Kommentar eine Entität beschreibt, die nicht Mitglied einer anderen Entität (typischerweise ein Namespace oder eine Klasse) ist, sollte er entweder \relates oder \inmodule verwenden, um sie mit ihrem breiteren Kontext zu verbinden. Ist dies nicht der Fall, wird diese Warnung ausgegeben.

Cannot find <name> specified with \<command> in any header file

Dies bedeutet, dass QDoc keine Deklaration von <Name> in einer Header-Datei finden kann, aber einen Kommentar gefunden hat, der behauptet, diesen zu dokumentieren.

Ein Beispiel:

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

Ein Dokumentationskommentar behauptet, ein Enum zu beschreiben, aber QDoc hat keine Definition dieses Enums in einer Header-Datei gefunden.

Dies kann auch auf Folgendes zurückzuführen sein:

• ein Tippfehler in <Name> oder <Befehl>
• ein fehlendes Namespace- oder Klassenpräfix
• <Name> wurde in einen anderen Namespace oder eine andere Klasse verschoben

Unerkennbarer QML-Modul/Typ-Qualifizierer für <Bezeichner>

Ein an \qmlproperty oder \qmlmethod übergebener Parameter enthält eine Kombination von qmlModule::qmlType::identifier, die nirgends definiert ist.

Beispiel:

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

DragHandler Das Modul <Name> hat keine Eigenschaft namens DragAxis.

Fehlender Eigenschaftstyp für <Name>

Bei der Deklaration einer \qmlproperty fehlt der Typ der Eigenschaft.

Der Befehl \qmlproperty erwartet, dass nach dem Typ der Eigenschaft der vollqualifizierte Name der Eigenschaft folgt (d.h. der Name ::-joined nach dem Namen der Klasse, zu der er gehört).

Falsch:

\qmlproperty MyWidget::count

Korrekt:

\qmlproperty int MyWidget::count

QML-Eigenschaft mehrfach dokumentiert: <Bezeichner>

QDoc verwendet diese Warnung, wenn es zwei QDoc-Kommentare findet, die dieselbe QML-Eigenschaft dokumentieren, entweder indem sie direkt vor ihrer Definition erscheinen oder indem der Befehl \qmlproperty verwendet wird.

Der Befehl <command> ist bei QML-Eigenschaftsbefehlen nicht erlaubt

Beispiel:

\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()

Fehlermeldung:

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

Diese Warnung ist spezifisch für die Dokumentation von Eigenschaftsgruppen. QDoc erlaubt mehrere qmlproperty oder qmlattachedproperty Themenbefehle in einem einzigen Dokumentationskommentar, um eine Eigenschaftsgruppe zu dokumentieren, bei der das letzte Element im Pfad <group>.<property> ist. Jeder andere Themenbefehl löst diese Warnung aus.

Basisfunktion für <Methode> in <Klasse> nicht gefunden

QDoc erzeugt diese Warnung, wenn \reimp verwendet wird, um eine Methode als Überschreibung einer virtuellen Methode zu dokumentieren, wenn keine Basisklasse eine virtuelle Methode mit dem angegebenen Namen und der Signatur hat. Dies kann passieren, weil die Methode, die überschrieben werden soll, ihre Signatur geändert hat oder nicht mehr virtuell ist.

Illegal \reimp; keine dokumentierte virtuelle Funktion für <command>

Qdoc versucht, einen Link zu der Funktion zu erstellen, die dieser Befehl neu implementiert, konnte aber das Linkziel nicht finden, wahrscheinlich weil diese Funktion nicht dokumentiert ist. Dies kann auch auftreten, wenn keine Basisklasse eine virtuelle Methode mit diesem Namen und dieser Signatur hat; dies kann durch eine Umbenennung, eine Änderung der Signatur oder dadurch entstehen, dass die Basisklasse die Methode nicht mehr als virtuell deklariert.

<Klasse> versucht, sich selbst zu erben

Der Befehl \inherits wird verwendet, um zu dokumentieren, dass ein QMl-Typ einen anderen QML-Typ erbt. Diese Warnung wird ausgegeben, wenn dieser andere QML-Typ derselbe ist wie der dokumentierte QML-Typ.

Beispiel:

\qmltype Foo
\inherits Foo

\nativetype ist nur in \qmltype erlaubt

Der Befehl \nativetype kann nur in einem QDoc-Kommentar verwendet werden, der einen QML-Typ dokumentiert.

Alle Eigenschaften in einer Gruppe müssen zum selben Typ gehören: <Name>

Bei der Dokumentation von QML-Eigenschaftsgruppen müssen alle im Kommentarblock aufgeführten Eigenschaften zum selben QML-Typ gehören.

Projektdatei für Beispiel <Name> kann nicht gefunden werden

Im Quellverzeichnis des Beispiels erwartet QDoc eine Projektdatei mit dem Namen CMakeLists.txt oder eine Datei mit der Erweiterung .pro, .qmlproject oder .pyproject, deren Basisname mit dem des Beispielverzeichnisses übereinstimmt. Zum Beispiel: examples/mymodule/helloworld/helloworld.pro.

Datei zum Zitieren kann nicht geöffnet werden von: <Dateiname>

Der Suchpfad für <Dateiname> wird durch die folgenden Variablen in der Datei .qdocconf definiert: sources, sourcedirs, und exampledirs.

QDoc konnte eine Datei nicht finden, die in einem Befehl (wie \quotefromfile, \snippet, \include) genannt wurde, der es anweist, den Inhalt aus der genannten Datei zu holen. Es durchsucht jedes im Suchpfad genannte Verzeichnis. Wenn es keine Datei mit diesem Namen in einem dieser Verzeichnisse gibt, oder die Datei zwar gefunden wird, aber nicht lesbar ist, gibt QDoc diese Warnung aus. Vergewissern Sie sich, dass die Kombination aus Suchpfad und <Dateiname> richtig geschrieben ist und dass Sie Leserechte für die Datei haben.

Fehlender Formatname nach \raw

Der Befehl \raw und der entsprechende Befehl \endraw begrenzen einen Block mit Rohcode der Auszeichnungssprache. Auf den Befehl \raw muss der Formatname folgen.

Makros können nicht sowohl formatspezifische als auch qdoc-Syntax-Definitionen enthalten

Ein \macro, das ein Ausgabeformat angibt, kann nicht gleichzeitig eine generische Definition haben.

Ein Beispiel für eine Konfiguration, die diese Warnung auslöst:

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

Unbekannter Befehl <Name>

Wenn ein QDoc-Kommentar einen Backslash gefolgt von einem Token verwendet, das kein eingebautes QDoc-Kommando ist und nicht als benutzerdefiniertes Kommandomakro definiert wurde, erzeugt QDoc diese Warnung. Überprüfen Sie die Schreibweise des Kommandonamens und prüfen Sie, ob Ihre QDoc-Konfiguration nicht das enthält, was es definiert hätte, wenn es ein benutzerdefiniertes Kommando wäre.

Diese Warnung kann auch durch Code entstehen, der im QDoc-Kommentar zitiert wird, z.B. wenn der Autor auf das C-String-Beendigungszeichen '\0' oder eine der anderen C-String-Escape-Sequenzen wie '\n' Bezug genommen hat, ohne den Backslash zu escapen. Geben Sie den Backslash als \ aus, um einen buchstäblichen Backslash in die Dokumentation aufzunehmen, oder schließen Sie das Codefragment in \c{...} ein, was die Interpretation von Backslashes als einleitende QDoc-Befehle unterdrückt.

Duplizierter Zielname <target>

Diese Warnung wird ausgegeben, wenn Sie zwei Ziele mit demselben Parameter definieren, indem Sie entweder den Befehl \target oder den Befehl \keyword verwenden. Der als Parameter für diese Befehle angegebene Zielname muss eindeutig sein. Auf die Warnung folgt der Hinweis "Das vorherige Vorkommen ist hier: [location]", wobei location einen Dateinamen und eine Zeilennummer enthält.

Kann die qdoc-Include-Datei <Dateiname> nicht finden

QDoc konnte eine in einem Befehl genannte Include-Datei nicht finden. QDoc durchsucht jedes im Suchpfad genannte Verzeichnis. Wenn es in keinem dieser Verzeichnisse eine Datei mit diesem Namen gibt, oder die gefundene Datei nicht lesbar ist, gibt QDoc diese Warnung aus. Vergewissern Sie sich, dass die Kombination aus Suchpfad und <Dateiname> richtig geschrieben ist und dass Sie Leserechte für die Datei haben.

Kann <Tag> in <Datei> nicht finden

Dies bedeutet, dass QDoc den Bezeichner <id> nicht in <Datei> oder <Snippet-Befehl}{\snippet} <Datei> finden kann.

Leeres qdoc-Snippet <tag> in <Datei>

Das Snippet <tag> wurde im \snippet <file> gefunden, aber es ist leer.

Befehle <command> können nicht verschachtelt werden

Diese Warnung betrifft Formatierungsbefehle: bold, italic, index, link, span, subscript, superscript, teletype, uicontrol, underline. Ein Formatierungsbefehl kann nicht innerhalb des Textes verwendet werden, für den er gilt. Ein Beispiel hierfür:

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

Führt zu der QDoc-Warnung "Can't use '\table' in '\list'".

Fehlendes <outer> vor <inner>

Einige Beispiele:

• Der Befehl \li kann nur innerhalb einer \list oder einer \row einer \table verwendet werden.
• Die Befehle \row und \header können nur innerhalb einer \table verwendet werden.

Unerwartetes <end_command>

Diese Warnung wird ausgegeben, wenn Sie z. B. eine \endlist ohne eine vorangehende \list haben. Sie gilt für alle Befehle, die paarweise auftreten (z. B. startFoo/endFoo).

Fehlendes Komma in \sa

Die für einen \sa-Befehl aufgeführten Titel sollten durch Kommas voneinander getrennt werden.

Makro <Befehl> hat keine Standarddefinition

QDoc versucht, ein Makro zu erweitern, und erwartet, dass dieses Makro eine Standarddefinition hat. Einige Makros haben möglicherweise nur formatspezifische Definitionen.

Beispiel:

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

Es gibt jedoch Fälle, in denen die Makroexpansion ein formatunabhängiges Makro erfordert. So können Sie beispielsweise Makros in Abschnittsüberschriften verwenden, die jedoch eine Standarddefinition haben müssen.

Makro <macro> wurde mit zu wenigen Argumenten aufgerufen (erwartet <viele>, erhalten <wenige>)

Das angegebene Makro benötigt mehr Parameter, als ihm gegeben wurden. Siehe die Definition des Makros in der Konfiguration für weitere Details.

Unausgewogene Klammern in <text>

Zeigt auf ein '(' ohne ein entsprechendes ')', oder andersherum.

Keine Dokumentation für <Name>

Beispiel:

Warning "No documentation for QNativeInterface."

QDoc erkennt die Deklaration des Namespace QNativeInterface in einer Header-Datei, findet aber keinen QDoc-Kommentar, in dem dieser Namespace dokumentiert ist.

Kein solches enum Element <name> in <class>

Beispiel:

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

QDoc gibt diese Warnung aus, wenn es eine \value-Direktive in einem \enum-Kommentar findet, die einen Wert nennt, der nicht in der Header-Datei zu finden ist, die den Aufzählungstyp dokumentiert hat.

Undokumentiertes enum Element <enum> in <enum list>

Die \value- oder \omitvalue-Einträge von <enum list> enthalten keinen Eintrag für <enum>, der in der Deklaration von <enum list> in der Header-Datei genannt wird.

Fehler bei der Suche nach qhp.<project>.subprojects.<subproject>.indexTitle

QDoc konnte keinen Titel für eine Seite finden, die als Indexseite für <subproject> in der Qt Help Projektkonfiguration festgelegt wurde.

Unterprojekt-Index-Titel müssen für das aktuelle Dokumentationsprojekt lokal sein. Die Verwendung eines Seitentitels aus einem anderen Projekt, das als Abhängigkeit geladen wurde, führt ebenfalls zu dieser Warnung.

Weitere Informationen finden Sie unter Erstellen von Hilfeprojektdateien.

\generatelist <group> ist leer

Nachfolgend ein kurzer Überblick über alle möglichen Argumente für \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist Klassen <Präfix>
• \generatelist classesbymodule <Modulname>
• \generatelist qmltypesbymodul <Modulname>
• \generatelist funktionsindex
• \generatelist legalese
• \generatelist Übersichten
• \generateliste attributionen
• \generatelist verwandt

QDoc gibt diese Warnung aus, wenn Sie \generatelist <group> angeben und die Gruppe keine Elemente enthält, oder wenn Sie \generatelist <group> <pattern> angeben und kein Element in der Gruppe dem Muster entspricht.

\generatelist <group> no such group

Diese Warnung wird ausgegeben, wenn das Argument für \generatelist eine nicht existierende Gruppe ist.

Beispiel:

\generatelist draganddrop

Diese Anweisung erzeugt eine Liste von Klassen oder QML-Typen in der Gruppe draganddrop. Klassen oder QML-Typen werden der draganddrop-Gruppe durch den Befehl \l {ingroup-command}{\ingroup} draganddrop in ihrem Kommentar \class oder \qmltype hinzugefügt.

QDoc gibt diese Warnmeldung aus, wenn keine Entität diese \ingroup draganddrop Anweisung hat.

Fehlendes Bild: <Bilddatei>

Der Suchpfad zum Bild ist falsch, oder die Bilddatei existiert nicht.

Kann nicht mit <Ziel> verknüpft werden

Dies kann eine Vielzahl von Ursachen haben:

• Das Verknüpfungsziel wurde nicht mit einem QDoc-Themenbefehl definiert, z. B. {title-command}{\title} <target>.
• Das <target> enthält einen Tippfehler.
• Das Dokument, das dieses Linkziel enthält, wurde nicht kompiliert.
• Das Dokument, das dieses Linkziel enthält, befindet sich in einem Modul, das nicht im Kompilierungspfad liegt.
• Das Linkziel befindet sich in einem anderen Modul und eine Abhängigkeit zu diesem Modul wurde in der Konfiguration nicht festgelegt oder QDoc konnte die Indexdatei für die Abhängigkeit nicht finden.

QML-Import-Anweisung für Typ <Name> konnte nicht aufgelöst werden

QDoc gibt diese Warnung aus, wenn Sie einen QML-Typ dokumentieren, aber den Befehl \inqmlmodule auslassen. Beispiel:

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

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

Korrekt:

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

\brief-Anweisung endet nicht mit einem Punkt

Das Argument des \brief-Befehls ist ein Satz, der das dokumentierte Thema zusammenfasst, und sollte daher mit einem Punkt enden. Außerdem sollte es kurz sein.

QtDeclarative nicht installiert; kann QML nicht parsen

QDoc gibt diese Warnung aus, wenn es ohne Unterstützung für QML-Parsing kompiliert wurde. Dies sollte nicht passieren, es sei denn, Sie haben eine angepasste Version von QDoc.

Ungültiger regulärer Ausdruck <regex>

Einige QDoc-Befehle verwenden reguläre Ausdrücke als Parameter. QDoc gibt diese Warnung aus, wenn der als Parameter übergebene Text kein gültiger regulärer Ausdruck ist. Dies liegt normalerweise daran, dass er Zeichen mit besonderer Bedeutung in regulären Ausdrücken enthält, die mit einem Escape-Zeichen versehen sein sollten.

Beispiel:

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

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

Ungültiger regulärer Ausdruck:

\printuntil /^})$/

Gültiger regulärer Ausdruck:

\printuntil /^\}\)$/

Der Befehl \printuntil druckt so lange, bis er auf eine Zeile trifft, die nur aus einer geschweiften Klammer gefolgt von einer rechten Klammer besteht. In diesem Fall müssen die geschweifte Klammer und die Klammer mit einem Escapezeichen versehen werden, da sie in regulären Ausdrücken eine besondere Bedeutung haben.

Mehrere Indexdateien für die Abhängigkeit <indexfile>:<depend> gefunden

Verwendung von <indexfile> als Indexdatei für die Abhängigkeit <depend>

Mehrere -indexdir Pfade wurden als Kommandozeilenoptionen an QDoc übergeben, und mehr als einer enthielt eine .index Datei, die zu einer Abhängigkeit passt. QDoc wählt automatisch die Datei mit dem neuesten Zeitstempel aus.

Typischerweise zeigt diese Warnung an, dass noch Artefakte von einem früheren Dokumentations-Build vorhanden sind.

Cannot locate index file for dependency <depend>

Beispiel:

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

Das Dokumentationsprojekt QMake konnte activeqt.index in keinem der angegebenen Indexverzeichnisse finden. In diesem Fall sind die angegebenen Indexverzeichnisse in qmake.qdocconf angegeben.

Abhängige Module wurden angegeben, aber es wurden keine Indexverzeichnisse gesetzt.

QDoc erwartet ein oder mehrere -indexdir Argumente in der Kommandozeile. Ohne diese kann QDoc die Indexdateien von Abhängigkeiten, die mit der Konfigurationsvariable 'depends' definiert wurden, nicht finden.

Überschreibt ein vorheriges Dokument

QDoc gibt diese Warnung aus, wenn es zwei Kommentare findet, die dasselbe Objekt zu beschreiben scheinen. Der Ort des zuvor gesehenen Kommentars wird in den Warnungsdetails angegeben.

Nicht erkannter Listenstil <Name>

\list kann ein optionales Argument annehmen: eine einzelne Zahl oder ein Zeichen, das den Listenstil modifiziert. Siehe die Dokumentation von {list-command}{\list} für weitere Details. Wenn Sie ein Argument verwenden, das nicht erkannt wird, gibt QDoc diese Warnung aus.

QML-Snippet kann nicht analysiert werden: <code> in Zeile <y>, Spalte <x>

QDoc-Kommentare können QML-Code enthalten. Dieser Code kann sich in einem Snippet oder in den QDoc-Kommentaren befinden, die durch \qml und {endqml-command}{\endqml} begrenzt sind.

Beispiel:

Wenn es einen Syntaxfehler im QML-Code gibt, gibt QDoc die Warnung

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

Snippets können auch QML enthalten und auch dort wird der Code geprüft. Fehlt z.B. eine geschweifte Klammer im Code, gibt QDoc die Warnung aus

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

QDoc versagt oft beim Parsen unvollständiger QML-Snippets; in diesen Fällen ist es oft OK, die \qml ... \endqml Befehle durch \code ... \endcode zu ersetzen, um diese Warnung zu unterdrücken.

Befehl <Befehl> am Ende der Datei <Dateiname> fehlgeschlagen

Beispiel:

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

In diesem Fall bedeutet die Warnung, dass der Befehl \snippet kein zweites Label "//! [2]" gefunden hat, um das Ende des Snippets zu markieren. Es könnte auch bedeuten, dass er kein Vorkommen dieses Snippet-Tags in dieser Snippet-Datei gefunden hat.

Ein anderes Beispiel:

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

Mit \skipto + <Muster> wird der Cursor in die nächste Zeile bewegt, die dieses Muster enthält. Wenn \skipto es nicht findet, gibt QDoc diese Warnung aus.

<Datei> konnte nicht zum Schreiben geöffnet werden

Diese Warnung bedeutet eindeutig, dass eine Datei nicht zum Schreiben geöffnet werden kann, wahrscheinlich wegen eines falschen Pfades oder der Schreibberechtigung in einem bestimmten Verzeichnis.

Dieser Seitentitel existiert in mehr als einer Datei

Der Befehl \title setzt den Titel für eine Seite.

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

QDoc gibt diese Warnung aus, wenn ein bestimmter Titel in mehr als einer Seite verwendet wird.

Der Inhalt ist zu lang

QDoc verwendet bei der Tokenisierung von Quelldateien einen Puffer fester Größe. Wenn ein einzelnes Token in der Datei mehr Zeichen als die Höchstgrenze hat, gibt QDoc diese Warnung aus.

Während QDoc mit dem Parsen der Datei fortfährt, wird nur der Teil des Tokens berücksichtigt, der in den Puffer passt, was bedeutet, dass die Ausgabe möglicherweise verstümmelt ist.

Um diese Warnung zu beheben, muss der betreffende Inhalt verkleinert werden, entweder durch Aufteilung, falls möglich, oder durch Entfernen einiger Teile.

Die maximale Anzahl von Zeichen für ein einzelnes Token wird z. B. neben der Warnung angezeigt:

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

Keine Dokumentation für Funktion <Name> im globalen Bereich erzeugt

QDoc war in der Lage, die Dokumentation für eine Funktion <Name> mit ihrer Deklaration abzugleichen, aber es wurde keine Ausgabe erzeugt, weil die Funktion im globalen Namensraum deklariert ist.

Verwenden Sie den Befehl \relates, um die Funktion mit einem dokumentierten Typ, Namespace oder einer Header-Datei zu verknüpfen. Die Funktion wird dann als verwandtes Nichtmitglied auf der zugehörigen Referenzseite aufgeführt.

Dokumentationskonfiguration für <project> definiert kein Hilfeprojekt (qhp)

Eine gültige Qt-Hilfekonfiguration wurde erwartet, aber nicht in der .qdocconf-Datei des Projekts bereitgestellt.

Siehe auch Hilfeprojektdateien erstellen und qhp.

Bereits generierte DATEI für dieses Projekt

Während der Generierung der Dokumentation für ein Projekt, verfolgt QDoc die Dateinamen der generierten Dateien. QDoc gibt eine Warnung aus, wenn es eine Datei zum Schreiben öffnet, von der bekannt ist, dass sie in der aktuellen Ausführung bereits erzeugt wurde. Dies kann passieren, wenn ein \page Kommando denselben Namen verwendet wie \group zum Beispiel.

Sie können die Umgebungsvariable QDOC_ALL_OVERWRITES_ARE_WARNINGS so einstellen, dass sie bei allen derartigen Ereignissen eine Warnung ausgibt. Dies kann beim Aufspüren der fehlerhaften Definitionen nützlich sein.