Status

Diese Befehle zeigen an, dass ein dokumentiertes Element einen besonderen Status hat. Das Element könnte als veraltet gekennzeichnet sein, d.h. es wird demnächst überflüssig und ist nicht mehr in der öffentlichen Schnittstelle enthalten. Mit dem Befehl \since wird die Versionsnummer angegeben, in der eine Funktion oder Klasse erstmals erschienen ist. Der Befehl \qmlabstract dient dazu, einen QML-Typ als abstrakte Basisklasse zu kennzeichnen.

\abstract und \qmlabstract

\abstract ist ein Synonym für den Befehl \qmlabstract. Fügen Sie diesen Befehl dem Kommentar \qmltype für einen QML-Typ hinzu, wenn dieser Typ nur als abstrakter Basistyp verwendet werden soll. Wenn ein QML-Typ abstrakt ist, bedeutet dies, dass der QML-Typ nicht instanziiert werden kann. Stattdessen werden die Eigenschaften in seiner öffentlichen API in die Liste der öffentlichen Eigenschaften auf der Referenzseite für jeden QML-Typ aufgenommen, der den abstrakten QML-Typ erbt. Die Eigenschaften werden so dokumentiert, als ob sie Eigenschaften des ererbenden QML-Typs wären.

Wenn ein QML-Typ mit \qmlabstract gekennzeichnet ist, wird er normalerweise auch mit \internal gekennzeichnet, damit seine Referenzseite nicht erzeugt wird. Wenn der abstrakte QML-Typ nicht als intern gekennzeichnet ist, wird er in der Dokumentation eine Referenzseite haben.

\attribution

Der Befehl \attribution kennzeichnet einen dokumentierten \page als Dokumentation zur Lizenzvergabe.

Der Befehl \generatelist annotatedattributions erzeugt eine kommentierte Liste aller Seiten mit Lizenzangaben im Dokumentationsprojekt.

\default

Der Befehl \default wird verwendet, um einen Standardwert für eine QML-Eigenschaft zu dokumentieren. Der Befehl nimmt ein einzelnes Argument entgegen, das in der Dokumentation als Standardwert angezeigt wird.

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

Wenn der Standardwert eine nicht leere Zeichenfolge ist, verwenden Sie Anführungszeichen:

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\compares

Verwenden Sie den Befehl \compares, um die Vergleichsergebnisse für den dokumentierten C++-Typ im Vergleich zu sich selbst zu beschreiben. Sie müssen diesen Befehl in Verbindung mit dem Befehl \class verwenden.

\compares nimmt eines der folgenden Argumente an:

• strong
• partial
• weak
• equality

strong partial und beziehen sich auf die Reihenfolge. bedeutet, dass der Typ nur auf Gleichheit verglichen wird. weak equality

Dieser Befehl wurde in QDoc mit Qt 6.7 eingeführt.

Siehe auch \compareswith.

\compareswith

Verwenden Sie das Befehlspaar \compareswith .. \endcompareswith, um die Vergleichsergebnisse für den dokumentierten C++-Typ im Vergleich zu anderen Typen zu beschreiben. \compareswith nimmt zwei oder mehr Argumente entgegen: eine Vergleichskategorie, gefolgt von einem Typnamen, oder eine durch Leerzeichen getrennte Liste von Typnamen. Alle Textzeilen zwischen den Befehlen \compareswith und \endcompareswith werden als weitere Details betrachtet, die für alle Typen gelten, die dem Argument Vergleichskategorie unterliegen.

Typen, die ein oder mehrere Leerzeichen in ihrem Namen haben, wie z. B. unsigned long, sollten in geschweifte Klammern gesetzt werden.

Zum Beispiel:

/*!
    ...
    \compareswith strong int long {unsigned long} {unsigned int} char
    ...
    \endcompareswith
    ...
*/

Bei Argumenten, die in geschweifte Klammern eingeschlossen sind, werden die führenden und nachgestellten Leerzeichen entfernt. Zum Beispiel: unsigned long und unsigned long sind gleichwertig.

Das Argument für die Vergleichskategorie muss eines der folgenden sein:

• strong
• partial
• weak
• equality

strong partial und beziehen sich auf die Reihenfolge. bedeutet, dass der Typ nur auf Gleichheit verglichen wird. weak equality

Dieser Befehl wurde in QDoc mit Qt 6.7 eingeführt.

Siehe auch \compares.

\qmldefault

Der Befehl \qmldefault dient dazu, eine QML-Eigenschaft als Standardeigenschaft zu kennzeichnen. Das Wort default wird in der Dokumentation der Eigenschaft angezeigt.

/*!
    \qmlproperty list<Change> State::changes
    This property holds the changes to apply for this state.
    \qmldefault

    By default, these changes are applied against the default state. If the state
    extends another state, then the changes are applied against the state being
    extended.
*/

Wie QDoc diese Eigenschaft wiedergibt, ist auf der Referenzseite für den Typ State zu sehen.

\qmlenumeratorsfrom

Verwenden Sie den Befehl \qmlenumeratorsfrom in einem \qmlproperty Thema mit einem Eigenschaftstyp Aufzählung, um automatisch die Dokumentation für Aufzählungszeichen aus einem C++ \enum Thema zu replizieren.

Der Befehl nimmt eine voll qualifizierte C++ Aufzählung als Argument und erzeugt eine Liste von Aufzählungszeichen und deren Beschreibungen.

Standardmäßig wird jedem Aufzähler der Name des Typs vorangestellt, zu dem die Eigenschaft gehört, mit . als Trennzeichen.

Zum Beispiel:

/*!
    \qmlproperty enumeration QtMultimedia::Camera::error
    \qmlenumeratorsfrom QCamera::Error

    //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
*/

Wenn die Aufzählungszeichen in QML unter einem anderen Typnamen registriert sind, kann dieser Name (Präfix) mit dem optionalen Argument in eckigen Klammern angegeben werden:

    \qmlenumeratorsfrom [Errors] QCamera::Error

    //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
\1/

Dieser Befehl wurde in QDoc 6.8 eingeführt.

Siehe auch \qmlproperty, \enum, und \value.

\dontdocument

Der Befehl \dontdocument wird nur in einer dontdocument.qdoc-Datei für ein bestimmtes Modul verwendet. Diese Datei gibt öffentlich deklarierte Klassen oder Strukturen an, die nicht dokumentiert werden sollen. QDoc wird keine Warnungen über fehlende \class-Kommentare für diese Klassen und Strukturen ausgeben.

Nachfolgend finden Sie den \dontdocument-Befehl in der dontdocument.qdoc für Widgets:

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

Der Meta-Befehl \inheaderfile wird verwendet, um die Include-Anweisung zu überschreiben, die für eine C++-Klassen-, Namespace- oder Header-Datei-Referenzdokumentation erzeugt wird.

Standardmäßig dokumentiert QDoc eine \class SomeClass, die mit einem folgenden Include-Statement verfügbar ist:

#include <SomeClass>

Wenn die tatsächliche Include-Anweisung von der Vorgabe abweicht, kann dies wie folgt dokumentiert werden

\class SomeClass
\inheaderfile Tools/SomeClass
...

Siehe auch \class und \headerfile.

\obsolete

Der Befehl \obsolete wird durch den Befehl \deprecated abgelöst.

Dieser Befehl wird nur aus Gründen der Abwärtskompatibilität beibehalten. Er kann in einer zukünftigen Version von QDoc entfernt werden. Verwenden Sie stattdessen den Befehl \deprecated.

Siehe auch \deprecated.

\deprecated

Der Befehl \deprecated zeigt an, dass eine Funktion veraltet ist und nicht mehr in neuem Code verwendet werden sollte. Es gibt keine Garantie dafür, wie lange sie in der Bibliothek bleiben wird.

Der Befehl \deprecated benötigt zwei optionale Argumente:

• Eine Version in eckigen Klammern (z.B. [6.2]).
• Eine Zeichenkette mit weiteren Informationen, z. B. einem Vorschlag für eine Ersetzung.

Wenn QDoc die Referenzdokumentation für eine Klasse generiert, erstellt es eine separate Seite, die die veralteten Funktionen dokumentiert, und verlinkt auf diese. Es ist gute Praxis, eine gleichwertige Funktion als Alternative vorzuschlagen.

/*!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
*/

\intern

Der Befehl \internal zeigt an, dass die referenzierte Funktion nicht Teil der öffentlichen Schnittstelle ist.

Der Befehl muss in einer eigenen Zeile stehen.

QDoc ignoriert sowohl die Dokumentation als auch das dokumentierte Element, wenn es die zugehörige Klassenreferenzdokumentation erstellt.

/*!
    \internal

    Tries to find the decimal separator. If it can't find
    it and the thousand delimiter is != '.' it will try to
    find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
        (const QString &str, int index) const
{
    int dotindex = str.indexOf(delimiter, index);
    if (dotindex == -1 && thousand != dot && delimiter != dot)
        dotindex = str.indexOf(dot, index);
    return dotindex;
}

Diese Funktion wird nicht in die Dokumentation aufgenommen, es sei denn, QDoc wird mit der Kommandozeilenoption -showinternal aufgerufen oder die Umgebungsvariable QDOC_SHOW_INTERNAL ist gesetzt.

\modulestate

Der Befehl \modulestate kann innerhalb eines \module- oder \qmlmodule-Themas verwendet werden, um eine andere Modulstatusbeschreibung als "preliminary" oder " deprecated" anzugeben.

Der Rest der Zeile wird als Argument verwendet, das den Zustand des Moduls beschreibt. Zum Beispiel:

/*!
    \module QtFoo
    \modulestate Technical Preview
*/

QDoc fügt dann diese Informationen auf der Modulseite hinzu:

Dieses Modul befindet sich im Stadium der technischen Vorschau.

In der HTML-Ausgabe erscheint diese Statusinformation auch in der Navigationsleiste (Breadcrumbs) der Referenzseiten für die Mitglieder des Moduls.

\preliminär

Der Befehl \preliminary zeigt an, dass sich eine referenzierte Funktion noch in der Entwicklung befindet.

Der Befehl muss in einer eigenen Zeile stehen.

Der Befehl \preliminary führt zu einer Meldung in der Funktionsdokumentation und kennzeichnet die Funktion als vorläufig, wenn sie in Listen erscheint.

/*!
    \preliminary

    Returns information about the joining type attributes of the
    character (needed for certain languages such as Arabic or
    Syriac).

*/
QChar::JoiningType QChar::joiningType() const
{
    return QChar::joiningType(ucs);
}

\readonly

Der Befehl \readonly wird in Verbindung mit einem \qmlproperty-Befehl verwendet, um die QML-Eigenschaft als schreibgeschützt zu kennzeichnen.

\required

Der Befehl \required wird in Verbindung mit einem \qmlproperty-Befehl verwendet, um die QML-Eigenschaft als erforderlich zu kennzeichnen.

Siehe auch Das Eigenschaftssystem.

\since

Der Befehl \since gibt an, in welchem Minor Release die zugehörige Funktionalität hinzugefügt wurde.

Wenn das an \since übergebene Argument keine Leerzeichen enthält, wird angenommen, dass es sich um eine Versionsnummer für das Qt-Projekt handelt, und QDoc wird ihr in der generierten Ausgabe das Präfix 'Qt' voranstellen. Das Argument kann auch explizit den Projektnamen enthalten:

\since MyFramework 2.0

In diesem Fall werden die Argumente (Projekt und Version) so verwendet, wie sie sind.

Vererbung von Since-Informationen

Seit QDoc Version 6.5 erben C++-Klassen und QML-Typen die \since-Anweisung von ihrem jeweiligen Modul oder QML-Modul, sofern \since nicht explizit in der Typdokumentation verwendet wird.

Since-Klausel

Der Befehl \value erlaubt eine optionale since-Klausel, die in eckigen Klammern eingeschlossen ist, unmittelbar nach der Befehlszeichenfolge. Dies wird verwendet, um bestimmte C++-Enum-Werte mit since-Informationen zu kennzeichnen.

Siehe auch \value und ignoresince.

\wrapper

Der Befehl \wrapper kennzeichnet, wenn er in einer C++-Klassendokumentation verwendet wird, die Klasse als Wrapper, der Zugriff auf eine Nicht-Qt-API bietet. Dieser Befehl wird verwendet, um Warnungen zu unterdrücken, die andernfalls für Mitglieder einer solchen Klasse erzeugt werden könnten.