Allgemeine Konfigurationsvariablen

Mit den allgemeinen QDoc-Konfigurationsvariablen können Sie festlegen, wo QDoc die verschiedenen Quelldateien findet, die es zur Erstellung der Dokumentation benötigt, sowie das Verzeichnis, in dem die generierte Dokumentation abgelegt werden soll. Außerdem können Sie einige kleinere Anpassungen an QDoc selbst vornehmen und so dessen Ausgabe sowie das Verarbeitungsverhalten steuern.

codeindent

Die Variable „ codeindent “ legt die Einrückungstiefe fest, die QDoc beim Schreiben von Codeausschnitten verwendet.

Ursprünglich verwendete QDoc einen fest programmierten Wert von vier Leerzeichen für die Code-Einrückung, um sicherzustellen, dass sich Codeausschnitte leicht vom umgebenden Text unterscheiden lassen. Da wir Stylesheets verwenden können, um das Erscheinungsbild bestimmter Arten von HTML-Elementen anzupassen, ist diese Einrückungstiefe nicht immer erforderlich.

Programmiersprachen

Die Variable „ codelanguages “ gibt eine Liste von Quellsprachen an, die von QDoc nicht erkannt werden, aber innerhalb von „ \code “ ... „ \endcode “-Blöcken verwendet werden können. Dies ermöglicht es, Code-Blöcke in Sprachen zu schreiben, die QDoc nicht analysieren kann, und HTML zu generieren, das von anderen Tools hervorgehoben oder verarbeitet werden kann.

codelanguages = Python Rust Java Swift "C#"

Da QDoc C++ (Cpp), QML und Text verarbeiten kann, müssen diese Sprachen in dieser Liste nicht angegeben werden. Sprachnamen, die Sonderzeichen enthalten, wie z. B. C#, müssen in dieser Liste in doppelte Anführungszeichen gesetzt werden.

Die Variable „ codelanguages “ wurde in QDoc 6.11 eingeführt, um in der Online-Qt-Dokumentation die Syntaxhervorhebung für eine Teilmenge der von highlight.js unterstützten Sprachen zu ermöglichen.

Siehe auch \code.

codeprefix, codesuffix

Die Variablen „ codeprefix “ und „ codesuffix “ geben ein Zeichenfolgenpaar an, in das jedes Code-Snippet eingeschlossen wird.

definiert

Die Variable „ defines “ gibt die C++-Präprozessorsymbole an, die QDoc erkennt und auf die es reagiert.

Wenn ein Präprozessorsymbol über die Variable „ defines “ festgelegt wird, können Sie auch den \if Befehl verwenden, um Dokumentation einzufügen, die nur dann eingebunden wird, wenn das Präprozessorsymbol definiert ist.

defines = QT_GUI_LIB

Dadurch wird sichergestellt, dass QDoc den Code verarbeitet, für den die Definition dieser Symbole erforderlich ist. Beispiel:

#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endif

Sie können Präprozessorsymbole auch manuell über die Befehlszeile mit der Option -D definieren. Beispiel:

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

In diesem Fall sorgt die Option -D dafür, dass das Präprozessorsymbol „ qtforpython “ definiert ist, wenn QDoc die in der Datei „qtgui.qdocconf“ definierten Quelldateien verarbeitet.

Siehe auch „Falschangaben“ und \if.

abhängig von

Die Variable „ depends “ definiert eine Liste anderer Dokumentationsprojekte, von denen dieses Projekt abhängt, um Verknüpfungsziele für die Typvererbung und alles andere, worauf die Dokumentation verweisen muss, aufzulösen.

Genau wie Qt selbst ist auch die Dokumentation zu Qt auf mehrere Module verteilt. In einem aus mehreren Modulen bestehenden Dokumentationsprojekt besteht der Mindestumfang an Abhängigkeiten für ein einzelnes Modul aus den eigentlichen Build-Abhängigkeiten. Wenn es darüber hinaus ein Dokumentationsprojekt (Modul) gibt, das als Einstiegspunkt auf oberster Ebene für den gesamten Dokumentationsumfang dient und Navigationslinks bereitstellt, sollte die Dokumentation jedes Moduls dieses als Abhängigkeit einbeziehen.

Wenn QDoc Dokumentation für ein Projekt generiert, erstellt es außerdem eine „ .index “-Datei, die URLs zu allen verlinkbaren Elementen im Projekt enthält. Jede Abhängigkeit ist der Name (in Kleinbuchstaben) eines Projekts. Dieser Name muss mit dem Basisnamen der für dieses Projekt generierten Indexdatei übereinstimmen.

depends = \
    qtdoc \
    qtcore \
    qtquick

Beim Aufruf von QDoc für ein Projekt, das Abhängigkeiten aufweist und die Variable ` depends ` verwendet, müssen ein oder mehrere Pfade vom Typ ` --indexdir ` als Befehlszeilenoptionen übergeben werden. QDoc verwendet diese Pfade, um nach den Indexdateien der Abhängigkeiten zu suchen.

qdoc mydoc.qdocconf --outputdir $PWD/html --indexdir $QT_INSTALL_DOCS

In diesem Fall sucht QDoc nach einer Datei „ $QT_INSTALL_DOCS/qtdoc/qtdoc.index “ für eine Abhängigkeit zu „ qtdoc “. Wird keine Indexdatei für eine Abhängigkeit gefunden, gibt QDoc eine Warnung aus.

Der Befehl „ depends “ akzeptiert auch den Sonderwert „*“. Dadurch wird QDoc angewiesen, alle in den angegebenen Indexverzeichnissen gefundenen Indexdateien zu laden; das heißt, „von allem abhängig“.

depends = *

Siehe auch „indexes“, „project“ und „url“.

documentationinheaders

Setzen Sie „ documentationinheaders = true “, um QDoc anzuweisen, bei der Erstellung der Dokumentation für C++-basierte Projekte auch Dokumentationskommentare in Header-Dateien zu analysieren.

Diese Funktion wurde mit Qt 6.9 in QDoc eingeführt.

exampledirs

Die Variable „ exampledirs “ gibt die Verzeichnisse an, die den Quellcode der Beispieldateien enthalten.

Die Variablen „examples“ und „exampledirs“ werden von der \quotefromfile, \quotefile und \example Befehle verwendet. Sind sowohl die Variable „examples“ als auch die Variable „exampledirs“ definiert, durchsucht QDoc beide Verzeichnisse, zunächst „examples “ und anschließend „exampledirs“.

QDoc durchsucht die Verzeichnisse in der angegebenen Reihenfolge und akzeptiert die erste übereinstimmende Datei, die es findet. Es durchsucht nur die angegebenen Verzeichnisse, nicht deren Unterverzeichnisse.

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

Bei der Verarbeitung

\quotefromfile widgets/calculator/calculator.cpp

prüft QDoc, ob eine Datei namens „ calculator.cpp “ als Wert in der examples Variable aufgeführt ist. Ist dies nicht der Fall, durchsucht es die Variable „ exampledirs “ und prüft zunächst, ob eine Datei mit dem Namen

$QTDIR/doc/src/widgets/calculator/calculator.cpp

Ist dies nicht der Fall, sucht QDoc weiter nach einer Datei namens

$QTDIR/examples/widgets/calculator/calculator.cpp

und so weiter.

Siehe auch die Beispiele.

Beispiele

Mit der Variablen „ examples “ können Sie zusätzlich zu den Dateien, die sich in den durch die Variable exampledirs Variable angegebenen Verzeichnissen.

Die Variablen „ examples “ und exampledirs Variablen werden von der \quotefromfile, \quotefile und \example Befehlen verwendet. Sind sowohl die Variable „ examples “ als auch die exampledirs definiert sind, durchsucht QDoc beide, zuerst „ examples “, dann exampledirs.

QDoc durchsucht die für die Variable „ examples “ aufgeführten Werte in der angegebenen Reihenfolge und akzeptiert den ersten gefundenen Wert.

Ein ausführliches Beispiel finden Sie im exampledirs Befehl. Beachten Sie jedoch: Wenn Sie wissen, dass die Datei in der Variablen ` examples ` aufgeführt ist, müssen Sie ihren Pfad nicht angeben:

\quotefromfile calculator.cpp

Siehe auch exampledirs.

examplesinstallpath

Die Variable „ examplesinstallpath “ legt den Stammpfad für die Beispiele dieses Projekts im installierten Beispielverzeichnis fest.

Angenommen, der Stamminstallationspfad für alle Beispiele lautet „ QT_INSTALL_EXAMPLES “, dann lautet der Pfad

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

wird verwendet, um auf den Pfad eines einzelnen Beispiels innerhalb dieses Dokumentationsprojekts zu verweisen. Diese Pfade sind in der Beispiel-Manifestdatei gespeichert, die von Qt Creator gelesen wird.

Um korrekte Pfade zu gewährleisten, muss examplesinstallpath mit einem der in exampledirs aufgeführten Verzeichnisse übereinstimmen. Der als Argument für jeden \example Befehls ist relativ zum Pfad in ` exampledirs`.

Beispiel:

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

Angenommen, es gibt folgenden Befehl „ \example “:

/*!
    \example basic/hello
    ...
*/

Dann wird der Pfad „ mymodule/basic/hello “ in der Manifestdatei für dieses Beispiel gespeichert.

Siehe auch: exampledirs, \exampleund \meta.

Beispiele.Dateierweiterungen

Die Variable „ examples.fileextensions “ gibt die Dateiendungen an, nach denen QDoc sucht, wenn es Beispieldateien für die Anzeige in der Dokumentation sammelt.

Die Standarderweiterungen sind *.cpp, *.h, *.js, *.xq, *.svg, *.xml und *.ui.

Die Dateiendungen werden als Standard-Platzhalterausdrücke angegeben. Mit „+=“ können Sie dem Filter eine Dateiendung hinzufügen. Beispiel:

examples.fileextensions += *.qrc

Siehe auch headers.fileextensions.

examples.warnaboutmissingimages

Bei der Verarbeitung der Beispieldokumentation gibt QDoc möglicherweise Warnungen aus, wenn ein Beispiel keine Bilder enthält. Diese Warnung kann deaktiviert werden, indem die folgende Konfigurationsvariable in der Datei .qdocconf des Projekts gesetzt wird:

examples.warnaboutmissingimages = false

Diese Konfigurationsvariable wurde mit Qt 6.9 in QDoc eingeführt.

Siehe auch examples.warnaboutmissingprojectfiles.

examples.warnaboutmissingprojectfiles

Bei der Verarbeitung der Beispieldokumentation gibt QDoc möglicherweise Warnungen aus, wenn ein Beispiel keine Projektdatei enthält. Diese Warnung kann deaktiviert werden, indem die folgende Konfigurationsvariable in der Datei .qdocconf des Projekts gesetzt wird:

examples.warnaboutmissingprojectfiles = false

Diese Konfigurationsvariable wurde mit Qt 6.9 in QDoc eingeführt.

Siehe auch examples.warnaboutmissingimages.

excludedirs

Die Variable „ excludedirs “ dient dazu, Verzeichnisse aufzulisten, die von QDoc nicht verarbeitet werden sollen, selbst wenn dieselben Verzeichnisse in den Variablen „sourcedirs“ oder „headerdirs“ enthalten sind.

Beispiel:

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

Bei der Ausführung schließt QDoc die aufgeführten Verzeichnisse von der weiteren Verarbeitung aus. Dateien in diesen Verzeichnissen werden von QDoc nicht gelesen.

Siehe auch excludefiles.

excludefiles

Mit der Variablen „ excludefiles “ können Sie einzelne Dateien angeben, die von QDoc nicht verarbeitet werden sollen.

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

Wenn Sie den obigen Eintrag in Ihre `qdocconf`-Datei für `qtbase` aufnehmen, wird für ` QWidget` keine Klassendokumentation generiert.

Seit Qt 5.6 werden von ` excludefiles` auch einfache Platzhalter („*“ und „?“) erkannt. Um beispielsweise alle privaten Qt-Header-Dateien von der Analyse auszuschließen, definieren Sie Folgendes:

excludefiles += "*_p.h"

Siehe auch excludedirs.

extraimages

Die Variable „ extraimages “ weist QDoc an, bestimmte Bilder in die generierte Dokumentation einzubinden.

QDoc kopiert automatisch eine Bilddatei aus dem Verzeichnis „imagedirs“ in das Ausgabeverzeichnis, wenn sie von der \image oder \inlineimage Befehl referenziert wird. Wenn Sie weitere Bilder kopieren möchten, müssen Sie diese mithilfe der Variablen ` extraimages ` angeben.

Die allgemeine Syntax lautet format.extraimages = image.

Beispiel:

HTML.extraimages = images/qt-logo.png

Siehe auch „images “ und „imagedirs“.

Unwahrheiten

Die Variable „ falsehoods “ legt den Wahrheitswert bestimmter Präprozessorsymbole als „false“ fest.

Die Werte der Variablen sind reguläre Ausdrücke (Einzelheiten finden Sie unter „ QRegularExpression “). Ist diese Variable für ein Präprozessorsymbol nicht gesetzt, geht QDoc davon aus, dass dessen Wahrheitswert „true“ ist. Eine Ausnahme bildet „0“, das immer „false“ ist.

QDoc erkennt die folgende Präprozessorsyntax und kann sie auswerten:

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

Bei unbekannter Syntax wie

#if NOTYET
    ...
#endif

wird QDoc diese standardmäßig als „true“ auswerten, es sei denn, das Präprozessorsymbol ist im Eintrag der Variablen „ falsehoods “ angegeben:

falsehoods = NOTYET

Siehe auch „defines“.

generateindex

Die Variable „ generateindex “ enthält einen booleschen Wert, der angibt, ob bei der Erstellung der HTML-Dokumentation eine Indexdatei generiert werden soll.

Standardmäßig wird bei der Erstellung der HTML-Dokumentation immer eine Indexdatei generiert. Daher wird diese Variable in der Regel nur verwendet, um diese Funktion zu deaktivieren (durch Setzen des Werts auf „ false “) oder um die Indexgenerierung für die WebXML-Ausgabe zu aktivieren (durch Setzen des Werts auf „ true “).

headerdirs

Die Variable „ headerdirs “ gibt die Verzeichnisse an, die die Header-Dateien enthalten, die zu den in der Dokumentation verwendeten „ .cpp “-Quelldateien gehören.

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

Bei der Ausführung liest QDoc als Erstes die in der headers Variable sowie diejenigen, die sich in den durch die Variable ` headerdir ` angegebenen Verzeichnissen (einschließlich aller Unterverzeichnisse) befinden, und erstellt so eine interne Struktur der Klassen und ihrer Funktionen.

Anschließend liest es die in der sourcessowie die in den in der sourcedirs Variable angegeben sind (einschließlich aller Unterverzeichnisse), und führt dabei eine Zusammenführung der Dokumentation mit der Struktur durch, die es aus den Header-Dateien extrahiert hat.

Sind sowohl die Variablen ` headers ` als auch ` headerdirs ` definiert, liest QDoc beide durch, zunächst headers dann „ headerdirs “.

fileextensions In den angegebenen Verzeichnissen liest QDoc nur die Dateien mit der in der headers.fileextensions Variablen angegeben ist. Die durch headers werden ohne Berücksichtigung ihrer Dateiendungen gelesen.

Siehe auch headers und headers.fileextensions.

headers

Mit der Variablen „ headers “ können Sie zusätzlich zu den Header-Dateien, die sich in den durch die Variable headerdirs Variable angegebenen Verzeichnissen.

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

Bei der Verarbeitung der Variablen „ headers “ verhält sich QDoc genauso wie bei der Verarbeitung der headerdirs Variable. Weitere Informationen finden Sie unter der headerdirs Variable.

Siehe auch „headerdirs“.

headers.fileextensions

Die Variable „ headers.fileextensions “ legt die von den Headern verwendete Dateiendung fest.

Bei der Verarbeitung der in der headerdirs Variablen angegebenen Header-Dateien liest QDoc nur die Dateien mit den in der Variablen „ headers.fileextensions “ angegebenen Dateiendungen. Auf diese Weise vermeidet QDoc den Zeitaufwand für das Einlesen irrelevanter Dateien.

Die Standarderweiterungen sind *.ch, *.h, *.h++, *.hh, *.hpp und *.hxx.

Die Dateiendungen werden als Standard-Platzhalterausdrücke angegeben. Mit „+=“ können Sie dem Filter eine Dateiendung hinzufügen. Zum Beispiel:

header.fileextensions += *.H

Siehe auch headerdirs.

includepaths

Die Variable „ includepaths “ dient dazu, dem Clang-Parser zusätzliche Include-Pfade zu übergeben, die QDoc zum Parsen von C++-Code für Dokumentationskommentare verwendet.

Die Variable akzeptiert eine Liste von Pfaden, denen entweder „ -I “ (Include-Pfad), „ -F “ (macOS-Framework-Include-Pfad) oder „ -isystem “ (System-Include-Pfad) vorangestellt ist. Wird kein Präfix angegeben, wird standardmäßig „ -I “ verwendet.

Pfade, die relativ zur aktuellen .qdocconf-Datei sind, werden in absolute Pfade umgewandelt. Pfade, die im Dateisystem nicht vorhanden sind, werden ignoriert.

Siehe auch moduleheader.

includeprivate

Verwenden Sie „ includeprivate “, um private C++-Klassenmitglieder in Ihre Dokumentation aufzunehmen. QDoc schließt private Funktionen, Typen und Variablen normalerweise aus der generierten Dokumentation aus.

Um alle privaten Mitglieder einzubeziehen, setzen Sie „ includeprivate “ auf „ true “:

includeprivate = true

Sie können auch bestimmte Mitgliedstypen aktivieren:

# Include only private functions
includeprivate.functions = true

# Include only private types (classes, enums, typedefs)
includeprivate.types = true

# Include only private variables
includeprivate.variables = true

Spezifische Einstellungen haben Vorrang vor der globalen Einstellung. Zum Beispiel:

includeprivate = true
includeprivate.types = false

Diese Konfiguration umfasst private Funktionen und Variablen, schließt jedoch private Typen aus.

QDoc hat in Qt 6.11 die Funktion „ includeprivate “ eingeführt.

internalfilepatterns

Die Variable „ internalfilepatterns “ legt Dateipfadmuster fest, die interne Implementierungsdateien identifizieren. Klassen, die in Dateien deklariert sind, die diesen Mustern entsprechen, werden automatisch als „Internal“ markiert, ebenso wie alle ihre Mitglieder (Eigenschaften, Funktionen, Aufzählungen, verschachtelte Typen). Freie Funktionen, Aufzählungen und Typdefinitionen im Dateibereich sind von dieser Einstellung nicht betroffen.

Wenn „showinternal“ auf „ false “ gesetzt ist (Standardeinstellung), werden diese Elemente von der Dokumentationsvalidierung ausgeschlossen. Wenn „ showinternal “ auf „ true “ gesetzt ist, werden sie in die Dokumentation aufgenommen, behalten jedoch ihren Status „Internal“ bei, sodass Generatoren sie anders gestalten können (z. B. durch Hinzufügen visueller Kennzeichnungen für interne APIs).

Dies ist nützlich für private Implementierungs-Header, die Klassen enthalten, die nicht Teil der dokumentierten öffentlichen Schnittstelle sind. In Qt gehören dazu private Header, die auf „ _p.h “ enden.

Syntax des Musters

Die Muster unterstützen zwei Syntaxen:

• Glob-Muster im Shell-Stil: Einfache Platzhalter, bei denen „ * “ beliebige Zeichen und „ ? “ genau ein Zeichen ersetzt. Glob-Muster werden nur mit dem Dateinamen abgeglichen, nicht mit dem vollständigen Pfad, wodurch sie sich ideal für Muster wie „ *_p.h “ eignen.
• Reguläre Ausdrücke: Verwenden Sie für den Abgleich auf Basis des Pfads die Regex-Syntax. Jedes Muster, das Regex-Metazeichen (^$[]{}()|+\\.) enthält, wird als regulärer Ausdruck behandelt und mit dem vollständigen normalisierten Dateipfad abgeglichen.

Muster werden mit Schrägstrichen (/) als Verzeichnistrennzeichen abgeglichen. QDoc normalisiert Pfadtrennzeichen intern, verwenden Sie daher in Mustern unabhängig von der Plattform immer „ / “.

Wenn eine Klasse aufgrund ihres Speicherorts als „Internal“ gekennzeichnet ist, wird der Status „Internal“ automatisch über die Knotenhierarchie auf alle ihre Mitglieder übertragen.

Beispiel – Qt-Konvention (glob):

internalfilepatterns = *_p.h

Passt auf jede Datei, die auf „ _p.h “ endet, unabhängig von der Verzeichnistriefe.

Beispiel – Mehrere Dateinamenmuster (glob):

internalfilepatterns = *_p.h *_impl.h *_pch.h

Erkennt Dateien, die auf _p.h, _impl.h oder _pch.h enden.

Beispiel – Verzeichnisbasierte Übereinstimmung (regex):

internalfilepatterns = .*/internal/.*\.h

Erkennt jede Datei „ .h “ in jedem Verzeichnis „ internal “ auf beliebiger Ebene.

Beispiel – Mehrere Muster:

internalfilepatterns = *_p.h .*/private/.*\.h

Kombiniert „glob“-Muster für einfache Fälle mit regulären Ausdrücken für komplexe Pfade.

QDoc hat in Qt 6.11 „ internalfilepatterns “ eingeführt.

Siehe auch: excludedirs und excludefiles.

ignorewords

Die Variable „ ignorewords “ dient zur Angabe einer Liste von Zeichenfolgen, die QDoc bei der Auflösung von Hyperlink-Zielen ignoriert.

QDoc verfügt über eine Funktion zur automatischen Verlinkung, bei der versucht wird, Wörter zu verlinken, die C++- oder QML-Entitäten ähneln. Konkret kommt eine Zeichenkette für die automatische Verlinkung in Frage, wenn sie mindestens drei Zeichen lang ist, keine Leerzeichen enthält und

• ein Wort im „camelCase“-Format ist, d. h., mindestens ein Großbuchstaben an einer Position größer als Null enthält, oder
• die Teilzeichenfolge „ () “ oder „ :: “ enthält oder
• mindestens ein Sonderzeichen enthält: „ @ “ oder „ _ “.

Das Hinzufügen eines qualifizierten Wortes zu „ ignorewords “ verhindert, dass QDoc dieses Wort automatisch verlinkt. Wenn beispielsweise das Wort „OpenGL“ ein gültiges Linkziel ist (ein Abschnitt, \pageoder \externalpage Titel), lässt sich ein Hyperlink bei jedem Vorkommen vermeiden mit

ignorewords += OpenGL

Durch explizites Verlinken mit \l funktioniert weiterhin für ignorierte Wörter.

Die Variable „ ignorewords “ wurde in QDoc 5.14 eingeführt.

ignoresince

Die Variable „ ignoresince “ dient dazu, einen Schwellenwert für Versionen festzulegen, die an den Befehl \since Befehl übergeben werden. Alle „ \since “-Befehle, die eine Version definieren, die unterhalb des Schwellenwerts liegt, werden ignoriert und erzeugen keine Ausgabe.

Die Schwellenwerte sind projektspezifisch. Der Projektname kann als Untervariable definiert werden. Der Standardprojektname lautet „Qt“. Beispiel:

ignoresince      = 5.0
ignoresince.QDoc = 5.0

Dadurch werden „ \since “-Befehle ignoriert, bei denen die Hauptversion 4 oder niedriger ist und das Projekt entweder „ QDoc “ oder undefiniert ist.

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

Die Variable „ ignoresince “ wurde in QDoc 5.15 eingeführt.

Siehe auch \since.

imagedirs

Die Variable „ imagedirs “ gibt die Verzeichnisse an, die die in der Dokumentation verwendeten Bilder enthalten.

Die images Variablen „ imagedirs “ und „ “ werden von der \image und \inlineimage Befehlen verwendet. Sind sowohl die images und „ imagedirs “ definiert sind, sucht QDoc in beiden. Zuerst in images, dann in imagedirs.

QDoc durchsucht die Verzeichnisse in der angegebenen Reihenfolge und akzeptiert die erste übereinstimmende Datei, die es findet. Es wird nur in den angegebenen Verzeichnissen gesucht, nicht in Unterverzeichnissen.

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

Bei der Verarbeitung

\image calculator-example.png

prüft QDoc dann, ob eine Datei namens „calculator-example.png“ als Wert in der Variablen „ images “ aufgeführt ist. Ist dies nicht der Fall, sucht es in der Variablen „ imagedirs “ nach:

$QTDIR/doc/src/images/calculator-example.png

Falls die Datei nicht existiert, sucht QDoc nach einer Datei namens

$QTDIR/examples/calculator-example.png

imagesoutputdir

Die Variable „ imagesoutputdir “ legt den Namen des Unterverzeichnisses im Ausgabeverzeichnis fest, in dem QDoc die Bilder speichert.

Der Standardwert für „ imagesoutputdir “ lautet „images“.

Bilddateien, die als Argument an \image und \inlineimage Befehle als Argument übergeben werden, werden in dieses Verzeichnis kopiert.

Die Festlegung eines benutzerdefinierten Ausgabeverzeichnisses für Bilder ist nützlich bei der Erstellung von Dokumentationen mit mehreren Modulen, bei der mehrere Dokumentationsprojekte so konfiguriert sind, dass sie ein gemeinsames Ausgabeverzeichnis verwenden. Beispielsweise bei der folgenden (gemeinsamen) Konfiguration:

imagesoutputdir = images/${project}

Jedes Dokumentationsprojekt im Build verwendet „ <outputdir>/images/<project name> “ zum Speichern von Bildern, wodurch vermieden wird, dass gleichnamige Bilddateien sich gegenseitig überschreiben.

Diese Variable wurde mit Qt 6.11 in QDoc eingeführt.

Sprache

Die Variable ` language ` gibt die Sprache des Quellcodes an, der in der Dokumentation verwendet wird. Konkret definiert sie die Standardsprache für die Analyse von Quellcode innerhalb der Blöcke ` \code ` und ` \endcode `.

language = Cpp

Die Standardsprache ist C++ (Cpp) und muss nicht explizit angegeben werden. Wenn die Codeausschnitte in der Dokumentation hauptsächlich aus QML-Code bestehen, legen Sie QML als Standard fest:

language = QML

Siehe auch \code.

Standortinformationen

Die boolesche Variable „ locationinfo “ legt fest, ob detaillierte Standortinformationen zu jeder Entität in die Dateien „ .index “ und „ .webxml “ geschrieben werden (bei Verwendung des WebXML-Ausgabeformats).

Die Standortinformationen bestehen aus dem vollständigen Pfad und der Zeilennummer entweder der Deklaration oder des Dokumentationskommentarblocks im Quellcode.

Wenn Sie diesen Wert auf „ false “ setzen, werden die Positionsangaben deaktiviert:

locationinfo = false

Der Standardwert lautet „ true “.

Die Variable „ locationinfo “ wurde in QDoc 5.15 eingeführt.

logwarnings

Die boolesche Variable „ logwarnings “ legt fest, ob QDoc Warnmeldungen zusätzlich zu stderr in eine Protokolldatei schreibt.

Ist die Variable auf „ true “ gesetzt, erstellt QDoc im Ausgabeverzeichnis eine Protokolldatei mit dem Namen „ <project>-qdoc-warnings.log “ und schreibt alle Warnmeldungen in diese Datei. Warnungen werden weiterhin wie gewohnt auch an stderr ausgegeben.

Die Protokolldatei enthält einen Header mit Projektinformationen und standardmäßig die Befehlszeilenargumente, mit denen QDoc aufgerufen wurde, um die Reproduzierbarkeit zu gewährleisten.

Die Einstellung auf „ true “ aktiviert die Protokollierung von Warnungen:

logwarnings = true

Der Standardwert ist „ false “.

Diese Funktion ist nützlich für umfangreiche Dokumentationssätze oder CI-Umgebungen, in denen zahlreiche Warnungen auftreten können, die zu schnell vorbeiscrollen, um systematisch analysiert zu werden.

Die Variable „ logwarnings “ wurde in QDoc 6.11 eingeführt.

logwarnings.disablecliargs

Die boolesche Untervariable „ logwarnings.disablecliargs “ steuert, ob CLI-Argumente aus den Kopfzeilen der Warnprotokolldateien weggelassen werden.

logwarnings.disablecliargs = true

Ist die Variable auf „ true “ gesetzt, werden die Befehlszeilenargumente aus dem Kopf der Protokolldatei weggelassen, wodurch die Protokolldateien in verschiedenen Umgebungen portierbar sind. Dies ist nützlich für Testsuiten und CI-Systeme, in denen Befehlszeilenargumente umgebungsspezifische Pfade und temporäre Verzeichnisse enthalten.

Der Standardwert ist „ false “. Die Variable „ logwarnings.disablecliargs “ wurde in QDoc 6.11 eingeführt.

Makro

Die Variable „ macro “ dient dazu, eigene einfache QDoc-Befehle zu erstellen. Die Syntax lautet macro.command = definition. Der Befehl ist auf eine Kombination aus Buchstaben und Ziffern beschränkt, Sonderzeichen wie Bindestrich oder Unterstrich sind nicht zulässig. Die Definition wird in der QDoc-Syntax geschrieben.

Eine Makrovariable kann auf die Verwendung in einer bestimmten Art der Ausgabegenerierung beschränkt werden. Durch Anhängen von „ .HTML “ an den Makronamen wird das Makro beispielsweise nur bei der Generierung von HTML-Ausgaben verwendet.

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

Das erste Makro definiert den Befehl „ \key “, um sein Argument in fetter Schrift darzustellen. Das zweite Makro definiert den Befehl „ \raisedaster “, um ein hochgestelltes Sternchen darzustellen, jedoch nur bei der Erzeugung von HTML.

Ein Makro kann außerdem bis zu sieben Parameter annehmen:

macro.hello            = "Hello \1!"

Parameter werden an Makros auf dieselbe Weise übergeben wie an andere Befehle:

\hello World

Wenn Sie mehr als einen Parameter verwenden oder wenn ein Argument Leerzeichen enthält, setzen Sie jedes Argument in geschweifte Klammern:

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

Eine spezielle Makrooption, „match“, kann hinzugefügt werden, um bei expandierten Makros zusätzliche Mustererkennung mit regulären Ausdrücken zu ermöglichen.

Beispielsweise:

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

Dies erstellt ein Makro „ \qtminorversion “, das sich basierend auf der Umgebungsvariablen „QT_VER“ zur Minor-Version erweitert.

Ein Makro, das ein Übereinstimmungsmuster definiert, gibt alle Erfassungsgruppen (Klammern) aneinandergefügt aus oder die exakt übereinstimmende Zeichenkette, falls das Muster keine Erfassungsgruppen enthält.

Weitere Informationen zu vordefinierten Makros finden Sie unter „Makros“.

manifestmeta

Die Variable „ manifestmeta “ legt zusätzliche Metadaten für die von QDoc generierten Beispiel-Manifestdateien fest.

Weitere Informationen finden Sie im Abschnitt „Manifest-Meta-Inhalte “.

moduleheader

Die Variable „ moduleheader “ definiert den Namen des Modul-Headers eines dokumentierten C++-Moduls.

Projekte, die C++-APIs dokumentieren, benötigen einen Header auf Modulebene, der alle öffentlichen Klassen, Namespaces und Header-Dateien des Moduls enthält. Der Clang-Parser in QDoc verwendet diese Datei, um einen vorkompilierten Header (PCH) für das Modul zu erstellen und so die Geschwindigkeit beim Parsen der Quelldateien zu erhöhen.

Standardmäßig wird der Projektname auch als Name des Modul-Headers verwendet.

project = QtCore

Bei dem oben genannten Projektnamen sucht QDoc in allen bekannten Include-Pfaden nach einem Modul-Header namens „QtCore“; dabei werden zunächst die als Befehlszeilenargumente übergebenen Pfade verwendet, anschließend die in der Variablen „includepaths“ aufgeführten Pfade.

QDoc gibt eine Warnung aus, wenn der Modul-Header nicht gefunden wird. Anschließend versucht es, einen künstlichen Modul-Header auf der Grundlage der in der Variablen „headerdirs“ aufgeführten Header zu erstellen.

Bei Qt-Dokumentationsprojekten stellt das Build-System QDoc in der Regel die richtigen Include-Pfade zur Verfügung, um den Modul-Header zu finden, vorausgesetzt, die Variable „ project “ ist korrekt gesetzt. Die Variable „ moduleheader “ liefert einen alternativen Dateinamen, nach dem QDoc suchen soll.

Bei Projekten, die keine C++-Dokumentation enthalten, verwenden Sie die parsecppcomments Variable, um die C++-Analyse zu deaktivieren. Die Einstellung von ` moduleheader ` auf eine leere Zeichenkette hat denselben Effekt und wird aus Gründen der Abwärtskompatibilität unterstützt:

# No C++ code to document in this project
moduleheader =

Siehe auch parsecppcomments, ` includepaths` und ` project`.

naturallanguage

Die Variable „ naturallanguage “ legt die natürliche Sprache fest, die für die von QDoc generierte Dokumentation verwendet wird.

naturallanguage = zh-Hans

Standardmäßig ist die natürliche Sprache „ en “, um die Kompatibilität mit älterer Dokumentation zu gewährleisten.

QDoc fügt die Informationen zur natürlichen Sprache mithilfe der Attribute „ lang “ und „ xml:lang “ in den von ihm generierten HTML-Code ein.

Siehe auch sourceencoding, outputencoding, C.7. Die Attribute „lang“ und „xml:lang“ sowie Best Practice 13: Verwendung von Hans- und Hant-Codes.

Navigation

Die Untervariablen „ navigation “ legen, sofern definiert, die Startseite, die Landing-Seite, die Seite mit den C++-Klassen und die Seite mit den QML-Typen fest, die in der generierten Navigationsleiste für jede Seite angezeigt werden.

In einem Projekt mit mehreren Unterprojekten (z. B. Qt-Modulen) definiert jedes Unterprojekt in der Regel eine eigene Landing-Page, während für alle Unterprojekte dieselbe Startseite verwendet wird.

Untervariablen

Beispiel:

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

Die obige Konfiguration erzeugt die folgende Navigationsleiste für den QML-Typ „ Item “:

Qt 5.10 > Qt Quick > QML Types > Item QML Type

Inhaltsverzeichnis und Navigationslinks

Wenn eine oder mehrere Seiten als Inhaltsverzeichnis (TOC) dienen, listen Sie deren Titel in „ navigation.toctitles “ auf, um die automatische Generierung von Navigationslinks (vorherige und nächste Seite) für alle im Inhaltsverzeichnis aufgeführten Seiten zu ermöglichen.

QDoc erwartet eine \list Links auf jeder Inhaltsverzeichnisseite. Verschachtelte Unterlisten sind zulässig.

Zum Beispiel:

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
        \list
            \li \l {What's new in v1.3} {v1.3}
            \li \l {What's new in v1.2} {v1.2}
            \li \l {What's new in v1.1} {v1.1}
        \endlist
\endlist

Seit QDoc-Version 6.10 können auch \generatelist in der Inhaltsverzeichnisliste erscheinen:

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
    \generatelist [descending] whatsnew
\endlist

Hier ist das Ergebnis ähnlich wie beim ersten \list, vorausgesetzt, alle drei „Was ist neu?“-Seiten gehören zur gleichen Gruppe whatsnew.

Siehe auch \ingroup.

overloadedsignalstarget

Standard: connecting-overloaded-signals

Die Variable „ overloadedsignalstarget “ legt das Verknüpfungsziel fest, das in automatisch generierten Hinweisen für überladene Signale verwendet wird.

Wenn QDoc auf ein überladenes Signal stößt, generiert es einen Hinweis mit einem Link zur Hilfedokumentation zum Anschluss an überladene Signale. Standardmäßig verweist dieser Link auf ein Ziel namens connecting-overloaded-signals.

Projekte können dies anpassen, um auf ihre eigene Dokumentation zu verweisen:

# Link to a target within the project
overloadedsignalstarget = signals-guide.html#overloaded-signals

# Link to external documentation
overloadedsignalstarget = https://example.com/docs/signals.html#overloaded-signals

Das Ziel kann sein:

• Ein einfacher Zielname (zur Verwendung mit \target Befehlen): connecting-overloaded-signals
• Eine relative URL: signals-guide.html#overloaded-signals
• Eine absolute URL: https://example.com/docs/signals.html#overloaded-signals

Siehe auch „overloadedslotstarget“.

overloadedslotstarget

Standard: connecting-overloaded-slots

Die Variable „ overloadedslotstarget “ legt das Link-Ziel fest, das in automatisch generierten Hinweisen für überladene Slots verwendet wird.

Wenn QDoc auf einen überladenen Slot stößt, generiert es einen Hinweis mit einem Link zur Hilfedokumentation über die Anbindung an überladene Slots. Standardmäßig verweist dieser Link auf ein Ziel namens „ connecting-overloaded-slots “.

Projekte können dies anpassen, um auf ihre eigene Dokumentation zu verweisen:

# Link to a target within the project
overloadedslotstarget = signals-guide.html#overloaded-slots

# Link to external documentation
overloadedslotstarget = https://example.com/docs/slots.html#overloaded-slots

Das Ziel kann sein:

• Ein einfacher Zielname (zur Verwendung mit \target Befehlen): connecting-overloaded-slots
• Eine relative URL: signals-guide.html#overloaded-slots
• Eine absolute URL: https://example.com/docs/slots.html#overloaded-slots

Siehe auch ` overloadedsignalstarget`.

outputdir

Die Variable „ outputdir “ gibt das Verzeichnis an, in dem QDoc die generierte Dokumentation ablegt.

outputdir = $QTDIR/doc/html

speichert die generierte Qt-Referenzdokumentation unter $QTDIR/doc/html. Beispielsweise befindet sich die Dokumentation der Klasse „ QWidget “ unter

$QTDIR/doc/html/qwidget.html

Die zugehörigen Bilder werden in einem Unterverzeichnis namens „ images “ abgelegt.

outputencoding

Die Variable „ outputencoding “ legt die Kodierung fest, die für die von QDoc erstellte Dokumentation verwendet wird.

outputencoding = UTF-8

Standardmäßig ist die Ausgabekodierung „ ISO-8859-1 “ (Latin1), um die Kompatibilität mit älterer Dokumentation zu gewährleisten. Bei der Erstellung von Dokumentation für bestimmte Sprachen, insbesondere für außereuropäische Sprachen, reicht dies jedoch nicht aus, und es ist eine Kodierung wie UTF-8 erforderlich.

QDoc kodiert HTML unter Verwendung dieser Kodierung und generiert die richtigen Deklarationen, um Browsern mitzuteilen, welche Kodierung verwendet wird. Die Konfigurationsvariable ` naturallanguage ` sollte ebenfalls angegeben werden, um Browsern einen vollständigen Satz an Zeichenkodierungs- und Sprachinformationen zur Verfügung zu stellen.

Siehe auch „outputencoding “ und „naturallanguage“.

outputformats

Die Variable „ outputformats “ legt das Format bzw. die Formate der generierten Dokumentation fest.

Seit Qt 5.11 unterstützt QDoc die Formate HTML und WebXML; seit Qt 5.15 kann die Dokumentation auch im DocBook-Format generiert werden. Wenn kein „ outputformats “ angegeben ist, generiert QDoc die Dokumentation im HTML-Format (dem Standardformat). Alle Ausgabeformate können mit eigenen Ausgabeverzeichnissen und weiteren Einstellungen festgelegt werden. Zum Beispiel:

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

Dadurch wird HTML-Dokumentation mit den Standardeinstellungen sowie WebXML-Dokumentation im Ausgabeverzeichnis „webxml“ generiert.

outputprefixes

Die Variable „ outputprefixes “ legt eine Zuordnung zwischen Dateitypen und den Präfixen fest, die den Dateinamen der Ausgabedateien in der generierten Dokumentation vorangestellt werden sollen.

QDoc unterstützt das Hinzufügen eines Ausgabeprefixes zu den Dateinamen von Referenzseiten für QML-Typen, C++-Klassen, Namespaces und Header-Dateien.

outputprefixes     = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-

Standardmäßig haben Dateien, die die API-Dokumentation für QML-Typen enthalten, das Präfix „ qml- “. Im obigen Beispiel wird stattdessen das Präfix „ uicomponents- “ verwendet.

Ebenso haben die Dokumentationsseiten für C++-Typen im obigen Beispiel das Präfix „ components- “. Standardmäßig haben C++-Typseiten kein Präfix.

outputsuffixes

Die Variable ` outputsuffixes ` legt eine Zuordnung zwischen Dateitypen und Suffixen fest, die auf den Modul- oder Typnamen angewendet werden sollen, wie sie in den Namen der Ausgabedateien erscheinen.

QDoc unterstützt das Hinzufügen einer Ausgabesuffix zu den Dateinamen von Modulseiten, QML-Typen, C++-Klassen, Namespaces und Referenzseiten für Header-Dateien.

Standardmäßig wird kein Suffix verwendet. Das QML-Ausgabesuffix wird, sofern definiert, als Suffix an den Modulnamen angehängt, wie er in den Dateinamen von QML-Typ- und QML-Modul-Seiten erscheint.

Dateinamen für C++-Typen enthalten keinen Modulnamen. Das CPP-Ausgabesuffix wird, sofern definiert, als Suffix an den Typnamen angehängt.

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

Mit den obigen Definitionen lautet der Name der generierten Datei für einen QML-Typ „FooWidget“ bei einem QML-Modulnamen „FooBar“ und dem Standard -Ausgabeprefix (qml-) „ qml-foobar-tp-foowidget.html “.

Ebenso generiert QDoc für eine C++-Klasse „QFoobar“ den Namen „ qfoobar-tp.html “.

Die Variable „ outputsuffixes “ wurde in QDoc 5.6 eingeführt.

parsecppcomments

Die Variable „ parsecppcomments “ legt fest, ob QDoc C++-Quelldateien mit dem auf Clang basierenden C++-Parser analysiert.

Wenn die Einstellung auf „ false “ gesetzt ist, überspringt QDoc die Clang-Analyse und die PCH-Generierung für das Projekt und verarbeitet stattdessen „ .cpp “-Dateien mit dem reinen Dokumentations-Parser. Dies ist nützlich für Projekte, die ausschließlich QML-APIs dokumentieren, bei denen die C++-Quelldateien zwar QDoc-Kommentare, aber keine zu dokumentierenden C++-Entitäten enthalten.

Der Standardwert ist „ true “.

parsecppcomments = false

Die Variable „ parsecppcomments “ wurde in Qt 6.12 in QDoc eingeführt.

Siehe auch moduleheader.

qhp

Die Untervariablen „ qhp “ dienen dazu, die Informationen zu definieren, die in „ Qt Help Project“-Dateien (qhp) geschrieben werden sollen.

Informationen zu diesem Vorgang finden Sie im Kapitel „Erstellen von Hilfe-Projektdateien “.

Seit QDoc 6.6 bedeutet die Einstellung der Basisvariablen „ qhp “ auf „ true “, dass eine gültige Hilfsprojektkonfiguration erwartet wird:

qhp = true

Wenn in einer Projektkonfiguration „ qhp.projects “ nicht definiert ist, gibt QDoc eine Warnung aus. Dies ist nützlich, um sicherzustellen, dass alle Dokumentationsprojekte mit einer gemeinsamen .qdocconf-Datei auf oberster Ebene (wie bei Qt XML) korrekt konfiguriert sind.

Um die Warnung zu deaktivieren, setzen Sie die Variable auf „ false “.

showautogenerateddocs

Die boolesche Variable „ showautogenerateddocs “ legt fest, ob die Dokumentation, die QDoc automatisch für explizit mit Standardwerten versehene und gelöschte spezielle Mitgliedsfunktionen generiert, in der Ausgabe erscheint.

QDoc generiert diese Dokumentation, wenn kein \fn Block eine solche Funktion dokumentiert. Mit \fn hat stets Vorrang vor dem generierten Text und wird von dieser Variablen nicht beeinflusst.

Wird diese Variable auf „ false “ gesetzt, wird die automatisch generierte Dokumentation weggelassen:

showautogenerateddocs = false

Der Standardwert lautet „ true “.

Die Variable „ showautogenerateddocs “ wurde in QDoc 6.12 eingeführt.

sourcedirs

Die Variable „ sourcedirs “ gibt die Verzeichnisse an, die die in der Dokumentation verwendeten Dateien vom Typ „ .cpp “ oder „ .qdoc “ enthalten.

sourcedirs  += .. \
               ../../../examples/gui/doc/src

Bei der Ausführung liest QDoc als Erstes die in der header Variablen sowie derjenigen in den durch die Variable ` headerdir ` angegebenen Verzeichnissen (einschließlich aller Unterverzeichnisse) durch und erstellt dabei eine interne Struktur der Klassen und ihrer Funktionen.

Anschließend liest es die in der sourcessowie die in den in der sourcedirs Variable angegeben sind (einschließlich aller Unterverzeichnisse), und führt dabei eine Zusammenführung der Dokumentation mit der Struktur durch, die es aus den Header-Dateien abgerufen hat.

Sind sowohl die Variablen „ sources “ als auch „ sourcedirs “ definiert, liest QDoc beide durch, zunächst sources dann sourcedirs.

fileextensions In den angegebenen Verzeichnissen liest QDoc nur die Dateien mit dem in der sources.fileextensions Variablen angegeben sind. Die durch sources werden unabhängig von ihren Dateiendungen gelesen.

Siehe auch „sources “ und „sources.fileextensions“.

sourceencoding

Die Variable „ sourceencoding “ legt die für den Quellcode und die Dokumentation verwendete Kodierung fest.

sourceencoding = UTF-8

Standardmäßig ist die Quellcode-Kodierung „ ISO-8859-1 “ (Latin1), um die Kompatibilität mit älterer Dokumentation zu gewährleisten. Für einige Sprachen, insbesondere außereuropäische Sprachen, reicht dies jedoch nicht aus, sodass eine Kodierung wie UTF-8 erforderlich ist.

Obwohl QDoc diese Kodierung zum Lesen von Quell- und Dokumentationsdateien verwendet, können Einschränkungen von C++-Compilern dazu führen, dass Sie keine Nicht-ASCII-Zeichen in Kommentaren im Quellcode verwenden können. In solchen Fällen ist es möglich, die API-Dokumentation vollständig in Dokumentationsdateien zu verfassen.

Siehe auch „naturallanguage “ und „outputencoding“.

Quellen

Mit der Variablen „ sources “ können Sie zusätzlich zu den Dateien, die sich in den durch die Variable „sourcedirs“ angegebenen Verzeichnissen befinden, einzelne Quelldateien angeben.

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

Bei der Verarbeitung der Variablen „ sources “ verhält sich QDoc genauso wie bei der Verarbeitung der Variablen „sourcedirs “. Weitere Informationen finden Sie unter der Variablen „sourcedirs “.

Siehe auch „sourcedirs“.

sources.fileextensions

Die Variable „ sources.fileextensions “ filtert die Dateien innerhalb eines Quellverzeichnisses.

Bei der Verarbeitung der in der sourcedirs Variablen angegebenen Quelldateien liest QDoc nur die Dateien mit den in der Variablen „ sources.fileextensions “ angegebenen Dateiendungen. Auf diese Weise vermeidet QDoc den Zeitaufwand für das Einlesen irrelevanter Dateien.

Die Standarderweiterungen sind *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml und *.qdoc.

Die Dateiendungen werden als Standard-Platzhalterausdrücke angegeben. Sie können dem Filter mit „+=“ eine Dateiendung hinzufügen. Beispiel:

sources.fileextensions += *.CC

Siehe auch „sourcedirs “ und „sources“.

falsch

Die Variable „ spurious “ schließt angegebene QDoc-Warnungen aus der Ausgabe aus. Die Warnungen werden mithilfe von Standard-Platzhalterausdrücken angegeben.

spurious = "Cannot find .*" \
"Missing .*"

Stellt sicher, dass Warnungen, die einem dieser Ausdrücke entsprechen, bei der Ausführung von QDoc nicht in die Ausgabe aufgenommen werden. Beispielsweise würde die folgende Warnung aus der Ausgabe weggelassen werden:

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

Die Variable „ syntaxhighlighting “ legt fest, ob QDoc die Syntaxhervorhebung für Quellcode durchführen soll, der in der von ihm generierten Dokumentation zitiert wird.

syntaxhighlighting = true

aktiviert die Syntaxhervorhebung für alle unterstützten Programmiersprachen.

tabsize

Die Variable „ tabsize “ definiert die Größe eines Tabulatorzeichens.

tabsize = 4

gibt dem Tabulatorzeichen die Größe von 4 Leerzeichen. Der Standardwert der Variablen ist 8 und muss nicht angegeben werden.

tagfile

Die Variable „ tagfile “ gibt die Doxygen-Tag-Datei an, die bei der HTML-Generierung geschrieben werden soll.

version

Die Variable „ version “ gibt die Versionsnummer der dokumentierten Software an.

version = 5.6.0

Wenn eine Versionsnummer angegeben wird (mithilfe des version oder versionsym in einer ` .qdocconf `-Datei angegeben), ist sie über den entsprechenden Befehl ` \version ` für die Verwendung in der Dokumentation zugänglich.

Siehe auch versionsym.

versionsym

Die Variable „ versionsym “ gibt ein C++-Präprozessorsymbol an, das die Versionsnummer der dokumentierten Software definiert.

versionsym = QT_VERSION_STR

QT_VERSION_STR ist in qglobal.h wie folgt definiert

#define QT_VERSION_STR   "5.14.1"

Wenn eine Versionsnummer angegeben wird (unter Verwendung des version oder versionsym in einer ` .qdocconf `-Datei), ist sie über den entsprechenden Befehl ` \version ` für die Verwendung in der Dokumentation zugänglich.

Siehe auch \version.

warninglimit

Die Variable „ warninglimit “ legt die maximal zulässige Anzahl von Dokumentationswarnungen fest. Wird diese Grenze überschritten, läuft QDoc normal weiter, wird jedoch mit der Anzahl der Warnungen als Fehlercode beendet. Wurde die Grenze nicht überschritten oder wurde „ warninglimit “ nicht definiert, wird der QDoc-Prozess mit dem Status 0 beendet, sofern keine weiteren kritischen Fehler aufgetreten sind.

Wird „ warninglimit “ auf „ 0 “ gesetzt, führt bereits jede einzelne Warnung zum Abbruch.

Beispielsweise:

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

Die Variable ` warninglimit ` wurde in Qt 5.11 eingeführt.