QML-Dokumentationsstil

QDoc kann sowohl als C++-Klassen definierte QML-Typen als auch in „ .qml “-Dateien definierte QML-Typen verarbeiten. Für C++-Klassen, die als QML-Typen dokumentiert sind, befinden sich die QDoc-Kommentare in der Datei „ .cpp “, während in QML definierte QML-Typen in der Datei „ .qml “ zu finden sind. Die C++-Klassen müssen zudem mit den folgenden QML-Themenbefehlen dokumentiert werden:

• \qmlattachedmethod
• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \qmlmodule
• \inqmlmodule
• \nativetype

Bei QML-Typen, die in „ .qml “-Dateien definiert sind, analysiert QDoc das QML und ermittelt die Eigenschaften, Signale und den Typ innerhalb der QML-Definition. Der QDoc-Block muss sich dann unmittelbar über der Deklaration befinden. Bei in C++ implementierten QML-Typen gibt QDoc Warnungen aus, wenn die Dokumentation der C++-Klasse fehlt. Die Klassendokumentation kann als „internal“ gekennzeichnet werden, wenn es sich nicht um eine öffentliche API handelt.

QML-Typen

Der \qmltype Befehl 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 \nativetype Befehl akzeptiert die C++-Klasse, die den QML-Typ implementiert, als Argument. Bei in QML implementierten Typen ist dies nicht erforderlich.

Die Kurzbeschreibung liefert eine Zusammenfassung des QML-Typs. Die Kurzbeschreibung muss kein vollständiger Satz sein und kann mit einem Verb beginnen. QDoc fügt die Kurzbeschreibung in Tabellen und generierten Listen an den QML-Typ an.

\qmltype ColorAnimation
\brief Animates changes in color values

Hier sind einige alternative Verben für die Kurzbeschreibung:

• „Bietet …“
• „Spezifiziert …“
• „Beschreibt …“

Die ausführliche Beschreibung folgt auf die Kurzbeschreibung und kann Bilder, Codeausschnitte und Links zu weiterer Dokumentation enthalten.

Eigenschaften

Die Beschreibung der Eigenschaft konzentriert sich darauf, was die Eigenschaft bewirkt, und kann im folgenden Stil verfasst sein:

Die Eigenschaftsdokumentation beginnt in der Regel mit „Diese Eigenschaft…“, doch für bestimmte Eigenschaften sind folgende Formulierungen ü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 den …“ – für Eigenschaften, die einen Typ konfigurieren.

Dokumentation zu Signalen und Handlern

QML-Signale werden entweder in der QML-Datei oder in der C++-Implementierung mit dem \qmlsignal Befehl dokumentiert. Die Signaldokumentation muss die Bedingung für die Aussendung des Signals enthalten, den entsprechenden Signal-Handler nennen 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 …“
• „Ausgelöst, wenn …“

Methoden und QML-Funktionen

In der Regel steht die Funktionsdokumentation unmittelbar vor der Implementierung der Funktion in der Datei „ .cpp “. Der Befehl „topic“ 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 von der Funktion ausgeführte Operation angibt.

/*
    \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
• „Löscht …“ – für Destruktoren
• „Gibt zurück...“ – für Zugriffsfunktionen

Die Funktionsdokumentation muss Folgendes dokumentieren:

• den Rückgabetyp
• die Parameter
• die Funktionen der Funktionen

Der \a Befehl markiert den Parameter in der Dokumentation. Die Dokumentation des Rückgabetyps sollte auf die Typdokumentation verweisen oder im Falle von Booleschen Werten mit dem \c Befehl markiert werden.

Aufzählungen

QML-Aufzählungen werden als QML-Eigenschaften mit dem \qmlenum Befehl. Verwenden Sie den \value Befehl, um die Enumerationswerte zu dokumentieren. Fügen Sie jedem Wert den Typnamen als Präfix 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 die Verwendung des \qmlenumeratorsfrom Befehl. Ist dies nicht möglich, 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.