Status

Diese Befehle dienen dazu, anzugeben, dass ein dokumentiertes Element einen besonderen Status hat. Das Element könnte als veraltet markiert sein, d. h., es wird bald ausgemustert und ist nicht mehr in der öffentlichen Schnittstelle enthalten. Der \since Befehl dient dazu, die Versionsnummer anzugeben, in der eine Funktion oder Klasse erstmals erschienen ist. Der \qmlabstract Befehl dient dazu, einen QML-Typ als abstrakte Basisklasse zu kennzeichnen.

\abstract und \qmlabstract

\abstractist ein Synonym für den Befehl „ \qmlabstract “. Fügen Sie diesen Befehl in den \qmltype Kommentar eines QML-Typs ein, wenn dieser Typ ausschließlich als abstrakter Basistyp verwendet werden soll. Ist ein QML-Typ abstrakt, bedeutet dies, dass er nicht instanziiert werden kann. Stattdessen werden die Eigenschaften in seiner öffentlichen API in die Liste der öffentlichen Eigenschaften auf der Referenzseite jedes QML-Typs aufgenommen, der den abstrakten QML-Typ erbt. Die Eigenschaften werden so dokumentiert, als wären sie Eigenschaften des ererbenden QML-Typs.

Normalerweise wird ein QML-Typ, der mit \qmlabstract, wird er auch mit \internal markiert, sodass keine Referenzseite dafür generiert wird. Ist der abstrakte QML-Typ nicht als „internal“ gekennzeichnet, verfügt er über eine Referenzseite in der Dokumentation.

\attribution

Der Befehl „ \attribution “ kennzeichnet eine dokumentierte \page als Dokumentation zur Lizenzangabe.

Der Befehl „\generatelist annotatedattributions“ generiert eine kommentierte Liste aller Seiten mit Lizenzangaben im Dokumentationsprojekt.

\default

Der Befehl „ \default “ dient dazu, 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 beim Vergleich mit sich selbst zu beschreiben. Sie müssen diesen Befehl in Verbindung mit dem \class Befehl verwenden.

\compares akzeptiert eines der folgenden Argumente:

• 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 mit Qt 6.7 in QDoc eingeführt.

Siehe auch \compareswith.

\compareswith

Verwenden Sie die Befehlspaare „ \compareswith .. \endcompareswith “, um die Vergleichsergebnisse für den dokumentierten C++-Typ im Vergleich zu anderen Typen zu beschreiben. Der Befehl „ \compareswith “ erwartet zwei oder mehr Argumente: eine Vergleichskategorie, gefolgt von einem Typnamen oder einer durch Leerzeichen getrennten Liste von Typnamen. Alle Textzeilen zwischen den Befehlen „ \compareswith “ und „ \endcompareswith “ gelten als weitere Details, die für alle Typen gelten, die dem Argument der Vergleichskategorie unterliegen.

Typen, deren Name ein oder mehrere Leerzeichen enthält, wie beispielsweise „ unsigned long “, sollten in geschweifte Klammern gesetzt werden.

Beispiel:

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

Bei in geschweifte Klammern gesetzten Argumenten werden führende und nachfolgende Leerzeichen entfernt. So sind beispielsweise „ unsigned long “ und „ unsigned long “ gleichbedeutend.

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

• 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 mit Qt 6.7 in QDoc eingeführt.

Siehe auch \compares.

\qmldefault

Der Befehl „ \qmldefault “ dient dazu, eine QML-Eigenschaft als Standard-Eigenschaft zu kennzeichnen. In der Dokumentation der Eigenschaft wird der Begriff „ default “ 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.
*/

Sehen Sie sich an, wie QDoc diese Eigenschaft auf der Referenzseite für den Typ „ State “ darstellt.

\qmlenumeratorsfrom

Verwenden Sie den Befehl „ \qmlenumeratorsfrom “ in einem \qmlproperty Thema mit einer Aufzählung als Eigenschaftstyp verwenden, um die Dokumentation für die Elemente der Aufzählung automatisch aus einem C++-Thema \enum Thema zu übernehmen.

Der Befehl nimmt eine vollständig qualifizierte C++-Enumeration als Argument entgegen und generiert eine Liste der Enumeratoren und ihrer Beschreibungen.

Standardmäßig wird jedem Enumerator der Typname vorangestellt, zu dem die Eigenschaft gehört, wobei „ . “ als Trennzeichen dient.

Beispiel:

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

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

Wenn die Enumeratoren unter einem anderen Typnamen in QML registriert sind, kann dieser Name (Präfix) mithilfe des optionalen Arguments 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, sowie \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 gibt für diese Klassen und Strukturen keine Warnungen wegen fehlender „ \class “-Kommentare aus.

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

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

Der Meta-Befehl „ \inheaderfile “ dient dazu, die für eine C++-Klasse, einen Namespace oder eine Header-Datei generierte Include-Anweisung in der Referenzdokumentation zu überschreiben.

Standardmäßig dokumentiert QDoc einen ` \class SomeClass ` so, dass er über eine folgende `include`-Anweisung verfügbar ist:

#include <SomeClass>

Wenn die tatsächliche `include`-Anweisung vom Standard abweicht, kann dies wie folgt dokumentiert werden:

\class SomeClass
\inheaderfile Tools/SomeClass
...

Siehe auch \class und \headerfile.

\obsolete

Der Befehl „ \obsolete “ wurde durch den Befehl „ \deprecated “ ersetzt.

Dieser Befehl wird ausschließlich aus Gründen der Abwärtskompatibilität beibehalten. Er wird möglicherweise in einer zukünftigen Version von QDoc entfernt. Verwenden Sie stattdessen den Befehl „ \deprecated “.

Siehe auch \deprecated.

\deprecated

Der Befehl „ \deprecated “ dient dazu, anzugeben, dass das zugehörige Element veraltet ist und in neuem Code nicht mehr verwendet werden sollte.

Der Befehl „ \deprecated “ akzeptiert zwei optionale Argumente:

• Eine Versionsnummer in eckigen Klammern (z. B. [6.2]).
• Eine Zeichenkette mit weiteren Informationen, zum Beispiel einem vorgeschlagenen Ersatz.

Beim Erstellen der Referenzdokumentation für eine Klasse erstellt QDoc eine separate Seite, auf der veraltete Mitglieder dokumentiert werden, und verlinkt darauf. Es empfiehlt sich, eine gleichwertige Alternative vorzuschlagen.

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

\internal

Der Befehl „ \internal “ gibt 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 bei der Erstellung der zugehörigen Klassenreferenzdokumentation.

/*!
    \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 Befehlszeilenoption „ -showinternal “ aufgerufen oder die Umgebungsvariable „ QDOC_SHOW_INTERNAL “ ist gesetzt.

\modulestate

Verwenden Sie den Befehl „ \modulestate “ innerhalb eines Themas vom Typ „ \module “ oder „ \qmlmodule “, um eine benutzerdefinierte Beschreibung des Modulzustands bereitzustellen.

Der Befehl erwartet ein Argument, das den Status des Moduls beschreibt. Beispiel:

/*!
    \module QtFoo
    \modulestate Experimental
*/

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

Dieses Modul befindet sich im Status „Experimentell “.

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

Siehe auch \preliminary.

\preliminary

Der Befehl „ \preliminary “ dient dazu, darauf hinzuweisen, dass sich das dokumentierte Element noch in der Entwicklung befindet.

Der Befehl muss in einer eigenen Zeile stehen.

Der Befehl „ \preliminary “ wird in der Dokumentation zu einem Hinweis erweitert und kennzeichnet das Element in Listen als vorläufig.

/*!
    \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);
}

Seit QDoc-Version 6.12 ist es möglich, den Statusbeschreiber und den Inhalt des generierten Hinweises für mit ` \preliminary` markierte Elemente anzupassen.

Siehe auch preliminary Konfigurationsvariable.

\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 dem Befehl \qmlproperty Befehl verwendet, um die QML-Eigenschaft als erforderlich zu kennzeichnen.

Siehe auch „Das Eigenschaftssystem“.

\since

Der Befehl „ \since “ gibt an, in welcher Minor-Version die zugehörige Funktionalität hinzugefügt wurde.

Wenn das an „ \since “ übergebene Argument keine Leerzeichen enthält, wird davon ausgegangen, dass es sich um eine Kurzschreibweise für den Produktnamen handelt, und QDoc fügt der Version in der generierten Ausgabe den Wert von „ productname “ als Präfix hinzu. Ist die Variable „ productname “ nicht definiert, generiert QDoc nur die Versionszeichenfolge.

Das Argument kann auch den Produktnamen explizit enthalten:

\since MyFramework 2.0

In diesem Fall werden die Argumente (Produkt und Version) unverändert verwendet.

Vererbung von „Since“-Informationen

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

„Since“-Klausel

Der Befehl ` \value ` erlaubt eine optionale `since` -Klausel in eckigen Klammern, die unmittelbar auf die Befehlszeichenfolge folgt. Diese dient dazu, bestimmte C++-Enum-Werte mit `since`-Informationen zu kennzeichnen.

Siehe auch \value sowie ` ignoresince`.

\wrapper

Der Befehl „ \wrapper “ kennzeichnet die Klasse, wenn er in einer C++-Klassendokumentation verwendet wird, 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 ausgegeben würden.