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... und false, wenn..." - für Eigenschaften, die mit read-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.