Fehlersuche bei QDoc-Warnungen

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 in der Dokumentation verwendet wird, stimmt nicht mit dem in der Deklaration verwendeten Namen überein.
• Das Linkziel wurde als \internal markiert war, während der Linktext 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 Blocks vorausgeht, gibt es diese Warnung aus. Der Warnung folgt der Text Verschieben Sie den \target innerhalb des \li, um diese Warnung zu beheben.

Kann keine Snippets-Datei zum Zitieren finden

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

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 Kandidatendatei zu erhalten, nach der gesucht werden soll. 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 versucht zu zitieren.

Unerwartet \snippet

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

Undokumentiertes QML <Modul> referenziert von <Typ> oder seinen Mitgliedern

QDoc gibt diese Warnung aus, wenn es nicht in der Lage ist, ein QML-Modul zu finden, das auf dem Bezeichner basiert, der dem Befehl \inqmlmodule oder \qmlproperty Befehlen übergebenen Bezeichners, der mit einem QML-Typ verbunden ist.

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, aber das zugehörige \qmltype nicht zu diesem Modul gehört.

Der QML-Modulbezeichner, falls definiert, muss mit dem \inqmlmodule Argument in der QML-Typ-Dokumentation übereinstimmen. In den meisten Fällen ist QDoc in der Lage, den QML-Typ auch ohne 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. Es erkennt dies daran, dass jeder Parametername (wie in der Deklaration der Funktion oder Methode in einer Header-Datei angegeben) nach einem \a Befehl.

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 Parametername, der nach einem \a Kommando angegebene Parametername mit keinem 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 nicht gefunden werden \fn <Signatur>

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.

Keine Ausgabe für <entity> erzeugt, weil <parent> undokumentiert ist

QDoc gibt diese Warnung aus, wenn ein Dokumentationskommentar für eine API-Entität, wie z.B. ein Klassenmitglied, analysiert wird, aber keine Ausgabe erzeugt werden kann, weil das zugehörige Elternteil (Klasse) nicht dokumentiert ist. Stellen Sie sicher, dass das übergeordnete Element dokumentiert ist und dass QDoc so konfiguriert ist, dass es die Quelldatei analysiert, die den Dokumentationskommentar enthält.

Wenn das dokumentierte Member zu einer Klasse gehört, die nicht dokumentiert werden soll, markieren Sie die Klasse als \internal oder verwenden Sie den \dontdocument Befehl.

QML-Typ <Typname> dokumentiert mit <Klassenname> als nativer 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 kein Topic-Kommando (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.

<topic> kann nicht mit anderen topic-Befehlen gemischt werden

QDoc erlaubt für bestimmte Anwendungsfälle mehrere Themenbefehle in einem einzigen Dokumentationskommentar. Die Verwendung mehrerer Themenbefehle aus verschiedenen Kategorien führt zu dieser Warnung, und das Thema erzeugt keine Ausgabe.

Namespace <Name> mehr als einmal dokumentiert

Diese Warnung bedeutet, dass ein Dokumentationssatz zwei Kommentare enthält, die \namespace Befehle mit demselben Argument, <Name>, enthält.

<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 behoben werden, indem entweder <Namensraum> dokumentiert wird , oder, falls er bereits in einem anderen Modul dokumentiert ist, sichergestellt wird, dass dieses Modul eine Abhängigkeit dazu hat.

Siehe auch Abhängigkeiten und Indizes.

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

Wenn der QDoc-Kommentar eine Entität beschreibt, die nicht Mitglied einer anderen Entität ist (typischerweise ein Namespace oder eine Klasse), sollte er entweder \relates oder \inmodule verwenden, um es mit seinem 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-Qualifier für <identifier>

Ein Parameter, der an \qmlproperty oder \qmlmethod übergebene 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 Eine Eigenschaft namens DragAxis gibt es nicht.

Fehlender Eigenschaftstyp für <Name>

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

Der Befehl \qmlproperty erwartet den Typ der Eigenschaft, dann den vollqualifizierten Namen der Eigenschaft (d.h. den Namen ::-joined nach dem Namen der Klasse, zu der sie gehört).

Falsch:

\qmlproperty MyWidget::count

Korrekt:

\qmlproperty int MyWidget::count

Undokumentierte Eigenschaft '<Name>'

Diese Warnung zeigt an, dass eine C++-Klasse eine Q_PROPERTY Deklaration hat, die nicht dokumentiert ist. Eigenschaften sind Teil der öffentlichen API einer Klasse und erfordern eine Dokumentation mit dem \property Befehl, um ihren Zweck, ihre gültigen Werte und ihr Verhalten zu beschreiben.

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 der Definition erscheinen, oder indem sie den \qmlproperty Befehl.

Befehl <Befehl> 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> kann nicht gefunden werden

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 <Befehl>

Qdoc versucht, einen Link zu der Funktion zu erstellen, die diese neu implementiert, konnte aber das Link-Ziel 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.

Mehrere primäre Überladungsdefinitionen für <Funktion>

QDoc gibt diese Warnung aus, wenn mehrere Funktionen mit demselben Namen mit \overload primary gekennzeichnet sind. Es sollte nur eine Funktion in einer Überladungsgruppe als primäre Überladung bezeichnet werden.

Die Warnung enthält die Funktionssignaturen und ihre Quellorte, um alle konkurrierenden primären Überladungen zu identifizieren. QDoc bestimmt die tatsächliche primäre Überladung durch lexikographischen Vergleich (alphabetische Reihenfolge der Funktionssignaturen) zwischen den als primär gekennzeichneten Funktionen.

Um diese Warnung zu beheben, entfernen Sie das Argument primary aus allen \overload primary Befehlen in der Überladungsgruppe außer einem.

Beispiel, das diese Warnung auslöst:

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

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

Korrekter Ansatz - nur ein primärer:

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

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

<Klasse> versucht, sich selbst zu erben

Der \inherits Befehl wird verwendet, um zu dokumentieren, dass ein QMl-Typ einen anderen QML-Typ erbt. Diese Warnung wird ausgegeben, wenn dieser andere QML-Typ mit dem dokumentierten QML-Typ identisch ist.

Beispiel:

\qmltype Foo
\inherits Foo

\nativetype ist nur erlaubt in \qmltype

Der \nativetype Befehl 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 in einem Befehl genannte Datei nicht finden (z.B. \quotefromfile, \snippet, \include) genannten Datei zu finden, die den Inhalt der genannten Datei abrufen soll. Es durchsucht jedes im Suchpfad genannte Verzeichnis. Wenn es in einem dieser Verzeichnisse keine Datei mit diesem Namen 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 Befehl und der entsprechende \endraw Befehl begrenzen einen Block mit rohem Auszeichnungssprachencode. Auf den Befehl \raw muss der Formatname folgen.

Makro kann nicht sowohl formatspezifische als auch qdoc-Syntax-Definitionen haben

A \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 in QDoc eingebautes 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 die \target oder dem \keyword Befehl. Der Zielname, der als Parameter für diese Befehle angegeben wird, muss eindeutig sein. Die Warnung wird gefolgt von "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 der \include <Datei> oder {Snippet-Befehl}{\snippet} <Datei> nicht finden.

Leeres qdoc-Snippet <tag> in <Datei>

Das Snippet <tag> wurde gefunden in der \snippet <Datei> 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

Ergibt die QDoc-Warnung "Can't use '\table' in '\list'".

Fehlendes <outer> vor <inner>

Einige Beispiele:

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

Unerwartetes <Ende_Befehl>

Diese Warnung wird ausgegeben, wenn Sie z.B. einen \endlist ohne vorangehenden \list. Sie gilt für alle Befehle, die in Paaren auftreten (z. B. startFoo/endFoo).

Fehlendes Komma in \sa

Die Titel, 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 eine Direktive 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>

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

Fehler beim Finden von 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 <Gruppe> ist leer

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

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist Klassen <Präfix>
• \generatelist klassenbymodul <Modulname>
• \generatelist qmltypesbymodul <Modulname>
• \generatelist Funktionsindex
• \generatelist Rechtssprache
• \generatelist Übersichten
• \generatelist Zuschreibungen
• \generatelist verwandte

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 <Gruppe> keine solche Gruppe

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 ihren \class oder \qmltype Kommentar.

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

Fehlendes Bild: <imagefile>

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 Link-Ziel wurde nicht mit einem QDoc topic-Befehl 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 Link-Ziel 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 das \inqmlmodule Anweisung aus. 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 statement does not end with a full stop

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 das Parsen von QML 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.

Unbekannter Listenstil <Name>

\listkann ein optionales Argument annehmen: eine einzelne Zahl oder ein Zeichen, das den Listenstil ändert. Weitere Einzelheiten finden Sie in der Dokumentation zu {list-command}{\list}. 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}.

Beispiel:

Wenn ein Syntaxfehler im QML-Code vorliegt, 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 kann unvollständige QML-Snippets oft nicht parsen; in diesen Fällen ist es oft OK, die Befehle \qml... \endqml durch \code... \endcode zu ersetzen, um diese Warnung zu unterdrücken.

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

Beispiel:

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

In diesem Fall bedeutet die Warnung, dass der \snippet Befehl 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".

Das \skipto + <Muster> setzt den Cursor auf die nächste Zeile, 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 einer falschen Schreibberechtigung in einem bestimmten Verzeichnis.

Dieser Seitentitel existiert in mehr als einer Datei

Der Befehl \title Befehl 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 \relates Befehl, 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 <Projekt> 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 betreffenden Definitionen hilfreich sein.

Ungültiger QML-Eigenschaftstyp

Der Typ, der zur Deklaration einer QML-Eigenschaft verwendet wurde, war kein gültiger QML-Werttyp oder QML-Objekttyp, oder es war ein C++- oder Qt-Typ.

Diese Warnung tritt typischerweise auf, wenn Entwickler auf den zugrunde liegenden Qt-Typ verweisen, der zur Implementierung eines QML-Typs verwendet wird, z. B. QStringList anstelle von list<string>.

Typ ist sein eigener Basistyp: <Typ>

Der QML-Typ wurde fälschlicherweise als sein eigener Basistyp definiert, möglicherweise unter Verwendung des \inherits Befehl.

Zyklische Typvererbung: <type>

Zyklische oder zirkuläre Vererbung tritt auf, wenn ein QML-Typ von einem Basistyp erbt, der wiederum vom ursprünglichen Typ erbt. Dies kann zwischen zwei sich gegenseitig vererbenden Typen auftreten, oder es können Zwischentypen dazwischen liegen.

Diese Warnung zeigt an, wo ein Zyklus in der Vererbungshierarchie entdeckt wurde. Sie sollten sich den \inherits Befehl für den Typ untersuchen und der Spur der Basistypen folgen, bis ein Typ gefunden wird, der von einem Typ erbt, dem Sie zuvor begegnet sind. Dann sollten Sie den Zyklus unterbrechen, indem Sie den falschen \inherits Befehl für einen der identifizierten Typen korrigieren.

Redundanter Link zu self im \sa Befehl für <Name>

Ein Teil der Dokumentation enthält einen Verweis auf sich selbst in den Referenzen, die in seinem \sa Befehl.

Dieses Problem tritt in der Regel auf, wenn es eine Sammlung von verwandten Eigenschaften oder Methoden gibt, die aufeinander verweisen, und wenn die \sa Befehle zwischen ihnen kopiert wurden, wie in diesem Beispiel:

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

Es ist sinnvoll, den selbstreferenzierenden Link durch einen Link zu einer anderen verwandten Eigenschaft oder Methode zu ersetzen.

Es kann aber auch sein, dass der Link für QDoc nicht spezifisch genug ist, um ihn aufzulösen, wie in diesem Beispiel:

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

In diesem Fall könnte die Absicht darin bestanden haben, auf eine Überladung zu verweisen, die ein double Argument akzeptiert:

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

Unbekannte Basis <Name> für QML-Typ <Typ>

Der Typname, der als Basistyp für einen QML-Typ deklariert wurde, wurde nicht gefunden, oder er wurde nicht mit dem \inherits Befehl deklariert.

Unbekannte Auszeichnungssprache

Diese Warnung tritt auf, wenn für einen \code Befehl eine Programmiersprache angegeben wird, die QDoc nicht kennt. Zum Beispiel wurde diesem QML-Codeblock die ungültige Sprache "QL" zugewiesen:

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