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. Der Befehl \since gibt die Versionsnummer an, in der eine Funktion oder Klasse zum ersten Mal erschienen ist. Der Befehl \qmlabstract dient der Kennzeichnung eines QML-Typs als abstrakte Basisklasse.

\abstract und \qmlabstract

\abstractist ein Synonym für den Befehl \qmlabstract. Fügen Sie diesen Befehl in den \qmltype Kommentar 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.

Normalerweise, wenn ein QML-Typ mit \qmlabstractmarkiert ist, wird er auch mit \internal markiert, 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 markiert einen dokumentierten \page als Dokumentation zur Lizenzvergabe.

Der Befehl \generatelist annotatedattributions erzeugt eine kommentierte Liste aller Seiten mit Lizenzzuschreibungen 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 Zeichenkette 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 \class Befehl verwenden.

\compares nimmt eines der folgenden Argumente an:

• strong
• partial
• weak
• equality

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

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 markieren. 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, sehen Sie auf der Referenzseite für den Typ State.

\qmlenumeratorsfrom

Verwenden Sie den \qmlenumeratorsfrom Befehl 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 Enumerator 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 die Referenzdokumentation einer C++-Klasse, eines Namespaces oder einer Header-Datei erzeugt wird.

Standardmäßig dokumentiert QDoc eine \class SomeClass, die mit einer folgenden Include-Anweisung 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 das zugehörige Element veraltet ist und in neuem Code nicht mehr verwendet werden sollte.

Der Befehl \deprecated benötigt zwei optionale Argumente:

• Eine Version in eckigen Klammern (z.B. [6.2]).
• Eine Zeichenkette mit weiteren Informationen, z.B. eine vorgeschlagene Ersetzung.

Wenn QDoc die Referenzdokumentation für eine Klasse generiert, erstellt und verlinkt es eine separate Seite, die veraltete Member dokumentiert. Es ist gute Praxis, eine gleichwertige Alternative vorzuschlagen.

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

\internal

Der Befehl \internal zeigt an, dass das dokumentierte Element 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

Verwenden Sie den Befehl \modulestate innerhalb eines \module oder \qmlmodule Themas, um eine benutzerdefinierte Modulstatusbeschreibung zu erstellen.

Der Befehl benötigt ein Argument, das den Zustand des Moduls beschreibt. Zum Beispiel:

/*!
    \module QtFoo
    \modulestate Experimental
*/

QDoc fügt diese Information dann auf der Modulseite ein:

Dieses Modul befindet sich im experimentellen Zustand.

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

Siehe auch \preliminary.

\preliminary

Der Befehl \preliminary zeigt an, dass das dokumentierte Element noch in der Entwicklung ist.

Der Befehl muss in einer eigenen Zeile stehen.

Der Befehl \preliminary verweist auf eine Meldung in der Dokumentation und kennzeichnet das Element als vorläufig, wenn es 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 \readonly Befehl 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 markieren.

Siehe auch Das Eigenschaftssystem.

\since

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

Wenn das an \since übergebene Argument keine Leerzeichen enthält, wird angenommen, dass es sich um eine Kurzschreibweise für den Produktnamen handelt, und QDoc wird in der generierten Ausgabe der Version den Wert von productname voranstellen. Wenn die Variable productname undefiniert ist, generiert QDoc nur die Versionszeichenfolge.

Das Argument kann auch explizit den Produktnamen enthalten:

\since MyFramework 2.0

In diesem Fall werden die Argumente (Produkt 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, es sei denn, \since wird explizit in der Typdokumentation verwendet.

Since-Klausel

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

Siehe auch \value und ignoresince.

\wrapper

Der Befehl \wrapper, wenn er in einer C++-Klassendokumentation verwendet wird, kennzeichnet 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.