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 erstellte Dokumentation abgelegt werden soll. Sie können auch einige kleinere Manipulationen an QDoc selbst vornehmen, um dessen Ausgabe- und Verarbeitungsverhalten zu steuern.

codeindent

Die Variable codeindent gibt die Einrückungsebene an, die QDoc beim Schreiben von Codeschnipseln verwendet.

Ursprünglich verwendete QDoc einen fest kodierten Wert von vier Leerzeichen für die Codeeinrückung, um sicherzustellen, dass Codefragmente leicht vom umgebenden Text unterschieden werden können. Da wir Stylesheets verwenden können, um das Aussehen bestimmter Arten von HTML-Elementen anzupassen, ist dieser Einrückungsgrad nicht immer erforderlich.

codeprefix, codesuffix

Die Variablen codeprefix und codesuffix geben ein Paar von Zeichenketten an, in die jeder Codeschnipsel eingeschlossen ist.

definiert

Die Variable defines spezifiziert die C++ Präprozessor-Symbole, die QDoc erkennt und auf die es reagiert.

Wenn ein Präprozessor-Symbol mit der Variable defines angegeben wird, können Sie auch den Befehl \if verwenden, um die Dokumentation einzuschließen, die nur dann einbezogen wird, wenn das Präprozessor-Symbol definiert ist.

defines = QT_GUI_LIB

Dadurch wird sichergestellt, dass QDoc den Code verarbeitet, für den diese Symbole definiert sein müssen. Zum 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 auf der Kommandozeile mit der Option -D definieren. Zum Beispiel:

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

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

Siehe auch falsehoods und \if.

hängt

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

Wie Qt selbst ist auch die Dokumentation für Qt über mehrere Module verteilt. In einem Dokumentationsprojekt mit mehreren Modulen besteht der minimale Satz von Abhängigkeiten für ein einzelnes Modul aus den tatsächlichen Build-Abhängigkeiten. Wenn es darüber hinaus ein Dokumentationsprojekt (Modul) gibt, das als Einstiegspunkt für die gesamte Dokumentation dient und Navigationslinks bereitstellt, sollte jede Moduldokumentation dieses als Abhängigkeit enthalten.

Wenn QDoc Dokumentation für ein Projekt generiert, wird auch eine .index Datei erzeugt, die URLs zu jeder verlinkbaren Entität im Projekt enthält. Jede Abhängigkeit ist ein (klein geschriebener) Name eines Projekts. Dieser Name muss mit dem Basisnamen der für dieses Projekt erzeugten Indexdatei übereinstimmen.

depends = \
    qtdoc \
    qtcore \
    qtquick

Wenn QDoc ein Projekt aufruft, das Abhängigkeiten hat und die Variable depends verwendet, müssen ein oder mehrere -indexdir Pfade als Kommandozeilenoption(en) ü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

Mit der obigen Angabe sucht QDoc nach einer Datei $QT_INSTALL_DOCS/qtdoc/qtdoc.index für eine Abhängigkeit zu qtdoc. Wenn keine Indexdatei für eine Abhängigkeit gefunden wird, gibt QDoc eine Warnung aus.

Das depends Kommando akzeptiert auch einen speziellen Wert von '*'. Dies weist QDoc an, alle Indexdateien zu laden, die in den angegebenen Indexverzeichnissen gefunden werden; das heißt, "hängt von allem ab".

depends = *

Siehe auch indexes, project und url.

exampledirs

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

Die Variablen examples und exampledirs werden von den Befehlen \quotefromfile, \quotefile und \example verwendet. Wenn sowohl die Variablen examples als auch exampledirs definiert sind, sucht QDoc in beiden, zuerst in examples und dann in exampledirs.

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.

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

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

Bei der Verarbeitung von

\quotefromfile widgets/calculator/calculator.cpp

QDoc prüft, ob eine Datei namens calculator.cpp als Wert in der examples Variable aufgeführt ist. Ist dies nicht der Fall, wird die Variable exampledirs durchsucht und zuerst geprüft, ob es eine Datei namens

$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 Beispiele.

Beispiele

Die Variable examples ermöglicht es Ihnen, einzelne Beispieldateien zusätzlich zu denen in den Verzeichnissen anzugeben, die durch die Variable exampledirs Variable angegebenen Verzeichnisse.

Die Variablen examples und exampledirs werden von den Befehlen \quotefromfile, \quotefile und \example verwendet. Wenn sowohl die examples als auch die exampledirs Variablen definiert sind, sucht QDoc in beiden, zuerst in examples dann in exampledirs.

QDoc durchsucht die für die Variable examples aufgelisteten Werte in der angegebenen Reihenfolge und akzeptiert den ersten, den es findet.

Für ein ausführliches Beispiel siehe den exampledirs Befehl. Beachten Sie aber, dass Sie den Pfad nicht angeben müssen, wenn Sie wissen, dass die Datei in der Variable examples aufgeführt ist:

\quotefromfile calculator.cpp

Siehe auch exampledirs.

BeispieleInstallationspfad

Die Variable examplesinstallpath legt den Wurzelpfad für die Beispiele dieses Projekts unter dem installierten Beispielverzeichnis fest.

Unter der Annahme, dass der Root-Installationspfad für alle Beispiele QT_INSTALL_EXAMPLES ist, wird der Pfad

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

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

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

Zum Beispiel:

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

examplesinstallpath = mymodule

Mit dem folgenden Beispielbefehl:

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

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

Siehe auch: exampledirs, \example, und \meta.

examples.fileextensions

Die Variable examples.fileextensions gibt die Dateierweiterungen an, nach denen QDoc beim Sammeln von Beispieldateien für die Anzeige in der Dokumentation sucht.

Die Standard-Erweiterungen sind *.cpp, *.h, *.js, *.xq, *.svg, *.xml und *.ui.

Die Erweiterungen werden als Standard-Wildcard-Ausdrücke angegeben. Sie können dem Filter eine Dateierweiterung mit '+=' hinzufügen. Zum Beispiel:

examples.fileextensions += *.qrc

Siehe auch headers.fileextensions.

Ausgeschlossene Erbsen

Die Variable excludedirs dient zur Auflistung von Verzeichnissen, die von QDoc nicht verarbeitet werden sollen, auch wenn dieselben Verzeichnisse in den Variablen sourcedirs oder headerdirs enthalten sind.

Zum Beispiel:

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

Wenn QDoc ausgeführt wird, schließt es die aufgelisteten Verzeichnisse von der weiteren Verarbeitung aus. Dateien in diesen Verzeichnissen werden von QDoc nicht gelesen.

Siehe auch excludefiles.

excludefiles

Die Variable excludefiles erlaubt es Ihnen, einzelne Dateien anzugeben, 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 die obige Variable in Ihre qdocconf-Datei für qtbase aufnehmen, wird keine Klassendokumentation für QWidget erzeugt.

Seit Qt 5.6 werden auch einfache Wildcards ('*' und '?') von excludefiles erkannt. Um zum Beispiel alle privaten Qt-Header-Dateien vom Parsen 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 von imagedirs in das Ausgabeverzeichnis, wenn sie von der Variable \image oder \inlineimage Befehl referenziert wird. Wenn Sie weitere Bilder kopieren wollen, müssen Sie diese mit der Variable extraimages angeben.

Die allgemeine Syntax lautet format.extraimages = image.

Ein kontextbezogenes Beispiel finden Sie in der Beschreibung der Variable HTML.postheader.

Beispiel:

HTML.extraimages = images/qt-logo.png

Siehe auch images und imagedirs.

Unwahrheiten

Die Variable falsehoods definiert den Wahrheitswert der angegebenen Präprozessorsymbole als falsch.

Die Werte der Variablen sind reguläre Ausdrücke (siehe QRegularExpression für Details). Wenn diese Variable für ein Präprozessorsymbol nicht gesetzt ist, nimmt QDoc an, dass sein Wahrheitswert wahr ist. Die Ausnahme ist '0', die immer falsch ist.

QDoc erkennt die folgende Präprozessor-Syntax und ist in der Lage, sie auszuwerten:

#ifdef NOTYET
 ...
#endif

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

Angesichts einer unbekannten Syntax wie

#if NOTYET
    ...
#endif

QDoc wertet sie standardmäßig als wahr aus, es sei denn, das Präprozessor-Symbol ist in der Variablen falsehoods angegeben:

falsehoods = NOTYET

Siehe auch Defines.

generateindex

Die Variable generateindex enthält einen booleschen Wert, der angibt, ob eine Indexdatei erzeugt werden soll, wenn die HTML-Dokumentation generiert wird.

Standardmäßig wird bei der HTML-Dokumentation immer eine Indexdatei erzeugt, so dass diese Variable in der Regel nur verwendet wird, wenn Sie diese Funktion deaktivieren (indem Sie den Wert auf false setzen) oder wenn Sie die Indexerzeugung für die WebXML-Ausgabe aktivieren (indem Sie den Wert auf true setzen).

headerdirs

Die Variable headerdirs gibt die Verzeichnisse an, die die Header-Dateien enthalten, die mit den in der Dokumentation verwendeten .cpp Quelldateien verbunden sind.

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

Wenn QDoc ausgeführt wird, liest es als erstes die Header, die in der Variable headers angegebenen Header und die Header in den Verzeichnissen, die in der Variable headerdir angegeben sind (einschließlich aller Unterverzeichnisse), zu lesen und eine interne Struktur der Klassen und ihrer Funktionen aufzubauen.

Dann liest es die in der Variable sourcesangegebenen Quellen und die in den Verzeichnissen, die in der Variablen sourcedirs angegebenen Verzeichnisse (einschließlich aller Unterverzeichnisse), wobei die Dokumentation mit der aus den Header-Dateien gewonnenen Struktur zusammengeführt wird.

Wenn sowohl die headers als auch die headerdirs Variablen definiert sind, liest QDoc durch beide, zuerst headers dann headerdirs.

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

Siehe auch headers und headers.fileextensions.

Kopfzeilen

Die Variable headers ermöglicht es Ihnen, einzelne Header-Dateien zusätzlich zu denen in den Verzeichnissen anzugeben, die durch die Variable headerdirs Variable angegebenen Verzeichnisse.

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

Bei der Verarbeitung der Variable headers verhält sich QDoc genauso wie bei der Verarbeitung der Variable headerdirs Variable. Für weitere Informationen, siehe die headerdirs Variable.

Siehe auch headerdirs.

headers.fileextensions

Die Variable headers.fileextensions gibt die von den Headern verwendete Erweiterung an.

Bei der Verarbeitung der Header-Dateien, die in der headerdirs angegebenen Header-Dateien liest QDoc nur die Dateien mit den in der Variable headers.fileextensions angegebenen Dateierweiterungen. Auf diese Weise vermeidet QDoc, Zeit mit dem Lesen irrelevanter Dateien zu verbringen.

Die Standard-Erweiterungen sind *.ch, *.h, *.h++, *.hh, *.hpp, und *.hxx.

Die Erweiterungen werden als Standard-Wildcard-Ausdrücke angegeben. Sie können eine Dateierweiterung mit '+=' zum Filter hinzufügen. Zum Beispiel:

header.fileextensions += *.H

Siehe auch headerdirs.

includepaths

Die Variable includepaths wird verwendet, um zusätzliche Include-Pfade an den Clang-Parser zu übergeben, den QDoc zum Parsen von C++-Code für Dokumentationskommentare verwendet.

Die Variable akzeptiert eine Liste von Pfaden mit dem Präfix -I (Include-Pfad), -F (macOS Framework Include-Pfad) oder -isystem (System Include-Pfad). Wenn ein Präfix weggelassen wird, wird standardmäßig -I verwendet.

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

Siehe auch moduleheader.

Wörter ignorieren

Die Variable ignorewords wird verwendet, um eine Liste von Zeichenketten anzugeben, die QDoc bei der Auflösung von Hyperlink-Zielen ignoriert.

QDoc verfügt über eine automatische Verlinkungsfunktion, bei der eine Verlinkung bei Wörtern versucht wird, die C++- oder QML-Entitäten ähneln. Insbesondere qualifiziert sich eine Zeichenkette für die automatische Verlinkung, wenn sie mindestens drei Zeichen lang ist, keine Leerzeichen enthält und sie

• ein camelCase-Wort ist, d. h. sie enthält mindestens einen Großbuchstaben mit einem Index größer als Null, oder
• die Teilzeichenkette () oder :: enthält, oder
• mindestens ein Sonderzeichen enthält, @ oder _.

Das Hinzufügen eines qualifizierten Wortes zu ignorewords hindert QDoc daran, dieses Wort automatisch zu verknüpfen. Wenn zum Beispiel das Wort OpenGL ein gültiges Linkziel ist (ein Abschnitt, eine Seite oder ein externer Seitentitel), kann ein Hyperlink für jedes Vorkommen vermieden werden mit

ignorewords += OpenGL

Die explizite Verknüpfung mit \l funktioniert weiterhin für ignorierte Wörter.

Die Variable ignorewords wurde in QDoc 5.14 eingeführt.

ignoriertweil

Die Variable ignoresince wird verwendet, um einen Grenzwert für Versionen festzulegen, die an den Befehl \since übergeben werden. Alle \since-Befehle, die eine niedrigere Version als den Grenzwert definieren, werden ignoriert und erzeugen keine Ausgabe.

Die Abschneidewerte sind projektspezifisch. Der Projektname kann als Untervariable definiert werden. Der Standard-Projektname ist Qt. Zum Beispiel:

ignoresince      = 5.0
ignoresince.QDoc = 5.0

Hier 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 Variablen images und imagedirs werden von den Befehlen \image und \inlineimage verwendet. Wenn sowohl die images und imagedirs definiert sind, wird QDoc in beiden suchen. Zuerst in imagesund dann in imagedirs.

QDoc durchsucht die Verzeichnisse in der angegebenen Reihenfolge und akzeptiert die erste passende 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 von

\image calculator-example.png

QDoc prüft 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 Variable imagedirs nach:

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

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

$QTDIR/examples/calculator-example.png

Sprache

Die Variable language gibt die Sprache des Quellcodes an, die in der Dokumentation verwendet wird. Insbesondere definiert sie die Standardsprache für das Parsen von Quellcode innerhalb von \code ... \endcode-Blöcken.

language = Cpp

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

language = QML

Siehe auch code-command[\code}.

Standortinfo

Die boolesche Variable locationinfo bestimmt, ob detaillierte Standortinformationen über jede Entität in .index-files und .webxml-files (bei Verwendung des WebXML-Ausgabeformats) geschrieben werden.

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

Die Einstellung false schaltet die Ortsangabe aus:

locationinfo = false

Der Standardwert ist true.

Die Variable locationinfo wurde in QDoc 5.15 eingeführt.

Makro

Die Variable macro wird verwendet, um eigene einfache QDoc-Befehle zu erstellen. Die Syntax lautet macro.command = definitionDer Befehl ist auf eine Kombination von Buchstaben und Zahlen beschränkt, aber keine Sonderzeichen wie Bindestrich oder Unterstrich. Die Definition wird in QDoc-Syntax geschrieben.

Eine Makrovariable kann für die Verwendung in einer bestimmten Art der Ausgabeerzeugung eingeschränkt werden. Durch das Anhängen von .HTML an den Makronamen wird das Makro zum Beispiel nur bei der Erzeugung von HTML-Ausgaben verwendet.

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

Das erste Makro definiert den Befehl \key, um sein Argument in einer fetten Schriftart darzustellen. Das zweite Makro definiert den Befehl \raisedaster, um ein hochgestelltes Sternchen darzustellen, allerdings nur beim Generieren von HTML.

Ein Makro kann auch bis zu sieben Parameter enthalten:

macro.hello            = "Hello \1!"

Parameter werden an Makros genauso übergeben wie an andere Befehle:

\hello World

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

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

\verinfo {QFooBar} {1.0 beta}

Eine spezielle Makrooption, match, kann für den zusätzlichen Abgleich von Mustern regulärer Ausdrücke für erweiterte Makros hinzugefügt werden.

Zum Beispiel,

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

Dadurch wird ein Makro \qtminorversion erstellt, das auf der Grundlage der Umgebungsvariablen QT_VER auf die Nebenversion erweitert wird.

Ein Makro, das ein Übereinstimmungsmuster definiert, gibt alle Erfassungsgruppen (Klammern) zusammenhängend aus oder die genaue übereinstimmende Zeichenfolge, wenn das Muster keine Erfassungsgruppen enthält.

Weitere Informationen über vordefinierte Makros finden Sie unter Makros.

manifestmeta

Die Variable manifestmeta spezifiziert zusätzlichen Meta-Inhalt für die von QDoc erzeugten Beispiel-Manifestdateien.

Siehe den Abschnitt Manifest-Meta-Inhalt für weitere Informationen.

moduleheader

Die Variable moduleheader definiert den Namen des Modulheaders eines dokumentierten C++-Moduls.

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

Standardmäßig wird der Projektname auch als Name für den Modulheader verwendet.

project = QtCore

Mit dem obigen Projektnamen sucht QDoc einen Modulheader QtCore in allen bekannten Include-Pfaden; zuerst unter Verwendung der als Kommandozeilenargumente übergebenen Pfade, dann der in der Includepaths-Variablen aufgeführten Pfade.

QDoc wird eine Warnung ausgeben, wenn der Modul-Header nicht gefunden wird. Es wird dann versuchen, einen künstlichen Modul-Header zu erstellen, der auf den in der Variable headerdirs aufgeführten Headern basiert.

Für Qt-Dokumentationsprojekte stellt das Build-System QDoc normalerweise die korrekten Include-Pfade zur Verfügung, um den Modul-Header zu finden, vorausgesetzt, die Variable project ist korrekt gesetzt. Die Variable moduleheader bietet einen alternativen Dateinamen, nach dem QDoc suchen kann.

Wenn das Projekt keine C++-Dokumentation enthält, sollte QDoc angewiesen werden, die Erzeugung eines PCH zu überspringen, indem moduleheader auf einen leeren String gesetzt wird:

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

Siehe auch includepaths und project.

natürlicheSprache

Die Variable naturallanguage gibt die natürliche Sprache an, die für die von QDoc erzeugte Dokumentation verwendet wird.

naturallanguage = zh-Hans

Standardmäßig ist die natürliche Sprache en für die Kompatibilität mit älterer Dokumentation.

QDoc fügt die Informationen über die natürliche Sprache mit den Attributen lang und xml:lang in das von ihm erzeugte HTML ein.

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

Navigation

Die navigation Untervariablen, falls definiert, legen die Startseite, die Landing Page, die C++ Klassen Seite und die QML Typen Seite fest, die in der generierten Navigationsleiste für jede Seite sichtbar sind.

In einem Projekt mit mehreren Unterprojekten (z.B. Qt-Module) definiert jedes Unterprojekt typischerweise seine eigene Landing Page, während die gleiche Home Page für alle Unterprojekte verwendet wird.

Untervariablen

Zum 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 Item QML type:

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

outputdir

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

outputdir = $QTDIR/doc/html

legt die generierte Qt-Referenzdokumentation in $QTDIR/doc/html ab. Zum Beispiel befindet sich die Dokumentation der Klasse QWidget in

$QTDIR/doc/html/qwidget.html

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

outputencoding

Die Variable outputencoding gibt die Kodierung an, die für die von QDoc erzeugte Dokumentation verwendet wird.

outputencoding = UTF-8

Standardmäßig ist die Ausgabekodierung ISO-8859-1 (Latin1) für die Kompatibilität mit älterer Dokumentation. Bei der Erstellung von Dokumentation für einige Sprachen, insbesondere für nicht-europäische Sprachen, ist dies nicht ausreichend und eine Kodierung wie UTF-8 ist erforderlich.

QDoc kodiert HTML unter Verwendung dieser Kodierung und erzeugt die korrekten Deklarationen, um den Browsern anzuzeigen, welche Kodierung verwendet wird. Die Konfigurationsvariable naturallanguage sollte ebenfalls angegeben werden, um den Browsern einen vollständigen Satz von Zeichenkodierungs- und Sprachinformationen zu liefern.

Siehe auch outputencoding und naturallanguage.

outputformats

Die Variable outputformats gibt das/die Format(e) der erzeugten Dokumentation an.

Seit Qt 5.11 unterstützt QDoc die Formate HTML und WebXML; seit Qt 5.15 kann es die Dokumentation auch in DocBook erzeugen. Wenn keine outputformats angegeben wird, erzeugt QDoc die Dokumentation in HTML (das Standardformat). Alle Ausgabeformate können angegeben werden, mit eigenen Ausgabeverzeichnissen und anderen Einstellungen. Zum Beispiel:

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

Dies erzeugt eine HTML-Dokumentation mit den Standardeinstellungen sowie eine WebXML-Dokumentation im Ausgabeunterverzeichnis webxml.

Ausgabe-Präfixe

Die Variable outputprefixes gibt eine Zuordnung zwischen den Dateitypen und den Präfixen an, die den Ausgabedateinamen in der generierten Dokumentation vorangestellt werden.

QDoc unterstützt das Hinzufügen eines Ausgabepräfixes zu den Dateinamen von QML-Typ-, C++-Klassen-, Namespace- und Header-Datei-Referenzseiten.

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

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

Ebenso werden C++-Typdokumentationsseiten im obigen Beispiel mit dem Präfix components- eingeleitet. Standardmäßig haben C++-Typenseiten kein Präfix.

Ausgabesuffixe

Die Variable outputsuffixes gibt eine Zuordnung zwischen Dateitypen und Suffixen an, die auf den Modul- oder Typnamen anzuwenden sind, wie sie in den Ausgabedateinamen erscheinen.

QDoc unterstützt das Hinzufügen eines Ausgabesuffixes zu den Dateinamen von Modulseiten, QML-Typ-, C++-Klassen-, Namespace- und Header-Datei-Referenzseiten.

Standardmäßig wird kein Suffix verwendet. Das QML-Ausgabesuffix, sofern definiert, wird als Suffix auf den Modulnamen angewendet, wie er in den Dateinamen von QML-Typ- und QML-Modulseiten erscheint.

Dateinamen für C++-Typen enthalten den Modulnamen nicht. Das CPP-Ausgabesuffix, sofern definiert, wird als Suffix für den Typnamen verwendet.

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

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

Ebenso erzeugt QDoc für eine C++-Klasse QFoobar qfoobar-tp.html.

Die Variable outputsuffixes wurde in QDoc 5.6 eingeführt.

qhp

Die qhp Untervariablen werden verwendet, um die Informationen zu definieren, die in Qt Help Projekt (qhp) Dateien geschrieben werden sollen.

Siehe das Kapitel Erstellen von Hilfeprojektdateien für Informationen über diesen Prozess.

Seit QDoc 6.6 bedeutet das Setzen der Basisvariablen qhp auf true, dass eine gültige Hilfeprojektkonfiguration erwartet wird:

qhp = true

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

Um die Warnung abzuschalten, setzen Sie die Variable auf false.

sourcedirs

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

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

Wenn es ausgeführt wird, liest QDoc als erstes die in der Variable header angegebenen Header und die in den in der Variable headerdir angegebenen Verzeichnissen (einschließlich aller Unterverzeichnisse) zu lesen und eine interne Struktur der Klassen und ihrer Funktionen aufzubauen.

Dann liest es die in der Variable sourcesangegebenen Quellen und die in den Verzeichnissen, die in der Variable sourcedirs angegebenen Verzeichnisse (einschließlich aller Unterverzeichnisse), wobei die Dokumentation mit der aus den Header-Dateien gewonnenen Struktur zusammengeführt wird.

Wenn sowohl die sources als auch die sourcedirs Variablen definiert sind, liest QDoc durch beide, zuerst sources dann sourcedirs.

In den angegebenen Verzeichnissen liest QDoc nur die Dateien mit der fileextensions, die in der sources.fileextensions Variable angegeben ist. Die Dateien, die durch sources angegebenen Dateien werden unabhängig von ihren Dateierweiterungen gelesen.

Siehe auch sources und sources.fileextensions.

sourceencoding

Die Variable sourceencoding gibt die Kodierung an, die für den Quellcode und die Dokumentation verwendet wird.

sourceencoding = UTF-8

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

Obwohl QDoc die Kodierung zum Lesen von Quell- und Dokumentationsdateien verwendet, können Beschränkungen von C++ Compilern die Verwendung von Nicht-ASCII-Zeichen in Quellcode-Kommentaren verhindern. In solchen Fällen ist es möglich, die API-Dokumentation vollständig in Dokumentationsdateien zu schreiben.

Siehe auch naturallanguage und outputencoding.

Quellen

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

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

Bei der Verarbeitung der Variable sources verhält sich QDoc genauso wie bei der Verarbeitung der Variable sourcedirs. Weitere Informationen finden Sie unter der sourcedirs-Variable.

Siehe auch sourcedirs.

sources.fileextensions

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

Bei der Verarbeitung der Quelldateien, die in der Variable sourcedirs angegebenen Quelldateien, liest QDoc nur die Dateien mit den in der Variable sources.fileextensions angegebenen Dateierweiterungen. Auf diese Weise vermeidet QDoc, Zeit mit dem Lesen irrelevanter Dateien zu verbringen.

Die Standard-Erweiterungen sind *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml und *.qdoc.

Die Erweiterungen werden als Standard-Wildcard-Ausdrücke angegeben. Sie können dem Filter eine Dateierweiterung mit '+=' hinzufügen. Zum Beispiel:

sources.fileextensions += *.CC

Siehe auch Sourcedirs und Quellen.

falsche

Die Variable spurious schließt bestimmte QDoc-Warnungen von der Ausgabe aus. Die Warnungen werden mit Standard-Wildcard-Ausdrücken angegeben.

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

stellt sicher, dass Warnungen, die mit einem dieser Ausdrücke übereinstimmen, nicht Teil der Ausgabe sind, wenn QDoc läuft. Zum Beispiel würde die folgende Warnung von der Ausgabe ausgenommen werden:

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

syntaxhighlighting

Die Variable syntaxhighlighting gibt an, ob QDoc eine Syntaxhervorhebung für Quellcode, der in der Dokumentation zitiert wird, durchführen soll.

syntaxhighlighting = true

wird die Syntaxhervorhebung für alle unterstützten Programmiersprachen aktivieren.

tabsize

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

tabsize = 4

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

tagfile

Die Variable tagfile gibt die Doxygen-Tag-Datei an, die bei der HTML-Generierung geschrieben wird.

Version

Die Variable version gibt die Versionsnummer der dokumentierten Software an.

version = 5.6.0

Wenn eine Versionsnummer angegeben wird (unter Verwendung der version oder versionsym Variablen in einer .qdocconf Datei), ist sie über den entsprechenden \version Befehl 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 der version oder versionsym Variablen in einer .qdocconf Datei), ist sie über den entsprechenden \version Befehl für die Verwendung in der Dokumentation zugänglich.

Siehe auch \version.

warninglimit

Die Variable warninglimit legt die maximale Anzahl der erlaubten Dokumentationswarnungen fest. Wenn dieses Limit überschritten wird, fährt QDoc normal fort, beendet sich aber mit der Anzahl der Warnungen als Fehlercode. Wenn der Grenzwert nicht überschritten wurde oder warninglimit nicht definiert wurde, wird der QDoc-Prozess mit 0 beendet, vorausgesetzt, dass keine anderen kritischen Fehler aufgetreten sind.

Wenn warninglimit auf 0 gesetzt wird, bedeutet dies, dass der Prozess bei jeder Warnung fehlschlägt.

Zum Beispiel,

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