Themen-Befehle

Ein Themenbefehl teilt QDoc mit, welches Quellcode-Element dokumentiert werden soll. Einige Themenbefehle erlauben es Ihnen, Dokumentationsseiten zu erstellen, die nicht an ein zugrunde liegendes Quellcode-Element gebunden sind.

Wenn QDoc einen QDoc-Kommentar verarbeitet, versucht es, den Kommentar mit einem Element im Quellcode zu verbinden, indem es zuerst nach einem Themenbefehl sucht, der das Quellcode-Element nennt. Wenn es keinen Topic-Befehl gibt, versucht QDoc, den Kommentar mit dem Quellcode-Element zu verbinden, das unmittelbar auf den Kommentar folgt. Ist dies nicht möglich und gibt es keinen Themenbefehl, der anzeigt, dass der Kommentar kein zugrundeliegendes Quelltextelement hat (z.B. \page), dann wird der Kommentar verworfen.

Der Name der zu dokumentierenden Entität ist normalerweise das einzige Argument für einen Topic-Befehl. Verwenden Sie den vollständigen Namen. Manchmal kann es einen zweiten Parameter im Argument geben. Siehe z.B. \page.

\enum QComboBox::InsertPolicy

Der Befehl \fn Befehl ist ein Spezialfall. Für den \fn Befehl verwenden Sie die Funktionssignatur einschließlich des Klassenbezeichners.

\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)

Ein Themenbefehl kann an beliebiger Stelle in einem Kommentar erscheinen, muss aber in einer eigenen Zeile stehen. Es ist eine gute Praxis, den Themenbefehl in der ersten Zeile des Kommentars stehen zu lassen. Wenn sich das Argument über mehrere Zeilen erstreckt, stellen Sie sicher, dass jede Zeile (außer der letzten) mit einem Backslash abgeschlossen wird. Außerdem zählt QDoc Klammern, d.h. wenn es auf ein '(' stößt, betrachtet es alles bis zum schließenden ')' als sein Argument.

Wenn ein Topic-Befehl mit unterschiedlichen Argumenten wiederholt wird, erscheint für beide Einheiten die gleiche Dokumentation.

/*!
    \fn void PreviewWindow::setWindowFlags()
    \fn void ControllerWindow::setWindowFlags()

    Sets the widgets flags using the QWidget::setWindowFlags()
    function.

    Then runs through the available window flags, creating a text
    that contains the names of the flags that matches the flags
    parameter, displaying the text in the widgets text editor.
*/

Die Funktionen PreviewWindow::setWindowFlags() und ControllerWindow::setWindowFlags() erhalten die gleiche Dokumentation.

Nomenklatur für von Themenbefehlen erzeugte Dateien

Für viele themenbezogene Befehle, wie z.B. \pageerzeugt QDoc bei der Verarbeitung der Dokumentation eine Datei.

QDoc normalisiert den Namen jeder Datei, bevor es sie auf die Festplatte schreibt. Die folgenden Operationen werden durchgeführt:

• Alle Folgen von nicht alphanumerischen Zeichen werden durch einen Bindestrich, '-', ersetzt.
• Alle Großbuchstaben werden durch die entsprechenden Kleinbuchstaben ersetzt.
• Alle nachgestellten Bindestriche werden entfernt.

Der folgende Befehl erzeugt zum Beispiel eine Datei mit dem Namen this-generates-a-file-and-writes-it-to-disk.html:

\page this_generates_a_file_(and_writes_it_to_DISK)-.html

Wie das Beispiel zeigt, kann der Name, der der Datei im Befehl gegeben wird, von dem Namen der tatsächlichen Datei, die auf die Festplatte geschrieben wird, abweichen.

Präfixe und Suffixe für generierte Dateien

Wenn QDoc eine Datei erzeugt, kann es ein Präfix, ein Suffix oder beides hinzufügen, je nach dem Element, das die Datei dokumentieren soll.

Die folgende Tabelle zeigt, was diese Präfixe und Suffixe für verschiedene Elemente sind.

\class

Der Befehl \class dient zur Dokumentation einer C++ Klasse, einer C/C++ Struktur oder einer Union. Das Argument ist der vollständige, qualifizierte Name der Klasse. Der Befehl teilt QDoc mit, dass eine Klasse Teil der öffentlichen API ist, und lässt Sie eine detaillierte Beschreibung eingeben.

/*!
    \class QMap::iterator
    \inmodule QtCore

    \brief The QMap::iterator class provides an STL-style
    non-const iterator for QMap and QMultiMap.

    QMap features both \l{STL-style iterators} and
    \l{Java-style iterators}. The STL-style iterators ...
*/

Die HTML-Dokumentation für die benannte Klasse wird in eine Datei .html geschrieben, die nach dem Klassennamen benannt ist, in Kleinbuchstaben, wobei die doppelten Doppelpunkte durch '-' ersetzt werden. Zum Beispiel wird die Dokumentation für die Klasse QMap::iterator in die Datei qmap-iterator.html geschrieben.

Die Datei enthält die Klassenbeschreibung aus dem Kommentar \class sowie die aus den QDoc-Kommentaren generierte Dokumentation für alle Klassenmitglieder: eine Liste der Typen, Eigenschaften, Funktionen, Signale und Slots der Klasse.

Zusätzlich zu der detaillierten Beschreibung der Klasse enthält der \class Kommentar typischerweise einen \inmodule Befehl, sowie eine \brief Beschreibung. Hier ist ein sehr einfaches Beispiel:

/*!
    \class PreviewWindow
    \inmodule CustomWidgets
    \brief The PreviewWindow class is a custom widget.
           displaying the names of its currently set
           window flags in a read-only text editor.

    \ingroup miscellaneous

    The PreviewWindow class inherits QWidget. The widget
    displays the names of its window flags set with the \l
    {function} {setWindowFlags()} function. It is also
    provided with a QPushButton that closes the window.

    ...

    \sa QWidget
*/

Die Art und Weise, wie QDoc diese \class wiedergibt, hängt von Ihrer style.css Datei ab.

\enum

Der Befehl \enum dient zur Dokumentation eines C++-Enum-Typs. Das Argument ist der vollständige Name des Aufzählungstyps.

Die Enum-Werte werden im Kommentar \enum mit dem \value Befehl dokumentiert. Wenn ein Enum-Wert nicht mit \value dokumentiert ist, gibt QDoc eine Warnung aus. Diese Warnungen können vermieden werden, indem man mit dem \omitvalue Kommando, um QDoc mitzuteilen, dass ein Enum-Wert nicht dokumentiert werden soll. Die Enum-Dokumentation wird auf der Klassenreferenzseite, der Header-Datei-Seite oder der Namespace-Seite, auf der der Enum-Typ definiert ist, eingefügt. Betrachten wir zum Beispiel den Enum-Typ Corner im Qt-Namensraum:

enum Corner {
    TopLeftCorner = 0x00000,
    TopRightCorner = 0x00001,
    BottomLeftCorner = 0x00002,
    BottomRightCorner = 0x00003
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
    ,TopLeft = TopLeftCorner,
    TopRight = TopRightCorner,
    BottomLeft = BottomLeftCorner,
    BottomRight = BottomRightCorner
#endif
};

Diese Enum kann auf diese Weise dokumentiert werden:

/*!
    \enum Qt::Corner

    This enum type specifies a corner in a rectangle:

    \value TopLeftCorner
           The top-left corner of the rectangle.
    \value TopRightCorner
           The top-right corner of the rectangle.
    \value BottomLeftCorner
           The bottom-left corner of the rectangle.
    \value BottomRightCorner
           The bottom-right corner of the rectangle.

    \omitvalue TopLeft
    \omitvalue TopRight
    \omitvalue BottomLeft
    \omitvalue BottomRight
               Bottom-right (omitted; not documented).
*/

Beachten Sie die Einbeziehung des Namespace-Qualifizierers.

Siehe auch \value und \omitvalue.

\example

Der Befehl \example dient zur Dokumentation eines Beispiels. Das Argument ist der Pfad des Beispiels relativ zu einem der Pfade, die in der Variable exampledirs in der QDoc-Konfigurationsdatei aufgeführt sind.

Die Dokumentationsseite wird nach modulename-path-to-example.html ausgegeben. QDoc fügt eine Liste aller Quell- und Bilddateien des Beispiels am Ende der Seite ein, es sei denn, \noautolist Befehl verwendet wird oder die Konfigurationsvariable url.examples für das Projekt definiert ist.

Wenn exampledirs zum Beispiel $QTDIR/examples/widgets/imageviewer enthält, dann

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \subtitle

    The example shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

Siehe auch: \noautolist, url.examples, \meta

\externalpage

Mit dem Befehl \externalpage wird einer externen URL ein Titel zugewiesen.

/*!
    \externalpage http://doc.qt.io/
    \title Qt Documentation Site
*/

Auf diese Weise können Sie einen Link zu der externen Seite in Ihre Dokumentation einfügen:

/*!
    At the \l {Qt Documentation Site} you can find the latest
    documentation for Qt, Qt Creator, the Qt SDK and much more.
*/

Um das gleiche Ergebnis zu erzielen, ohne den Befehl \externalpage zu verwenden, müssten Sie die Adresse in Ihre Dokumentation fest einprogrammieren:

/*!
    At the \l {http://doc.qt.io/}{Qt Documentation Site}
    you can find the latest documentation for Qt, Qt Creator, the Qt SDK
    and much more.
*/

Der Befehl \externalpage macht die Pflege der Dokumentation einfacher. Wenn sich die Adresse ändert, müssen Sie nur das Argument des Befehls \externalpage ändern.

\fn (Funktion)

Der Befehl \fn dient zur Dokumentation einer Funktion. Das Argument ist die Funktionssignatur, einschließlich der Template-Parameter (falls vorhanden), des Rückgabetyps, der Konstante und der Liste der formalen Argumente mit Typen. Wenn die benannte Funktion nicht existiert, gibt QDoc eine Warnung aus.

Der Befehl akzeptiert auto als Typ einer Funktion, auch wenn der vollständige Typ von QDoc abgeleitet werden kann. In bestimmten Situationen kann es besser sein, auto anstelle des tatsächlichen Typs einer Funktion zu verwenden. Die Verwendung von auto als Rückgabetyp im \fn-Befehl ermöglicht es dem Autor, dies explizit zu tun, auch für Typen, die ohne das Schlüsselwort auto definiert sind.

Seit QDoc Version 6.0 kann der \fn -Befehl verwendet werden, um Klassenmitglieder zu dokumentieren, die nicht explizit im Header deklariert sind, sondern implizit vom Compiler erzeugt werden; Standardkonstruktor und -destruktor, Kopierkonstruktor und move-copy-Konstruktor, Zuweisungsoperator und move-assignment-Operator.

Bei der Dokumentation eines versteckten Freundes ist es erforderlich, dem Funktionsnamen den Namen der umschließenden Klasse voranzustellen. Zum Beispiel für:

class Foo {
   ...
   friend bool operator==(const Foo&, const Foo&) { ... }
   ...
}

Der Befehl sollte als "\fn Foo::operator==(const Foo&, const Foo&)" und nicht als die freie Funktion "\fn operator==(const Foo&, const Foo&)" geschrieben werden.

Andernfalls wird sich QDoc darüber beschweren, dass es die Funktion nicht auflösen kann.

/*!
    \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const

    Returns \c true if this toolbar is dockable in the given
    \a area; otherwise returns \c false.
*/

Siehe auch \overload.

\group

Der Befehl \group erstellt eine separate Seite, auf der die Klassen, Seiten oder andere Entitäten aufgelistet sind, die zu einer bestimmten Gruppe gehören. Das Argument ist der Gruppenname.

Eine Klasse wird in eine Gruppe aufgenommen, indem man den \ingroup Befehl. Übersichtsseiten können mit demselben Befehl ebenfalls mit einer Gruppe verknüpft werden, aber die Liste der Übersichtsseiten muss explizit mit dem \generatelist Befehl angefordert werden (siehe Beispiel unten).

Auf den Befehl \group folgt in der Regel ein \title Befehl und einer kurzen Einführung in die Gruppe. Die HTML-Seite für die Gruppe wird in eine Datei .html mit dem Namen <Kleinbuchstaben-Gruppenname>.html geschrieben.

Jede Entität in der Gruppe wird als Link aufgeführt (unter Verwendung des Seitentitels oder des Klassennamens), gefolgt von einer Beschreibung des \brief Befehl in der Dokumentation der Entität.

/*!
    \group io
    \title Input/Output and Networking
*/

QDoc erzeugt eine Gruppenseite io.html.

Beachten Sie, dass Übersichtsseiten, die sich auf die Gruppe beziehen, explizit mit dem \generatelist Befehl mit dem Argument related aufgelistet werden.

/*!
    \group architecture

    \title Architecture

    These documents describe aspects of Qt's architecture
    and design, including overviews of core Qt features and
    technologies.

    \generatelist{related}
*/

Siehe auch \ingroup, \annotatedlist, \generatelistund \noautolist.

\headerfile

Der Befehl \headerfile dient zur Dokumentation der globalen Funktionen, Typen und Makros, die in einer Header-Datei, aber nicht in einem Namensraum deklariert sind. Das Argument ist der Name der Header-Datei. Die HTML-Seite wird in eine .html Datei geschrieben, die aus dem Argument der Header-Datei erstellt wird.

Die Dokumentation für eine Funktion, einen Typ oder ein Makro, die in der zu dokumentierenden Header-Datei deklariert sind, wird mit dem \relates Befehl.

Wenn das Argument nicht als Header-Datei existiert, erstellt der Befehl \headerfile trotzdem eine Dokumentationsseite für die Header-Datei.

/*!
   \headerfile <QtAlgorithms>

   \title Generic Algorithms

   \brief The <QtAlgorithms> header file provides
    generic template-based algorithms.

   Qt provides a number of global template functions in \c
   <QtAlgorithms> that work on containers and perform
   well-know algorithms.
*/

QDoc erzeugt eine Seite für eine Header-Datei, qtalgorithms.html.

Siehe auch \inheaderfile.

\macro

Der Befehl \macro dient zum Dokumentieren eines C++-Makros. Das Argument ist das Makro in einem von drei Stilen: funktionsähnliche Makros wie Q_ASSERT(), deklarationsähnliche Makros wie Q_PROPERTY() und Makros ohne Klammern wie Q_OBJECT.

Der Kommentar \macro muss einen \relates Befehl enthalten, der den Makrokommentar an eine Klasse, eine Header-Datei oder einen Namespace anhängt. Andernfalls geht die Dokumentation verloren.

\module

\module erstellt eine Seite, die die Klassen auflistet, die zu dem durch das Argument des Befehls angegebenen Modul gehören. Eine Klasse wird in das Modul aufgenommen, indem der \inmodule Befehl in den \class Kommentar aufgenommen wurde.

Auf den Befehl \module folgt normalerweise ein \title und einem \brief Befehl. Jede Klasse wird als Link zur Klassenreferenzseite aufgeführt, gefolgt vom Text des Klassenbefehls \brief Befehls. Zum Beispiel:

/*!
    \module QtNetwork

    \title Qt Network Module

    \brief Contains classes for writing TCP/IP clients and servers.

    The network module provides classes to make network
    programming easier and portable. It offers both
    high-level classes such as QNetworkAccessManager that
    implements application-level protocols, and
    lower-level classes such as QTcpSocket, QTcpServer, and
    QUdpSocket.
*/

Der Befehl \noautolist kann hier verwendet werden, um die automatisch generierte Liste der Klassen am Ende wegzulassen.

Siehe auch \inmodule

\namespace

Der Befehl \namespace dient zur Dokumentation des Inhalts des als Argument angegebenen C++-Namensraums. Die Referenzseite, die QDoc für einen Namespace erzeugt, ähnelt der Referenzseite, die es für eine C++-Klasse erzeugt.

/*!
    \namespace Qt

    \brief Contains miscellaneous identifiers used throughout the Qt library.
*/

Beachten Sie, dass in C++ ein bestimmter Namensraum in mehr als einem Modul verwendet werden kann, aber wenn C++-Elemente aus verschiedenen Modulen im selben Namensraum deklariert werden, muss der Namensraum selbst nur in einem Modul dokumentiert werden. Der Namensraum Qt im obigen Beispiel enthält beispielsweise Typen und Funktionen sowohl aus QtCore als auch aus QtGui, wird aber mit dem Befehl \namespace nur in QtCore dokumentiert.

\page

Der Befehl \page dient zum Erstellen einer eigenständigen Dokumentationsseite.

Der Befehl \page erwartet ein einzelnes Argument, das den Namen der Datei angibt, in der QDoc die Seite speichern soll.

Der Seitentitel wird mit dem \title Befehl.

/*!
   \page aboutqt.html

   \title About Qt

   Qt is a C++ toolkit for cross-platform GUI
   application development. Qt provides single-source
   portability across Microsoft Windows, macOS, Linux,
   and all major commercial Unix variants.

   Qt provides application developers with all the
   functionality needed to build applications with
   state-of-the-art graphical user interfaces. Qt is fully
   object-oriented, easily extensible, and allows true
   component programming.

   ...
*/

QDoc rendert diese Seite in aboutqt.html.

\property

Der Befehl \property dient zur Dokumentation einer Qt-Eigenschaft. Das Argument ist der vollständige Eigenschaftsname.

Eine Eigenschaft wird mit dem Makro Q_PROPERTY() definiert. Das Makro nimmt als Argumente den Eigenschaftsnamen und die Funktionen set, reset und get an.

Q_PROPERTY(QString state READ state WRITE setState)

Die set-, reset- und get-Funktionen müssen nicht dokumentiert werden, es genügt, die Eigenschaft zu dokumentieren. QDoc generiert eine Liste der Zugriffsfunktionen, die in der Dokumentation der Eigenschaft erscheinen wird, die wiederum in der Dokumentation der Klasse, die die Eigenschaft definiert, zu finden sein wird.

Der \property Befehlskommentar enthält typischerweise einen \brief Befehl. Bei Eigenschaften ist das \brief Befehlsargument ist ein Satzfragment, das in eine einzeilige Beschreibung der Eigenschaft aufgenommen wird. Der Befehl folgt den gleichen Regeln für die Beschreibung wie der \variable Befehl.

/*!
    \property QPushButton::flat
    \brief Whether the border is disabled.

    This property's default is false.
*/

\qmlattachedproperty

Der Befehl \qmlattachedproperty dient zur Dokumentation einer QML-Eigenschaft, die an einen QML-Typ angehängt werden soll. Siehe Angehängte Eigenschaften. Das Argument ist der Rest der Zeile. Es muss mit dem Eigenschaftstyp beginnen, gefolgt vom QML-Typnamen, in dem die Eigenschaft deklariert ist, dem Qualifier :: und schließlich dem Eigenschaftsnamen.

Beispiel: Um eine boolesche QML-Eigenschaft mit dem Namen isCurrentItem für den Typ ListView zu dokumentieren:

/*!
    \qmlattachedproperty bool ListView::isCurrentItem

    This attached property is \c true if this delegate is the current
    item; otherwise false.

    It is attached to each instance of the delegate.

    This property may be used to adjust the appearance of the current
    item, for example:

    \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
*/

QDoc fügt diese angehängte Eigenschaft auf der QML-Referenzseite für den Typ ListView ein.

\qmlattachedsignal

Der Befehl \qmlattachedsignal dient zur Dokumentation eines anfügbaren Signals. Der \qmlattachedsignal Befehl wird genau wie der \qmlsignal Befehl.

Das Argument ist der Rest der Zeile. Es sollte der Name des QML-Typs sein, in dem das Signal deklariert ist, der Qualifier :: und schließlich der Signalname. Zum Beispiel wird ein QML-Signal mit dem Namen add() im Element GridView wie folgt dokumentiert:

/*!
    \qmlattachedsignal GridView::add()
    This attached signal is emitted immediately after an item is added to the view.
*/

QDoc enthält diese Dokumentation auf der QML-Referenzseite für das Element GridView.

\qmlvaluetype

Der Befehl \qmlvaluetype dient zur Dokumentation eines Wertetyps für QML. Der Befehl benötigt einen Typnamen als einziges Argument.

\qmlvaluetypeist funktionell identisch mit dem \qmltype Befehl. Der einzige Unterschied besteht darin, dass der Typ als QML-Wertetyp betitelt (und gruppiert) wird.

\qmlclass

Dieser Befehl ist veraltet. Verwenden Sie stattdessen \qmltype stattdessen.

\qmlenum

Der Befehl \qmlenum dient zur Dokumentation einer QML-Aufzählung. Der Befehl benötigt ein einziges Argument: den vollständigen Namen des Aufzählungstyps, einschließlich des übergeordneten QML-Typs und optional des QML-Moduls.

Die Aufzählungszeichen und ihre Beschreibungen werden mit \value Befehle.

Zum Beispiel,

/*!
    \qmlenum My.Module::Color::Channel
    \brief Specifies a color channel in the RGB colorspace.

    \value R
           Red color channel

    \value G
           Green color channel

    \value B
           Blue color channel
*/

Dies erzeugt die Dokumentation für eine Aufzählung Channel mit drei Aufzählungszeichen: Farbe.R, Farbe.G und Farbe.B. Standardmäßig wird der übergeordnete QML-Typname als Präfix für die Aufzählungszeichen verwendet.

Wenn das erste Argument des Befehls qdoccmd{value} bereits ein Präfix enthält, wird es unverändert verwendet:

\value Channel.R
       Red color channel
\value Channel.G
       Green color channel
\value Channel.B
       Blue color channel

Hier werden die Aufzähler als Channel.R, Channel.G und Channel.B aufgeführt.

Alternativ ist es möglich, die Dokumentation der Aufzählungszeichen aus einem bestehenden C++ \enum Thema zu übernehmen, indem man den \qmlenumeratorsfrom Befehl.

Dieser Befehl wurde mit Qt 6.10 eingeführt.

Siehe auch \qmlenumeratorsfrom.

\qmlmethod

Der Befehl \qmlmethod dient zur Dokumentation einer QML-Methode. Das Argument ist die vollständige Methodensignatur, einschließlich Rückgabetyp, Parameternamen und -typen.

/*!
    \qmlmethod void TextInput::select(int start, int end)

    Causes the text from \a start to \a end to be selected.

    If either start or end is out of range, the selection is not changed.

    After having called this, selectionStart will become the lesser, and
    selectionEnd the greater (regardless of the order passed to this method).

   \sa selectionStart, selectionEnd
*/

QDoc enthält diese Dokumentation auf der Elementreferenzseite für das TextInput-Element.

\qmltype

Der \qmltype Befehl dient zur Dokumentation eines QML-Typs. Der Befehl hat ein Argument, nämlich den Namen des QML-Typs.

Wenn der QML-Typ eine äquivalente C++-Klasse hat, können Sie diese Klasse mit dem \nativetype Kontext-Befehl angeben.

Der \inqmlmodule Befehl dokumentiert das QML-Modul, zu dem der Typ gehört. Das an diesen Befehl übergebene Argument muss mit einer dokumentierten \qmlmodule Seite entsprechen.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

Hier muss der \qmltype Kommentar enthält \nativetype um anzugeben, dass ein Transform das QML-Gegenstück zur C++-Klasse QGraphicsTransform ist. Ein \qmltype Kommentar sollte immer einen \since Befehl enthalten, da alle QML-Typen neu sind. Er sollte auch eine \brief Beschreibung enthalten. Wenn ein QML-Typ Mitglied einer QML-Typengruppe ist, sollte der \qmltype Kommentar einen oder mehrere \ingroup Befehle enthalten.

\qmlsingletontype

Der Befehl \qmlsingletontype dient der expliziten Dokumentation eines QML-Singleton-Typs. Dieses Kommando ist funktional identisch mit \qmltypeidentisch, kennzeichnet den Typ aber explizit als Singleton, unabhängig von der C++-Implementierung.

Ein QML-Singleton-Typ stellt sicher, dass nur eine Instanz in der QML-Engine existiert. Die Singleton-Bezeichnung wird in der generierten Dokumentation mit einem "(Singleton)"-Indikator im Titel und einem erklärenden Hinweis angezeigt.

/*!
    \qmlsingletontype Settings
    \inqmlmodule MyApp

    \brief Provides application-wide settings as a singleton.

    The Settings type is a singleton that maintains application
    configuration. Access it directly without instantiation.
*/

Für C++-Klassen, die das Makro QML_SINGLETON verwenden, sollten Sie stattdessen \qmltype zu verwenden, da QDoc den Singleton-Charakter automatisch aus dem C++-Code erkennt.

\qmlproperty

Der Befehl \qmlproperty dient zur Dokumentation einer QML-Eigenschaft. Das Argument ist der Rest der Zeile. Der Argumenttext sollte der Eigenschaftstyp sein, gefolgt vom QML-Typnamen, dem Qualifier :: und schließlich dem Eigenschaftsnamen. Wenn wir eine QML-Eigenschaft mit dem Namen x im QML-Typ Translate haben und die Eigenschaft den Typ real hat, würde die \qmlproperty für sie wie folgt aussehen:

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

QDoc nimmt diese QML-Eigenschaft auf der QML-Referenzseite für den Typ Translate auf.

Der \default Befehl wird verwendet, um den Standardwert einer Eigenschaft zu dokumentieren:

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

Wenn die QML-Eigenschaft ein C++-Enum darstellt, wird die QML-Eigenschaft mit dem Typ enumeration definiert:

\qmlproperty enumeration ParticleShape3D::ShapeType

Eigenschaften mit Aufzählungstyp und solche, die eine bitweise Kombination von Flags enthalten, können mit dem \value Befehl verwenden, um die akzeptablen Werte zu dokumentieren.

\qmlproperty enumeration Buffer::textureFilterOperation
Specifies the texture filtering mode...
\value Buffer.Nearest Use nearest-neighbor filtering.

QDoc akzeptiert auch einen vollständig qualifizierten Eigenschaftsnamen, einschließlich des QML-Modulbezeichners:

\qmlproperty bool QtQuick.Controls::Button::highlighted

Falls angegeben, muss der Modulbezeichner (oben, QtQuick.Controls) mit dem Wert übereinstimmen, der an den \inqmlmodule Befehl übergebenen Wert in der zugehörigen \qmltype Dokumentation übereinstimmen. Wenn der Name des QML-Typs, zu dem die Eigenschaft gehört, für alle Typen im Dokumentationsprojekt eindeutig ist, kann der Modulbezeichner weggelassen werden.

\qmlsignal

Der Befehl \qmlsignal dient zur Dokumentation eines QML-Signals. Das Argument ist der Rest der Zeile. Die Argumente sollten sein: der QML-Typ, in dem das Signal deklariert ist, der Qualifier :: und schließlich der Signalname. Wenn wir ein QML-Signal mit dem Namen clicked() haben, würde die Dokumentation dafür wie folgt aussehen:

/*!
    \qmlsignal MouseArea::clicked(MouseEvent mouse)

    This signal is emitted when there is a click. A click is defined as a
    press followed by a release, both inside the MouseArea.
*/

QDoc enthält diese Dokumentation auf der QML-Referenzseite für den Typ MouseArea.

\qmlmodule

Verwenden Sie den Befehl \qmlmodule, um eine QML Modulseite zu erstellen. Eine QML-Modulseite ist eine Sammlung von QML-Typen oder verwandtem Material. Der Befehl akzeptiert ein optionales <VERSION> Nummernargument und ist ähnlich wie der group-Befehl.

Ein QML-Typ wird mit einem Modul verknüpft, indem der \inqmlmodule Befehl in den Kommentarblock einfügt, der den Typ dokumentiert. Sie können auf jedes Mitglied eines QML-Moduls verweisen, indem Sie den Modulnamen und zwei Doppelpunkte (::) als Präfix verwenden.

/*!
    A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
*/

QDoc generiert eine Seite für das Modul, die alle Mitglieder des Moduls auflistet.

/*!
    \qmlmodule ClickableComponents

    This is a list of the Clickable Components set. A Clickable component
    responds to a \c clicked() event.
*/

\inqmlmodule

Ein QML-Typ wird als verfügbar unter einem bestimmten QML-Modul-Import markiert, indem der \inqmlmodule Befehl in ein \qmltype Thema einfügt. Der Befehl nimmt den Modulnamen (Import) ohne Versionsnummer als einziges Argument an.

Der QML-Modulname muss mit einem QML-Modul übereinstimmen, das mit dem (\qmlmodule Befehl) dokumentiert ist.

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

    A clickable button that responds to the \c click() event.
*/

QDoc gibt eine Zeile Import-Anweisung: import <qmlmodule> in einer Tabelle am oberen Rand der QML-Typ-Referenzseite aus.

Bei der Verknüpfung mit QML-Typen kann der QML-Modulbezeichner im Verknüpfungsziel erscheinen. Zum Beispiel:

\l {ClickableComponents::}{ClickableButton}

Links zur Typ-Referenzseite, mit ClickableButton als Linktext.

\instantiates

Der \instantiates Befehl ist seit Qt 6.8 veraltet. Verwenden Sie stattdessen \nativetype stattdessen.

\nativetype

Der \nativetype-Befehl muss in Verbindung mit dem \qmltype topic-Befehl verwendet werden. Der Befehl nimmt eine C++ Klasse als Argument. Wenn QDoc die C++ Klasse nicht finden kann, gibt es eine Warnung aus. Dieser Befehl wurde mit Qt 6.8 eingeführt.

Verwenden Sie den \nativetype-Befehl, um anzugeben, wie der Typ in C++ genannt wird. Dadurch wird sichergestellt, dass der in der Dokumentation für den QML-Typ generierte Requisitenblock einen Eintrag "In C++" enthält. Die C++-Klasse wird einen entsprechenden "In QML"-Eintrag haben.

Jeder QML-Typ kann nur einen nativen Typ haben. QDoc gibt eine Warnung aus, wenn eine Neudefinition stattfindet. Mehrere QML-Typen können jedoch dieselbe C++-Klasse als ihren nativen Typ haben. Die C++-Klassendokumentation enthält eine Liste aller entsprechenden Typen in QML.

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

Hier enthält das \qmltype Thema enthält \nativetype um anzugeben, dass ein Transform in C++ QGraphicsTransform genannt wird.

\typealias

Der Befehl \typealias ist ähnlich wie \typedefaber speziell für die Dokumentation eines C++-Typ-Alias:

class Foo
{
public:
    using ptr = void*;
// ...
}

Dieser kann dokumentiert werden als

/*!
    \typealias Foo::ptr
*/

Der \typealias Befehl wurde in QDoc 5.15 eingeführt.

Siehe auch \typedef.

\typedef

Der Befehl \typedef dient zur Dokumentation eines C++-Typedefs. Das Argument ist der Name des Typedefs. Die Dokumentation für das typedef wird in die Referenzdokumentation für die Klasse, den Namespace oder die Header-Datei aufgenommen, in der das typedef deklariert ist. Um die \typedef mit einer Klasse, einem Namespace oder einer Header-Datei zu verknüpfen, muss der \typedef Kommentar einen \relates Befehl enthalten.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

Andere Typedefs befinden sich auf der Referenzseite der Klasse, die sie definiert.

/*!
    \typedef QList::Iterator

    Qt-style synonym for QList::iterator.
*/

Siehe auch \typealias.

\variable

Der Befehl \variable dient dazu, eine Klassenvariable oder eine Konstante zu dokumentieren. Das Argument ist der Name der Variable oder Konstante. Der Kommentar des Befehls \variable enthält einen \brief Befehl. QDoc generiert die Dokumentation auf der Grundlage des Textes des \brief Befehls.

Die Dokumentation befindet sich in der zugehörigen Klasse, Header-Datei oder Namespace-Dokumentation.

Im Falle einer Member-Variable:

/*!
    \variable QStyleOption::palette
    \brief The palette that should be used when painting
           the control
*/

Sie können auch Konstanten mit dem Befehl \variable dokumentieren. Nehmen wir zum Beispiel an, Sie haben die Konstanten Type und UserType in der Klasse QTreeWidgetItem:

enum { Type = 0, UserType = 1000 };

Für diese kann der Befehl \variable auf diese Weise verwendet werden:

/*!
    \variable QTreeWidgetItem::Type

    The default type for tree widget items.

    \sa UserType, type()
*/

/*!
    \variable QTreeWidgetItem::UserType

    The minimum value for custom types. Values below
    UserType are reserved by Qt.

    \sa Type, type()
*/