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 Topic-Befehl, der anzeigt, dass der Kommentar kein zugrundeliegendes Quellcode-Element hat (z.B. \page), 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 ist ein Sonderfall. Für den Befehl \fn ist die Funktionssignatur einschließlich des Klassifizierers zu verwenden.

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

Ein Topic-Befehl 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. \page, erzeugt QDoc bei der Verarbeitung der Dokumentation eine Datei.

QDoc normalisiert den Namen jeder Datei, bevor sie auf die Festplatte geschrieben wird. 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 generiert, kann es ein Präfix, ein Suffix oder beides hinzufügen, je nach dem Element, das die Datei dokumentiert.

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 ermöglicht es Ihnen, eine detaillierte Beschreibung einzugeben.

/*!
    \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 \class-Kommentar sowie die aus QDoc-Kommentaren generierte Dokumentation für alle Klassenmitglieder: eine Liste der Typen, Eigenschaften, Funktionen, Signale und Slots der Klasse.

Neben der detaillierten Beschreibung der Klasse enthält der \class-Kommentar in der Regel auch einen \inmodule-Befehl sowie eine \kurzbeschreibung. 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 Klasse 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 \enum-Kommentar mit dem \value-Befehl dokumentiert. Wenn ein Enum-Wert nicht mit \value dokumentiert ist, gibt QDoc eine Warnung aus. Diese Warnungen können mit dem Befehl \omitvalue vermieden werden, 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 Aufzählung 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.

\Beispiel

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

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

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

\externeSeite

Der Befehl \externalpage weist einer externen URL einen Titel zu.

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

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

/*!
    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 Signatur der Funktion, einschließlich ihrer Schablonenparameter (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 den 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 für die Dokumentation von Klassenmitgliedern verwendet werden, 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 umgebenden 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.

\Gruppe

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

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

Auf den Befehl \group folgen in der Regel der Befehl \title und eine kurze Einführung in die Gruppe. Die HTML-Seite für die Gruppe wird in eine .html -Datei 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 aus dem Befehl \brief 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 Befehl \generatelist und dem Argument related aufgelistet werden müssen.

/*!
    \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, \generatelist und \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 Headerdatei. Die HTML-Seite wird in eine .html -Datei geschrieben, die aus dem Headerfile-Argument 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 Befehl \relates in die Header-Datei-Seite aufgenommen.

Wenn das Argument nicht als Header-Datei existiert, erzeugt 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 Headerfile-Seite, 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 \macro-Kommentar 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

Der Befehl \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 Befehl \inmodule in den Kommentar \class aufgenommen wird.

Auf den Befehl \module folgen in der Regel die Befehle \title und \brief. Jede Klasse wird als Link zur Klassenreferenzseite aufgelistet, gefolgt vom Text aus dem \brief-Befehl der Klasse. 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 auszulassen.

Siehe auch \inmodule

\Namensraum

Der Befehl \namespace dient dazu, den Inhalt des als Argument angegebenen C++-Namensraums zu dokumentieren. 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.

\Seite

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

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

Der Seitentitel wird mit dem Befehl \title festgelegt.

/*!
   \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 zum Dokumentieren 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 Kommentar zum Befehl \property enthält normalerweise einen Befehl \brief. Bei Eigenschaften ist das Argument des \brief-Befehls ein Satzfragment, das in eine einzeilige Beschreibung der Eigenschaft aufgenommen wird. Der Befehl folgt denselben Regeln für die Beschreibung wie der Befehl \variable.

/*!
    \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 wird. Siehe Angehängte Eigenschaften. Das Argument ist der Rest der Zeile. Sie muss mit dem Eigenschaftstyp beginnen, gefolgt vom QML-Typnamen, unter 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 zum Dokumentieren eines anfügbaren Signals. Der Befehl \qmlattachedsignal wird genau wie der Befehl \qmlsignal verwendet.

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. Ein QML-Signal mit dem Namen add() im Element GridView wird beispielsweise 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 nimmt einen Typnamen als einziges Argument an.

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

\qmlclass

Dieser Befehl ist veraltet. Verwenden Sie stattdessen \qmltype.

\qmlmethod

Der Befehl \qmlmethod dient zum Dokumentieren 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 Befehl \qmltype dient der 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 Befehl \inqmlmodule dokumentiert das QML-Modul, zu dem der Typ gehört. Das an diesen Befehl übergebene Argument muss mit einer dokumentierten \qmlmodule-Seite übereinstimmen.

/*!
    \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 der Kommentar \qmltype \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 \Kurzbeschreibung enthalten. Wenn ein QML-Typ Mitglied einer QML-Typengruppe ist, sollte der \qmltype-Kommentar einen oder mehrere \ingroup-Befehle enthalten.

\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 dafür 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.

Wenn die QML-Eigenschaft vom Typ Enumeration ist oder eine bitweise Kombination von Flags enthält, kann der Befehl \value verwendet werden, um die akzeptablen Werte zu dokumentieren.

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 dem Befehl \inqmlmodule in der zugehörigen \qmltype-Dokumentation übergeben wurde. 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 nimmt ein optionales <VERSION> Nummernargument entgegen und ähnelt dem group-Befehl.

Ein QML-Typ wird mit einem Modul verknüpft, indem der Befehl \inqmlmodule in den Kommentarblock eingefügt wird, 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 durch Einfügen des Befehls \inqmlmodule in ein \qmltype-Thema als unter einem bestimmten QML-Modulimport verfügbar markiert. Der Befehl nimmt den Modulnamen (Import) ohne Versionsnummer als einziges Argument an.

Der QML-Modulname muss mit einem QML-Modul übereinstimmen, das mit dem Befehl\qmlmodule 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 Befehl \instantiates 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 Befehl \nativetype-command, 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 schließt das Thema \qmltype \nativetype ein, um anzugeben, dass ein Transform in C++ QGraphicsTransform genannt wird.

\typealias

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

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

Dieser kann dokumentiert werden als

/*!
    \typealias Foo::ptr
*/

Der Befehl \typealias 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 den Typedef wird in die Referenzdokumentation für die Klasse, den Namespace oder die Header-Datei aufgenommen, in der der 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 für die Klasse, die sie definiert.

/*!
    \typedef QList::Iterator

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

Siehe auch \typealias.

\variable

Der Befehl \variable dient zur Dokumentation einer Klassenvariable oder einer Konstanten. Das Argument ist der Name der Variable oder Konstante. Der Kommentar des \variable-Befehls enthält einen \brief-Befehl. QDoc generiert die Dokumentation basierend auf dem Text des \brief-Befehls.

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

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()
*/