Dinge in Beziehung setzen

Mit den Befehlen zum Zuordnen können Sie angeben, wie ein dokumentiertes Element mit einem anderen dokumentierten Element in Beziehung steht. Einige Beispiele:

• Diese Funktion ist eine Überladung einer anderen Funktion.
• Diese Funktion ist eine Reimplementierung einer anderen Funktion.
• Dieses Typedef steht in Beziehung zu einer Klasse oder Header-Datei.

Es gibt auch einen Befehl, um zu dokumentieren, dass ein QML-Typ einen anderen QML-Typ erbt.

Befehle

\inherits

Der Befehl \inherits dient zur Dokumentation, dass ein QML-Typ einen anderen QML-Typ erbt. Er muss in den Kommentar des vererbenden Elements aufgenommen werden \qmltype Kommentar enthalten sein. Das Argument ist der Name des geerbten QML-Typs, optional qualifiziert mit einem QML-Modulnamen.

/*!
    \qmltype PauseAnimation
    \inqmlmodule QtQuick
    \nativetype QDeclarativePauseAnimation
    \ingroup qml-animation-transition
    \since 4.7
    \inherits Animation
    \brief The PauseAnimation element provides a pause for an animation.

    When used in a SequentialAnimation, PauseAnimation is a step
    when nothing happens, for a specified duration.

    A 500ms animation sequence, with a 100ms pause between two animations:

    SequentialAnimation {
        NumberAnimation { ... duration: 200 }
        PauseAnimation { duration: 100 }
        NumberAnimation { ... duration: 200 }
    }

    \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
*/

QDoc fügt diese Zeile in die Referenzseite für das Element PauseAnimation ein:

Vererbt Animation

Wenn ein QML-Typ direkt in einer .qml-Datei dokumentiert wird, ist der \inherits Befehl normalerweise nicht erforderlich, da QDoc den Basistyp aus der QML-Syntax erkennen kann. Falls vorhanden, wird ein \inherits Befehl diese automatische Erkennung des Basistyps außer Kraft setzen.

\overload

Verwenden Sie den \overload Befehl, um C++ Funktionsüberladungen zu markieren. Dieser Befehl muss in einer eigenen Zeile im Dokumentationskommentar erscheinen.

Wie es funktioniert

Wenn Sie mehrere C++-Funktionen mit demselben Namen (Überladungen) haben, die ähnliche Aufgaben mit unterschiedlichen Parametern erfüllen, verwenden Sie \overload um eine sich wiederholende Dokumentation zu vermeiden. Funktionen ohne \overload erfordern eine vollständige Dokumentation. Funktionen mit \overload können sich auf ihre spezifischen Unterschiede konzentrieren.

Funktionen, die mit \overload gekennzeichnete Funktionen unterdrücken automatisch Warnungen vor fehlenden Parametern, da sie auf die Dokumentation der Hauptfunktion verweisen.

Grundlegende Verwendung

/*!
    \overload
    Brief description of what makes this overload different.
*/

Verlinkung auf die Hauptfunktion

Fügen Sie den Funktionsnamen hinzu, um eine Verknüpfung mit der Primärfunktion herzustellen:

/*!
    \overload functionName()
    Brief description of what makes this overload different.
*/

Verwenden Sie entweder qualifizierte Namen (ClassName::functionName()) oder unqualifizierte Namen (functionName()). QDoc qualifiziert unqualifizierte Namen automatisch unter Verwendung der aktuellen Klasse oder des aktuellen Namespaces.

Festlegen einer primären Überladung

Standardmäßig wählt QDoc die primäre Überladung automatisch aus. Um explizit festzulegen, welche Überladung als primäre Überladung dient, verwenden Sie:

/*!
    \overload primary
    Main documentation for this function family.
    Document all parameters here.
*/

Primäre Überladungen:

• Enthalten die Dokumentation der Hauptfunktion.
• Erfordern eine vollständige Parameterdokumentation.
• Zeigen Sie keinen "Diese Funktion überlädt..."-Text an.
• Dienen als Linkziel für andere Überladungen.

Verwenden Sie \overload primary, wenn die wichtigste Überladung von QDocs automatischer Auswahl abweicht, oder wenn Sie ein konsistentes Linkverhalten benötigen.

\reimp

Der \reimp Befehl zeigt an, dass eine Funktion eine Reimplementierung einer virtuellen Funktion ist, ohne dass eine zusätzliche Dokumentation erforderlich ist.

Standardmäßig lässt QDoc eine reimplementierte virtuelle Funktion in der Klassenreferenz aus, wenn sie nicht dokumentiert ist. Dieser Befehl stellt sicher, dass eine ansonsten undokumentierte Funktion aufgenommen wird.

Der Befehl muss in einer eigenen Zeile stehen.

/*!
    \reimp
*/
void QToolButton::nextCheckState()
{
    Q_D(QToolButton);
    if (!d->defaultAction)
        QAbstractButton::nextCheckState();
    else
        d->defaultAction->trigger();
}

Diese Funktion wird nicht in die Dokumentation aufgenommen. Stattdessen wird in der Dokumentation ein Verweis auf die Basisfunktion QAbstractButton::nextCheckState() erscheinen.

\relates

Der Befehl \relates dient dazu, die Dokumentation einer Entität (eine Funktion, ein Makro, ein Typedef, ein Enum oder eine Variable) in eine Klasse, einen Namespace oder eine Header-Datei aufzunehmen. Das Argument ist der Name der Klasse, des Namespaces oder des Headers, auf den sich die Entität bezieht.

Wenn sich das Argument auf einen Schablonentyp bezieht, verwenden Sie nur den Typnamen (ohne Schablonenparameter).

/*!
    \relates QChar

    Reads a char from the stream \a in into char \a chr.

    \sa {Format of the QDataStream operators}
*/
QDataStream &operator>>(QDataStream &in, QChar &chr)
{
    quint16 u;
    in >> u;
    chr.unicode() = ushort(u);
    return in;
}

Die Dokumentation für diese Funktion ist auf der Referenzseite für die Klasse QChar enthalten, die unter dem Abschnitt Verwandte Nichtmitglieder aufgeführt ist.