QML-Dokumentationsstil
QDoc kann QML-Typen, die als C++-Klassen definiert sind, und QML-Typen, die in .qml
-Dateien definiert sind, verarbeiten. Bei C++-Klassen, die als QML-Typen dokumentiert sind, befinden sich die QDoc-Kommentare in der Datei .cpp
, während die in QML definierten QML-Typen in der Datei .qml
stehen. Die C++-Klassen müssen auch mit den QML-Themenbefehlen dokumentiert werden:
- \qmlattachedproperty
- \qmlattachedsignal
- \qmlvaluetype
- \qmltype
- \qmlmethod
- \qmlEigenschaft
- \qmlsignal
- \qmlmodule
- \inqmlmodule
- \nativetype
Bei QML-Typen, die in .qml
-Dateien definiert sind, analysiert QDoc die QML und bestimmt die Eigenschaften, Signale und den Typ innerhalb der QML-Definition. Der QDoc-Block muss dann unmittelbar über der Deklaration stehen. Für QML-Typen, die in C++ implementiert sind, gibt QDoc Warnungen aus, wenn die C++-Klassendokumentation nicht vorhanden ist. Die Klassendokumentation kann als intern markiert werden, wenn es sich nicht um eine öffentliche API handelt.
QML-Typen
Der Befehl \qmltype dient der Dokumentation von QML-Typen.
\qmltype TextEdit \nativetype QQuickTextEdit \inqmlmodule QtQuick \ingroup qtquick-visual \ingroup qtquick-input \inherits Item \brief Displays multiple lines of editable formatted text The TextEdit item displays a block of editable, formatted text. It can display both plain and rich text. For example: \qml TextEdit { width: 240 text: "<b>Hello</b> <i>World!</i>" font.family: "Helvetica" font.pointSize: 20 color: "blue" focus: true } \endqml \image declarative-textedit.gif ... omitted detailed description \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}
Der Befehl \nativetype akzeptiert die C++-Klasse, die den QML-Typ implementiert, als Argument. Für Typen, die in QML implementiert sind, ist dies nicht erforderlich.
Die Kurzbeschreibung bietet eine Zusammenfassung für den QML-Typ. Die Kurzbeschreibung muss nicht aus einem vollständigen Satz bestehen und kann mit einem Verb beginnen. QDoc fügt die Kurzbeschreibung an den QML-Typ in Tabellen und generierten Listen an.
\qmltype ColorAnimation \brief Animates changes in color values
Hier sind einige alternative Verben für die Kurzbeschreibung:
- "Provides..."
- "Spezifiziert..."
- "Describes..."
Die ausführliche Beschreibung folgt der Kurzbeschreibung und kann Bilder, Snippets und Links zu anderer Dokumentation enthalten.
Eigenschaften
Die Eigenschaftsbeschreibung konzentriert sich auf die Funktion der Eigenschaft und kann den folgenden Stil verwenden:
Die Eigenschaftsdokumentation beginnt in der Regel mit "Diese Eigenschaft...", aber für bestimmte Eigenschaften sind die folgenden Ausdrücke üblich:
- "Diese Eigenschaft enthält..."
- "Diese Eigenschaft beschreibt..."
- "Diese Eigenschaft repräsentiert..."
- "Gibt
true
zurück, wenn... undfalse
, wenn..." - für Eigenschaften, die mitread-only
gekennzeichnet sind. - "Setzt die..." - für Eigenschaften, die einen Typ konfigurieren.
Dokumentation von Signalen und Handlern
QML-Signale werden entweder in der QML-Datei oder in der C++-Implementierung mit dem Befehl \qmlsignal dokumentiert. Die Signaldokumentation muss die Bedingung für das Aussenden des Signals enthalten, den entsprechenden Signalhandler erwähnen und dokumentieren, ob das Signal einen Parameter akzeptiert.
/* This signal is emitted when the user clicks the button. A click is defined as a press followed by a release. The corresponding handler is \c onClicked. */ signal clicked()
Dies sind die möglichen Dokumentationsstile für Signale:
- "Dieses Signal wird ausgelöst, wenn..."
- "Ausgelöst, wenn..."
- "Emitted when..."
Methoden und QML-Funktionen
Typischerweise wird die Funktionsdokumentation unmittelbar vor der Implementierung der Funktion in der Datei .cpp
eingefügt. Der Topic-Befehl für Funktionen lautet \fn. Bei Funktionen in QML muss die Dokumentation unmittelbar über der Funktionsdeklaration stehen.
Die Funktionsdokumentation beginnt mit einem Verb, das die Operation angibt, die die Funktion ausführt.
/* \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1) Deletes the content at \a index from the model. \sa clear() */ void QQuickListModel::remove(QQmlV8Function *args)
Einige gängige Verben für die Funktionsdokumentation:
- "Kopiert..." - für Konstruktoren
- "Zerstört..." - für Destruktoren
- "Gibt zurück..." - für Accessor-Funktionen
Die Funktionsdokumentation muss dokumentieren:
- den Rückgabetyp
- die Parameter
- die Aktionen der Funktionen
Der Befehl \a kennzeichnet den Parameter in der Dokumentation. Die Dokumentation des Rückgabetyps sollte auf die Dokumentation des Typs verweisen oder im Falle von booleschen Werten mit dem Befehl \c gekennzeichnet sein.
Aufzählungen
QML-Aufzählungen werden als QML-Eigenschaften mit dem Befehl \qmlproperty dokumentiert. Der Typ der Eigenschaft ist enumeration
. Verwenden Sie den Befehl \value, um die Aufzählungswerte zu dokumentieren. Fügen Sie den Typnamen als Präfix zu jedem Wert hinzu, getrennt durch einen Punkt (.), da QDoc dies nicht automatisch tut.
/*! \qmlproperty enumeration QtQuick2::Text::font.weight Sets the font's weight. The weight can be one of: \value Font.Light \value Font.Normal The default \value Font.DemiBold \value Font.Bold \value Font.Black
Der QDoc-Kommentar listet die Werte der Aufzählung auf.
Wenn die Aufzählung in C++ implementiert ist, sollten Sie den Befehl \qmlenumeratorsfrom verwenden. Wenn dies nicht möglich ist, kann die Dokumentation auch direkt auf die entsprechende C++-Aufzählung verweisen. Der QDoc-Kommentar sollte dann jedoch darauf hinweisen, dass es sich um eine C++-Aufzählung handelt.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.