Elemente miteinander verknüpfen

Mit den Befehlen zum Herstellen von Beziehungen lässt sich festlegen, in welcher Beziehung ein dokumentiertes Element zu einem anderen dokumentierten Element steht. Einige Beispiele:

• Diese Funktion ist eine Überladung einer anderen Funktion.
• Diese Funktion ist eine Neuimplementierung einer anderen Funktion.
• Dieses `typedef` steht in Zusammenhang mit einer Klasse oder einer Header-Datei.

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

Befehle

\inherits

Der Befehl „ \inherits “ dient dazu, zu dokumentieren, dass ein QML-Typ von einem anderen QML-Typ erbt. Er muss in den \qmltype Kommentar des ererbenden Elements enthalten sein. Das Argument ist der Name des geerbten QML-Typs, optional ergänzt um einen 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 auf der Referenzseite für das Element ` PauseAnimation ` ein:

Erbt von Animation

Bei der direkten Dokumentation von QML-Typen in einer .qml-Datei ist der Befehl „ \inherits “ normalerweise nicht erforderlich, da QDoc den Basistyp anhand der QML-Syntax erkennen kann. Ist ein „ \inherits “-Befehl vorhanden, überschreibt dieser die automatische Erkennung des Basistyps.

\overload

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

So funktioniert es

Wenn Sie mehrere C++-Funktionen mit demselben Namen (Überladungen) haben, die ähnliche Aufgaben mit unterschiedlichen Parametern ausführen, verwenden Sie \overload , um 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 unterdrücken automatisch Warnungen wegen fehlender Parameter, da sie auf die Dokumentation der Hauptfunktion verweisen.

Grundlegende Verwendung

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

Verweis auf die Hauptfunktion

Fügen Sie den Funktionsnamen hinzu, um einen Link zur Hauptfunktion zu erstellen:

/*!
    \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 anhand der aktuellen Klasse oder des aktuellen Namensraums.

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 dienen soll, 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.
• Der Text „Diese Funktion überlädt …“ darf nicht angezeigt werden.
• Dienen als Linkziel für andere Überladungen.

Verwenden Sie „\overload “ vorrangig, wenn die wichtigste Überladung von der automatischen Auswahl von QDoc abweicht oder wenn Sie ein einheitliches Verlinkungsverhalten benötigen.

\reimp

Der Befehl „ \reimp “ dient dazu, anzugeben, dass eine Funktion eine Neuimplementierung einer virtuellen Funktion ist, ohne dass zusätzliche Dokumentation erforderlich ist.

Standardmäßig lässt QDoc eine neu implementierte virtuelle Funktion in der Klassenreferenz weg, sofern 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 erscheint in der Dokumentation ein Link zur Basisfunktion QAbstractButton::nextCheckState().

\relates

Der Befehl ` \relates ` dient dazu, die Dokumentation einer Entität (einer Funktion, eines Makros, eines `typedef`, einer `enum` oder einer Variablen) in eine Klasse, einen Namensraum oder eine Header-Datei einzubinden. Das Argument ist der Name der Klasse, des Namensraums oder der Header-Datei, auf die sich die Entität bezieht.

Bezieht sich das Argument auf einen Template-Typ, verwenden Sie bitte nur den Typnamen (ohne Template-Parameter).

/*!
    \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 zu dieser Funktion ist auf der Referenzseite für die Klasse ` QChar` unter dem Abschnitt „Verwandte Nicht-Mitglieder“ aufgeführt.