Fehlerbehebung bei QDoc-Warnungen

QDoc gibt möglicherweise Warnungen aus, wenn es Ihre Dokumentation generiert. In diesem Abschnitt wird beschrieben, was diese Warnungen bedeuten und wie Sie sie beheben können. Dieses Dokument behandelt keine von Clang generierten Warnungen.

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.

<Datei> für dieses Projekt wurde bereits generiert

Bei der Erstellung der Dokumentation für ein Projekt verfolgt QDoc die Dateinamen der von ihm generierten Dateien. QDoc gibt eine Warnung aus, wenn es eine Datei zum Schreiben öffnet und feststellt, dass diese Datei bereits zuvor im Rahmen der aktuellen Ausführung generiert wurde. Dies kann passieren, wenn ein \page Befehl denselben Namen wie \group .

Sie können die Umgebungsvariable ` QDOC_ALL_OVERWRITES_ARE_WARNINGS ` setzen, um bei allen derartigen Ereignissen bedingungslos eine Warnung auszugeben. Dies kann hilfreich sein, um die fehlerhaften Definitionen aufzuspüren.

\brief Anweisung nicht mit einem Punkt endet

Das Argument des Befehls „ \brief “ ist ein Satz, der das dokumentierte Thema zusammenfasst und daher mit einem Punkt enden sollte. Er sollte außerdem kurz sein.

Verlinkung zu <Ziel> nicht möglich

QDoc gibt diese Warnung aus, wenn ein Teil der Dokumentation (in der Warnmeldung angegeben) auf einen anderen Teil verweisen will, diesen anderen Teil – das Ziel des Verweises – jedoch nicht korrekt angibt. Dies kann daran liegen, dass der Verweis darauf falsch eingegeben wurde oder dass sich der Name (bei einer Funktion oder einem Typ) oder der Titel (bei einem anderen Abschnitt) des Ziels geändert hat.

Dies kann verschiedene Ursachen haben:

• Das Linkziel 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.

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

Wenn das Linkziel wie der Name eines Typs oder einer Funktion aussieht, könnte dies auch folgende Ursachen haben:

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

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

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

<name>, der mit \<command> angegeben wurde, kann in keiner Header-Datei gefunden werden

Das bedeutet, dass QDoc in keiner Header-Datei eine Deklaration von <name> finden kann, jedoch einen Kommentar gefunden hat, der angibt, diese zu dokumentieren.

Ein Beispiel:

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

Ein Dokumentationskommentar gibt vor, eine Enumeration zu beschreiben, aber QDoc hat keine Definition dieser Enumeration in einer Header-Datei gefunden.

Dies kann auch folgende Ursachen haben:

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

Projektdatei für Beispiel <name> nicht gefunden

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

Die Snippet-Datei, aus der zitiert werden soll, kann nicht gefunden werden

QDoc gibt diese Warnung aus, wenn es die Datei mit dem Namen eines \snippet oder \quotefromfile Befehl benannt ist.

Einige hilfreiche Schritte zur Behebung dieses Problems:

• Überprüfen Sie, ob der Name der Snippet-Datei korrekt ist. QDoc hängt den Namen der Snippet-Datei an jedes der im Suchpfad angegebenen Verzeichnisse an, um einen Pfadnamen für eine mögliche zu suchende Datei zu erhalten. Dieser Fehler tritt auf, wenn keine dieser möglichen Dateien vorhanden ist.
• Überprüfen Sie den Suchpfad für Snippets, der durch die Konfigurationsvariable „ exampledirs “ in der Datei „ *.qdocconf “ festgelegt ist. Möglicherweise müssen Sie diesem Pfad einen Eintrag hinzufügen oder einen bestehenden Eintrag korrigieren.
• Überprüfen Sie, ob die Snippet-Datei vorhanden ist oder ob sie verschoben, umbenannt oder entfernt wurde – was passieren kann, wenn Änderungen am Quellcode vorgenommen wurden, aus dem QDoc zitieren möchte.

Die QDoc-Include-Datei <Dateiname> kann nicht gefunden werden

QDoc konnte eine in einem Befehl genannte Include-Datei nicht finden. QDoc durchsucht jedes im Suchpfad angegebene Verzeichnis. Befindet sich in keinem dieser Verzeichnisse eine Datei mit diesem Namen oder ist die gefundene Datei nicht lesbar, gibt QDoc diese Warnung aus. Überprüfen Sie, ob die Kombination aus Suchpfad und <Dateiname> korrekt geschrieben ist und ob Sie Leserechte für die Datei haben.

<tag> kann in <file> nicht gefunden werden

Das bedeutet, dass QDoc den Bezeichner <id> in der \include <Datei> oder in der {snippet-command}{\snippet} <Datei> nicht finden.

Indexdatei für Abhängigkeit <depend> kann nicht gefunden werden

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“ festgelegt.

<command>-Befehle können nicht verschachtelt werden

Diese Warnung betrifft Formatierungsbefehle: bold, italic, index, link, span, subscript, superscript, teletype, uicontrol, underline. Ein Formatierungsbefehl darf nicht innerhalb des Textes verwendet werden, auf den er sich bezieht. 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

Dies führt zur QDoc-Warnung „‚\table ‘ kann in ‚\list ‘ nicht verwendet werden“.

Die Datei, aus der zitiert werden soll, kann nicht geöffnet werden: <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), der anweist, Inhalte aus der genannten Datei abzurufen. Dabei werden alle im Suchpfad aufgeführten Verzeichnisse durchsucht. Befindet sich in keinem dieser Verzeichnisse eine Datei mit diesem Namen oder wird die Datei zwar gefunden, ist aber nicht lesbar, gibt QDoc diese Warnung aus. Überprüfen Sie, ob die Kombination aus Suchpfad und <Dateiname> korrekt geschrieben ist und ob Sie Leserechte für die Datei haben.

Diese Dokumentation kann mit nichts verknüpft werden

QDoc hat einen /*! ... */-Kommentar ohne Topic-Befehl gefunden und konnte die unmittelbar auf den Kommentar folgende Deklaration oder Definition nicht mit einer dokumentierten Entität verknüpfen. Dies kann passieren, wenn auf den Kommentar keine Deklaration oder Definition folgt oder wenn die Entität für QDoc nicht sichtbar ist, beispielsweise wenn die Deklaration hinter einer Präprozessorbedingung steht, die QDoc nicht auswertet.

<class> versucht, sich selbst zu erben

Der \inherits Befehl wird verwendet, um zu dokumentieren, dass ein QML-Typ von einem 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

Der Befehl <command> ist am Ende der Datei <filename> fehlgeschlagen

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 in dieser Snippet-Datei kein Vorkommen dieses Snippet-Tags gefunden hat.

Ein weiteres Beispiel:

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

Der \skipto + <Muster> bewegt den Cursor zur nächsten Zeile, die dieses Muster enthält. Wenn „ \skipto “ es nicht findet, gibt QDoc diese Warnung aus.

Befehl <command> ist bei QML-Eigenschaftsbefehlen nicht zulässig

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 bezieht sich speziell auf 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> lautet. Alle anderen Themenbefehle lösen diese Warnung aus.

QML-Importanweisung für den Typ <name> konnte nicht aufgelöst werden

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

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

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

Richtig:

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

Zyklische Typvererbung: <type>

Eine zyklische oder kreisförmige Vererbung liegt vor, wenn ein QML-Typ von einem Basistyp erbt, der selbst vom ursprünglichen Typ erbt. Dies kann zwischen zwei sich gegenseitig erbenden Typen auftreten, oder es können Zwischentypen zwischen ihnen liegen.

Diese Warnung zeigt an, wo ein Zyklus in der Vererbungshierarchie erkannt wurde. Sie sollten den \inherits Befehl für den Typ überprüfen und die Kette der Basistypen zurückverfolgen, bis Sie einen finden, der von einem Typ erbt, auf den Sie zuvor bereits gestoßen sind. Anschließend sollten Sie den Kreislauf durchbrechen, indem Sie den fehlerhaften \inherits Befehl für einen der identifizierten Typen zu korrigieren.

Abhängige Module wurden angegeben, es wurden jedoch keine Indexverzeichnisse festgelegt.

QDoc erwartet ein oder mehrere –indexdir-Argumente auf der Befehlszeile. Ohne diese kann QDoc die Indexdateien der mit der Konfigurationsvariablen „depends“ definierten Abhängigkeiten nicht finden.

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

Eine gültige Qt Help-Konfiguration wurde erwartet, ist jedoch in der .qdocconf-Datei des Projekts nicht vorhanden.

Siehe auch „Erstellen von Hilfsprojektdateien “ und „qhp“.

Doppelte Zielbezeichnung <target>

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

Leeres qdoc-Snippet <tag> in <file>

Der Ausschnitt <tag> wurde in der \snippet <Datei> gefunden, ist jedoch leer.

Funktion beim Parsen von \fn <signature> nicht gefunden

Wenn Clang eine Funktionssignatur nach einem \fn Befehl analysiert, vergleicht er diese mit der Deklaration in der Header-Datei. Stellt Clang Abweichungen fest, gibt er diese Warnmeldung aus.

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

qhp.<project>.subprojects.<subproject>.indexTitle konnte nicht gefunden werden

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

Index-Titel von Unterprojekten müssen lokal zum aktuellen Dokumentationsprojekt gehören. 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 Hilfsprojektdateien“.

<Datei> konnte nicht zum Schreiben geöffnet werden

Diese Warnung bedeutet eindeutig, dass eine Datei nicht zum Schreiben geöffnet werden kann, wahrscheinlich aufgrund eines falschen Pfads oder fehlender Schreibrechte in einem bestimmten Verzeichnis.

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

Wenn QDoc innerhalb eines „\table... \endtable “-Blocks auf einen „\target “-Befehl stößt, dem kein „ \li “-Befehl vorangeht, gibt es diese Warnung aus. Auf die Warnung folgt der Text: „Verschieben Sie den Befehl „ \target “ in den Befehl „ \li “, um diese Warnung zu beheben.“

\generatelist <group> ist leer

Nachfolgend eine kurze Übersicht über alle möglichen Argumente für \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist Klassen <Präfix>
• \generatelist Klassen nach Modul <Modulname>
• \generatelist QML-Typen nach Modul <Modulname>
• \generatelist Funktionsverzeichnis
• \generatelist Rechtshinweise
• \generatelist Übersichten
• \generatelist Quellenangaben
• \generatelist Verwandte Themen

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

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

Beispiel:

\generatelist draganddrop

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

QDoc gibt diese Warnmeldung aus, wenn keine Entität über diese „ \ingroup draganddrop “-Anweisung verfügt.

Enthält keinen „ \inmodule “-Befehl

QDoc gibt diese Warnung aus, wenn die QDoc-Kommentare keine Klasse, keinen Namensraum und keine Header-Datei über den \inmodule Befehl.

Wenn der QDoc-Kommentar eine Entität beschreibt, die kein Mitglied einer anderen Entität ist (typischerweise eines Namespace oder einer Klasse), sollte entweder \relates oder \inmodule verwenden, um sie mit ihrem übergeordneten Kontext zu verknüpfen. Diese Warnung wird ausgegeben, wenn dies nicht der Fall ist.

Ungültiges ` \reimp`; keine dokumentierte virtuelle Funktion für <Befehl>

QDoc versucht, einen Link zu der Funktion zu erstellen, die diese Funktion neu implementiert, konnte das Linkziel jedoch 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 besitzt; dies kann durch eine Umbenennung, eine Änderung der Signatur oder dadurch entstehen, dass die Basisklasse die Methode nicht mehr als virtuell deklariert.

Ungültiger QML-Eigenschaftstyp

Der zur Deklaration einer QML-Eigenschaft verwendete Typ war kein gültiger QML-Werttyp oder QML-Objekttyp oder es handelte sich um einen 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>`.

Ungültiger regulärer Ausdruck <regex>

Einige QDoc-Befehle nehmen reguläre Ausdrücke als Parameter entgegen. QDoc gibt diese Warnung aus, wenn der als solcher Parameter angegebene Text kein gültiger regulärer Ausdruck ist, was in der Regel daran liegt, dass er Zeichen enthält, die in regulären Ausdrücken eine besondere Bedeutung haben und daher mit Escape-Zeichen versehen werden müssten.

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 \printuntil Befehl gibt so lange etwas aus, bis er auf eine Zeile stößt, die nur aus einer rechten geschweiften Klammer gefolgt von einer rechten runden Klammer besteht. In diesem Fall müssen die geschweifte Klammer und die runde Klammer mit Escape-Zeichen versehen werden, da sie in regulären Ausdrücken eine Sonderbedeutung haben.

Ein Makro darf nicht gleichzeitig format-spezifische und qdoc-Syntax-Definitionen enthalten

Ein \macro , das ein Ausgabeformat festlegt, darf keine generische Definition enthalten.

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

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

Das Makro <Befehl> verfügt über keine Standarddefinition

QDoc versucht, ein Makro zu erweitern, und erwartet, dass dieses Makro über eine Standarddefinition verfügt. Einige Makros verfügen möglicherweise nur über formatspezifische Definitionen.

Beispiel:

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

Es gibt jedoch Fälle, in denen die Makroauswertung ein formatunabhängiges Makro erfordert. Beispielsweise können Makros in Abschnittsüberschriften vorkommen, diese müssen jedoch über Standarddefinitionen verfügen.

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

Das angegebene Makro benötigt mehr Parameter, als übergeben wurden. Weitere Details finden Sie in der Definition des Makros in der Konfiguration.

Fehlendes Komma in \sa

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

Fehlender Formatname nach \raw

dem \raw Befehl und dem entsprechenden \endraw Befehl begrenzen einen Block mit Rohcode der Auszeichnungssprache. Dem Befehl „ \raw “ muss der Formatname folgen.

Fehlendes Bild: <Bilddatei>

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

Fehlendes <outer> vor <inner>

Einige Beispiele:

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

Fehlender Eigenschaftstyp für <name>

Bei der Deklaration eines \qmlproperty fehlt der Eigenschaftstyp.

Der Befehl „ \qmlproperty “ erwartet, dass ihm der Eigenschaftstyp folgt, dann der vollqualifizierte Name der Eigenschaft (d. h. der Name, der mit „:-“ an den Namen der Klasse angehängt wird, zu der er gehört).

Falsch:

\qmlproperty MyWidget::count

Richtig:

\qmlproperty int MyWidget::count

Es wurden mehrere Indexdateien für die Abhängigkeit <indexfile>:<depend> gefunden

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

Es wurden mehrere Pfade zu „ -indexdir “ als Befehlszeilenoptionen an QDoc übergeben, und mehr als einer davon enthielt eine „ .index “-Datei, die einer Abhängigkeit entspricht. QDoc wählt automatisch die Datei mit dem neuesten Zeitstempel aus.

In der Regel weist diese Warnung darauf hin, dass noch Build-Artefakte aus einem früheren Dokumentations-Build vorhanden sind.

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

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

Die Warnung enthält die Funktionssignaturen und ihre Quellcode-Speicherorte, um alle konkurrierenden primären Überladungen identifizieren zu können. QDoc ermittelt die tatsächliche primäre Überladung anhand eines lexikografischen Vergleichs (alphabetische Sortierung der Funktionssignaturen) unter den als primär markierten Funktionen.

Um diese Warnung zu beheben, entfernen Sie das Argument „ primary “ aus allen bis auf einen der Befehle „ \overload primary “ in der Überladungsgruppe.

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);

Korrekte Vorgehensweise – nur eine primäre Überladung:

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

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

<name> wurde mehr als einmal dokumentiert

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

Diese Warnung wird beispielsweise angezeigt, wenn eine Funktion einen Dokumentationskommentar vor ihrer Definition sowie einen separaten Kommentar „ \fn “ an einer anderen Stelle enthält.

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

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

Dies lässt sich beheben, indem Sie entweder <namespace> dokumentieren oder – falls dieser bereits in einem anderen Modul dokumentiert ist – sicherstellen, dass dieses Modul eine Abhängigkeit davon hat.

Siehe auch „depends “ und „indexes“.

Namensraum <name> mehr als einmal dokumentiert

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

\nativetype ist nur in \qmltype

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

Keine Dokumentation für <name>

Beispiel:

Warning "No documentation for QNativeInterface."

QDoc erkennt die Deklaration des Namensraums „ QNativeInterface “ in einer Header-Datei, findet jedoch keinen QDoc-Kommentar, in dem dieser Namensraum dokumentiert wurde.

Für die Funktion <name> im globalen Bereich wurde keine Dokumentation generiert

QDoc konnte die Dokumentation für eine Funktion <name> ihrer Deklaration zuordnen, es wurde jedoch keine Ausgabe generiert, da die Funktion im globalen Namensraum deklariert ist.

Verwenden Sie den \relates Befehl, um die Funktion einem dokumentierten Typ, Namensraum oder einer Header-Datei zuzuordnen. Die Funktion wird dann auf der zugehörigen Referenzseite als verwandtes Nicht-Mitglied aufgeführt.

Für <Entität> wurde keine Ausgabe generiert, da <übergeordnetes Element> nicht dokumentiert ist

QDoc gibt diese Warnung aus, wenn es einen Dokumentationskommentar für eine API-Entität wie beispielsweise ein Klassenmitglied analysiert, jedoch keine Ausgabe erzeugen kann, da die zugehörige übergeordnete Klasse nicht dokumentiert ist. Stellen Sie sicher, dass die übergeordnete Klasse dokumentiert ist und dass QDoc so konfiguriert ist, dass es die Quelldatei mit dem Dokumentationskommentar analysiert.

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

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, der einen Wert benennt, der in der Header-Datei, in der der dokumentierte Aufzählungstyp deklariert wurde, nicht vorhanden ist.

Kein solcher Parameter

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

Kein solcher <Typ> in QML <Modul>

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

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

Überschreibt eine vorherige Dokumentation

QDoc gibt diese Warnung aus, wenn es zwei Kommentare findet, die offenbar dieselbe Entität beschreiben. Die Position des zuvor gefundenen Kommentars wird in den Warnungsdetails angegeben.

QML-Eigenschaft mehrfach dokumentiert: <Bezeichner>

QDoc gibt diese Warnung aus, wenn es zwei QDoc-Kommentare findet, die dieselbe QML-Eigenschaft dokumentieren – entweder, weil sie unmittelbar vor deren Definition stehen, oder weil der Befehl \qmlproperty Befehl.

QML-Typ <TypeName> ist mit <ClassName> als nativem Typ dokumentiert. <ClassName> wird durch <OtherClass> ersetzt

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

QtDeclarative nicht installiert; QML kann nicht geparst werden

QDoc gibt diese Warnung aus, wenn es ohne Unterstützung für die QML-Analyse kompiliert wurde. Dies sollte nicht vorkommen, es sei denn, Sie verwenden eine benutzerdefinierte Version von QDoc.

Redundanter Verweis auf sich selbst im Befehl „ \sa “ für <name>

Ein Dokument enthält in den im Befehl \sa Befehl definierten Referenzen.

Dieses Problem tritt häufig auf, wenn es eine Reihe miteinander verbundener Eigenschaften oder Methoden gibt, die aufeinander verweisen, und 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.

Alternativ ist der Link möglicherweise nicht spezifisch genug, damit QDoc ihn auflösen kann, wie in diesem Beispiel:

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

In diesem Fall war möglicherweise beabsichtigt, auf eine Überladung zu verweisen, die ein „ double “-Argument akzeptiert:

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

Der Inhalt ist zu lang

QDoc verwendet beim Tokenisieren von Quelldateien einen Puffer fester Größe. Wenn ein einzelnes Token in der Datei mehr Zeichen enthält als das zulässige Maximum, gibt QDoc diese Warnung aus.

QDoc setzt zwar die Analyse der Datei fort, berücksichtigt jedoch nur den Teil des Tokens, der in den Puffer passt, was bedeutet, dass die Ausgabe möglicherweise verfälscht ist.

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

Die maximale Zeichenanzahl für ein einzelnes Token wird neben der Warnung angezeigt, zum Beispiel:

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

Dieser Seitentitel kommt in mehr als einer Datei vor

Der \title Befehl legt den Titel einer Seite fest.

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

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

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

Wenn ein QDoc-Kommentar keinen Topic-Befehl enthält, weiß QDoc nicht, was der Kommentar dokumentiert, und gibt diese Warnung aus. Sehr ähnlich wie „Diese Dokumentation kann mit nichts verknüpft werden“, jedoch spezifisch für Kommentare, die sich nicht in C++- oder QML-Dateien befinden.

<topic> darf nicht mit anderen „topic“-Befehlen gemischt werden

QDoc erlaubt in bestimmten Anwendungsfällen mehrere „topic“-Befehle in einem einzigen Dokumentationskommentar. Die Verwendung mehrerer „topic“-Befehle aus unterschiedlichen Kategorien führt zur Ausgabe dieser Warnung, und das Thema erzeugt keine Ausgabe.

Der Typ ist sein eigener Basistyp: <type>

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

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

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

Beispiel:

Wenn im QML-Code ein Syntaxfehler vorliegt, gibt QDoc die folgende Warnung aus

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

Snippets können ebenfalls QML enthalten, und auch dort wird der Code überprüft. Fehlt im Code beispielsweise eine geschweifte Klammer, 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 analysieren; in diesen Fällen ist es oft in Ordnung, die Befehle „ \qml … \endqml “ durch „ \code … \endcode “ zu ersetzen, um diese Warnung zu unterdrücken.

Ungleichmäßige Klammern in <text>

Weist auf ein „(“ ohne entsprechendes „)“ hin oder umgekehrt.

Undokumentiertes Enum-Element <enum> in <enum list>

Die <enum-Liste> enthält \value oder \omitvalue Enumerationsliste enthielt keinen Eintrag für <enum>, der in der Deklaration von <enum list> in der Header-Datei genannt wird.

Undokumentierter Parameter

QDoc erfordert, dass in der Dokumentation einer Funktion oder Methode jeder Parameter beschrieben wird. Dies wird dadurch erkannt, dass jeder Parametername (wie an der Stelle angegeben, an der die Funktion oder Methode in einer Header-Datei deklariert ist) nach einem \a Befehl.

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

Undokumentierte Eigenschaft „<name>“

Diese Warnung weist darauf hin, dass eine C++-Klasse eine Deklaration von „ Q_PROPERTY “ enthält, für die keine Dokumentation vorliegt. Eigenschaften sind Teil der öffentlichen API einer Klasse und müssen mithilfe des Befehls „ \property “ dokumentiert werden, um ihren Zweck, ihre gültigen Werte und ihr Verhalten zu beschreiben.

Undokumentiertes QML-<Modul>, auf das von <Typ> oder dessen Mitgliedern verwiesen wird

QDoc gibt diese Warnung aus, wenn es ein QML-Modul anhand des an den Befehl \inqmlmodule oder \qmlproperty Befehle, die mit einem QML -Typ verknüpft sind, nicht finden kann.

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

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.

Unerwartetes <end_command>

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

Unerwartetes \snippet

QDoc gibt diese Warnung aus, wenn es die in einem \snippet Befehl genannten Snippet-Datei nicht finden kann.

Unbekannter Basistyp <name> für den QML-Typ <type>

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

Unbekannter Befehl <name>

Wenn ein QDoc-Kommentar einen Backslash gefolgt von einem Token verwendet, das kein integrierter QDoc-Befehl ist und nicht als benutzerdefiniertes Befehlsmakro definiert wurde, gibt QDoc diese Warnung aus. Überprüfen Sie die Schreibweise des Befehlsnamens und prüfen Sie, ob Ihre QDoc-Konfiguration nicht das enthält, was ihn definiert hätte, falls es sich um einen benutzerdefinierten Befehl handelt.

Dies kann auch dadurch verursacht werden, dass Code im QDoc-Kommentar in Anführungszeichen steht; beispielsweise könnte der Autor auf das C-Zeichen für das Ende einer Zeichenkette '\0' oder eine der anderen C-Zeichenfolgen-Escape-Sequenzen wie '\n' verwiesen haben, ohne den Backslash zu escapen. Escapen Sie den Backslash als \, um einen literalen Backslash in die Dokumentation einzufügen, oder umschließen Sie das Codefragment mit \c{...}, wodurch die Interpretation von Backslashes als Einleitung von QDoc-Befehlen unterdrückt wird.

Unbekanntes Makro

QDoc gibt diese Warnung aus, wenn es einen Backslash, \, gefolgt von einem Token erkennt, das es weder als Namen eines integrierten Befehls noch als benutzerdefiniertes Makro erkennt. Wenn Sie Code zitieren, der Zeichen-Escape-Sequenzen enthält, sollten Sie den Code in \c{...} einschließen, um diese Warnung bezüglich der Escape-Sequenzen zu vermeiden.

Unbekannter QML-Modul-/Typqualifizierer für <Bezeichner>

Ein an \qmlproperty oder \qmlmethod übergeben wird, enthält eine Kombination aus qmlModule::qmlType::Bezeichner, die nirgendwo definiert ist.

Beispiel:

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

DragHandler verfügt nicht über eine Eigenschaft namens „DragAxis“.

Unbekannter Listenstil <name>

\listkann ein optionales Argument annehmen: eine einzelne Zahl oder ein Zeichen, das den Listenstil modifiziert. Weitere Details finden Sie in der Dokumentation zu {list-command}{\list}. Wenn Sie ein Argument verwenden, das nicht erkannt wird, gibt QDoc diese Warnung aus.

Unbekannte Markup-Sprache

Diese Warnung tritt auf, wenn für einen \code -Befehl eine Programmiersprache angegeben wird, die QDoc nicht erkennt. Diesem QML-Codeblock wurde beispielsweise die ungültige Sprache „QL“ zugewiesen:

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