Themenbefehle

Ein Themenbefehl teilt QDoc mit, welches Quellcode-Element dokumentiert wird. Mit einigen Themenbefehlen können Sie Dokumentationsseiten 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 verknüpfen, indem es zunächst nach einem Themenbefehl sucht, der das Quellcode-Element benennt. Ist kein Themenbefehl vorhanden, versucht QDoc, den Kommentar mit dem Quellcode-Element zu verknüpfen, das unmittelbar auf den Kommentar folgt. Gelingt beides nicht und gibt es keinen Themenbefehl, der angibt, dass der Kommentar kein zugrunde liegendes Quellcode-Element hat (z. B. \page), wird der Kommentar verworfen.

Der Name der zu dokumentierenden Entität ist in der Regel das einzige Argument für einen „topic“-Befehl. Verwenden Sie den vollständigen Namen. Manchmal kann das Argument einen zweiten Parameter enthalten. Siehe z. B. \page.

\enum QComboBox::InsertPolicy

Der \fn Befehl ist ein Sonderfall. Verwenden Sie für den \fn Befehls verwenden Sie die Signatur der Funktion einschließlich des Klassenqualifizierers.

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

Ein Themenbefehl kann an beliebiger Stelle in einem Kommentar stehen, muss jedoch allein in einer eigenen Zeile stehen. Es hat sich bewährt, den Themenbefehl an den Anfang des Kommentars zu setzen. Wenn sich das Argument über mehrere Zeilen erstreckt, stellen Sie sicher, dass jede Zeile (außer der letzten) mit einem Backslash endet. Außerdem zählt QDoc Klammern, d. h., wenn es auf ein „(“ stößt, betrachtet es alles bis zum schließenden „)“ als dessen Argument.

Wird ein Themenbefehl mit unterschiedlichen Argumenten wiederholt, wird für beide Einheiten dieselbe Dokumentation angezeigt.

/*!
    \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 dieselbe Dokumentation.

Namenskonvention für durch „topic“-Befehle generierte Dateien

Bei vielen Topic-Befehlen, wie beispielsweise \page, generiert QDoc bei der Verarbeitung der Dokumentation eine Datei.

QDoc normalisiert den Namen jeder Datei, bevor sie auf die Festplatte geschrieben wird. Dabei werden folgende Schritte durchgeführt:

• Alle Sequenzen aus nicht-alphanumerischen Zeichen werden durch einen Bindestrich „-“ ersetzt.
• Alle Großbuchstaben werden durch die entsprechenden Kleinbuchstaben ersetzt.
• Alle am Ende stehenden Bindestriche werden entfernt.

Beispielsweise erzeugt der folgende Befehl 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 zugewiesen wird, vom Namen der tatsächlichen Datei abweichen, die auf die Festplatte geschrieben wird.

Präfixe und Suffixe für generierte Dateien

Wenn QDoc eine Datei generiert, fügt es je nach dem Element, das die Datei dokumentieren soll, möglicherweise ein Präfix, ein Suffix oder beides hinzu.

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

\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 genannte Klasse wird in eine „ .html “-Datei geschrieben, deren Name sich aus dem Klassennamen in Kleinbuchstaben zusammensetzt, wobei die doppelten Doppelpunkte durch „-“ ersetzt werden. Beispielsweise 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 zur detaillierten Beschreibung der Klasse enthält der Kommentar „ \class “ in der Regel 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
*/

Wie QDoc diesen „ \class “-Kommentar darstellt, hängt von Ihrer Datei „ style.css “ ab.

\concept

Der Befehl „ \concept “ erstellt eine separate Seite für ein C++20-Konzept und fasst die dokumentierten Typen und Funktionen zusammen, deren Template-Einschränkungen darauf verweisen. Das Argument ist der vollqualifizierte Name des Konzepts, der mit dem Namen übereinstimmt, den Clang für die Deklaration angibt. Konzepte im Dateibereich verwenden ihren bloßen Namen; Konzepte innerhalb eines Namensraums benötigen den vollqualifizierten Namen, wie beispielsweise „ algorithms::Ordered “.

Ein Typ oder eine Funktion wird automatisch der Seite eines Konzepts hinzugefügt. Wenn QDoc eine dokumentierte Deklaration analysiert, überprüft es die Einschränkungen der Deklaration und ordnet die Deklaration den Konzepten zu, auf die sie verweisen. Ein Befehl im Stil von „ \ingroup “ oder „ \inmodule “ ist für das eingeschränkte Element selbst nicht erforderlich.

QDoc erkennt die drei syntaktischen Formen von C++20-Einschränkungen:

• Eine explizite ` requires `-Klausel, unabhängig davon, ob sie im Template-Kopf (`template <typename T> requires Ordered<T>`) oder am Ende der Funktionssignatur steht.
• Ein eingeschränkter „ auto “-Parameter (void sort(Ordered auto& range)).
• Ein Konzept, das direkt einem Template-Parameter zugewiesen wird (template <Ordered T> class SortedSet).

Auf den Befehl „ \concept “ folgt in der Regel ein \inmodule Befehl und einer \brief Beschreibung. Der Hauptteil des Kommentars wird als detaillierte Beschreibung dargestellt; \section1 Überschriften funktionieren wie auf jeder anderen Dokumentationsseite.

/*!
    \concept Ordered
    \inmodule Algorithms

    \brief A type that admits a total order.

    The Ordered concept is satisfied by any type that supplies the
    relational operators \c {<}, \c {<=}, \c {>}, and \c {>=}, and for
    which those operators induce a strict total order.

    \section1 Definition

    Ordered evaluates to \c true when \c {T} is totally ordered
    and to \c false otherwise.
*/

QDoc generiert eine Referenzseite für das Konzept. Für das obige Beispiel lautet die Seite ordered.html und enthält die Kurzbeschreibung, die detaillierte Beschreibung sowie einen Abschnitt „Verwendet von“, in dem die dokumentierten Typen und Funktionen aufgeführt sind, die in der generierten Dokumentation enthalten sind und deren Einschränkungen auf Ordered verweisen. Jeder Eintrag wird als Link dargestellt, gefolgt von der Beschreibung „ \brief “ aus der eigenen Dokumentation des Eintrags, in derselben Form wie die Auflistungen auf den Seiten \group und \module.

Konzeptverweise auf undokumentierte Konzepte, wie beispielsweise Konzepte aus der Standardbibliothek, werden stillschweigend ignoriert. Sie erzeugen weder eine Seite noch wird eine Warnung ausgegeben.

Siehe auch \group, \module, und \inmodule.

\enum

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

Die Enum-Werte werden im Kommentar „ \enum “ mithilfe des \value Befehl dokumentiert. Wenn ein Enum-Wert nicht mit ` \value` dokumentiert wird, gibt QDoc eine Warnung aus. Diese Warnungen lassen sich mit dem \omitvalue Befehl vermieden werden, mit dem QDoc mitgeteilt wird, dass ein Enum-Wert nicht dokumentiert werden soll. Die Enum-Dokumentation wird auf der Klassenreferenzseite, der Header-Datei-Seite oder der Namespace-Seite eingebunden, auf der der Enum-Typ definiert ist. Betrachten wir beispielsweise den Enum-Typ ` Corner ` im Qt-Namespace:

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 Enumeration kann wie folgt 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 Angabe 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 Variablen „exampledirs“ in der QDoc-Konfigurationsdatei aufgeführt sind.

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

Wenn „exampledirs“ beispielsweise „ $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

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

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

Auf diese Weise können Sie einen Link zur 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 dasselbe Ergebnis ohne den Befehl „ \externalpage “ zu erzielen, müssten Sie die Adresse fest in Ihre Dokumentation einfügen:

/*!
    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 “ erleichtert die Pflege der Dokumentation. Wenn sich die Adresse ändert, müssen Sie lediglich das Argument des Befehls „ \externalpage “ anpassen.

\fn (Funktion)

Der Befehl ` \fn ` dient zur Dokumentation einer Funktion. Das Argument ist die Signatur der Funktion, einschließlich ihrer Template-Parameter (falls vorhanden), des Rückgabetyps, der `const`-Eigenschaft und der Liste der formalen Argumente mit ihren Typen. Wenn die genannte 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 vorteilhaft sein, „auto“ anstelle des tatsächlichen Typs einer Funktion zu verwenden. Durch die Verwendung von „ auto “ als Rückgabetyp im Befehl „ \fn “ kann der Autor dies explizit tun, auch für Typen, die ohne das Schlüsselwort „auto“ definiert sind.

Seit QDoc-Version 6.0 kann der Befehl „ \fn “ zur Dokumentation von Klassenmitgliedern verwendet werden, die nicht explizit im Header deklariert, sondern implizit vom Compiler generiert werden: Standardkonstruktor und -destruktor, Kopierkonstruktor und Move-Kopierkonstruktor, Zuweisungsoperator und Move-Zuweisungsoperator.

Bei der Dokumentation eines „hidden friend“ können Sie entweder die klassenqualifizierte Syntax oder die unqualifizierte Syntax für freie Funktionen verwenden. Zum Beispiel für:

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

Der Befehl kann als ` "\fn Foo::operator==(const Foo&, const Foo&)" ` oder als freie Funktion ` "\fn bool operator==(const Foo&, const Foo&)"` geschrieben werden. QDoc ermittelt „Hidden Friends“, indem es nach Klassen sucht, auf die in den Parametertypen der Funktion verwiesen wird.

/*!
    \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 anderen Entitäten aufgelistet sind, die zu einer bestimmten Gruppe gehören. Das Argument ist der Name der Gruppe.

Eine Klasse wird mithilfe des \ingroup Befehls. Auch Übersichtsseiten können mit demselben Befehl einer Gruppe zugeordnet werden, allerdings muss die Liste der Übersichtsseiten explizit mit dem \generatelist Befehl (siehe Beispiel unten).

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

Jedes Element der Gruppe wird als Link (unter Verwendung des Seitentitels oder Klassennamens) aufgelistet, gefolgt von einer Beschreibung aus dem \brief Befehl in der Dokumentation der Entität.

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

QDoc generiert eine Gruppenseite unter io.html.

Beachten Sie, dass Übersichtsseiten, die sich auf die Gruppe beziehen, explizit mit dem \generatelist Befehl mit dem Argument „ related “ explizit aufgeführt 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 dazu, die globalen Funktionen, Typen und Makros zu dokumentieren, die in einer Header-Datei, jedoch nicht in einem Namensraum deklariert sind. Das Argument ist der Name der Header-Datei. Die HTML-Seite wird in eine Datei namens „ .html “ geschrieben, die aus dem Argument „Header-Datei“ erstellt wird.

Die Dokumentation für eine Funktion, einen Typ oder ein Makro, die bzw. das in der zu dokumentierenden Header-Datei deklariert ist, wird mithilfe des Befehls \relates Befehl in die Seite der Header-Datei eingebunden.

Existiert das Argument nicht als Header-Datei, erstellt der Befehl „ \headerfile “ dennoch 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 generiert eine Seite für die Header-Datei „ qtalgorithms.html “.

Siehe auch \inheaderfile.

\macro

Der Befehl „ \macro “ dient zur Dokumentation eines C++-Makros. Das Argument ist das Makro in einem von drei Formaten: funktionsähnliche Makros wie Q_ASSERT(), Makros im Deklarationsstil wie Q_PROPERTY() und Makros ohne Klammern wie Q_OBJECT.

Der Kommentar „ \macro “ muss einen \relates Befehl enthalten, der den Makrokommentar einer Klasse, einer Header-Datei oder einem Namensraum zuordnet. Andernfalls geht die Dokumentation verloren.

\module

Der Befehl „ \module “ erstellt eine Seite, auf der die Klassen aufgelistet sind, die zu dem durch das Argument des Befehls angegebenen Modul gehören. Eine Klasse, die durch Einbinden des \inmodule Befehls in den „ \class “-Kommentar.

Auf den Befehl „ \module “ folgt in der Regel ein \title und einem \brief Befehl. Jede Klasse wird als Link zur Klassenreferenzseite aufgeführt, gefolgt vom Text des \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 \noautolist Befehl kann hier verwendet werden, um die automatisch generierte Liste der Klassen am Ende wegzulassen.

Siehe auch \inmodule

\namespace

Der Befehl „ \namespace “ dient dazu, den Inhalt des C++-Namensraums zu dokumentieren, dessen Name als Argument angegeben wird. Die Referenzseite, die QDoc für einen Namensraum generiert, ähnelt der Referenzseite, die es für eine C++-Klasse generiert.

/*!
    \namespace Qt

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

Beachten Sie, dass in C++ ein bestimmter Namespace in mehr als einem Modul verwendet werden kann. Wenn jedoch C++-Elemente aus verschiedenen Modulen im selben Namespace deklariert werden, darf der Namespace selbst nur in einem Modul dokumentiert werden. Beispielsweise enthält der Namespace „Qt“ im obigen Beispiel Typen und Funktionen sowohl aus „ QtCore “ als auch aus „ QtGui “, wird jedoch mit dem Befehl „ \namespace “ ausschließlich 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 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 unter aboutqt.html.

\property

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

Eine Eigenschaft wird mit dem Makro „ Q_PROPERTY()“ definiert. Das Makro nimmt als Argumente den Namen der Eigenschaft sowie deren Set-, Reset- und Get-Funktionen entgegen.

Q_PROPERTY(QString state READ state WRITE setState)

Die Funktionen „set“, „reset“ und „get“ müssen nicht dokumentiert werden; es reicht aus, die Eigenschaft zu dokumentieren. QDoc generiert eine Liste der Zugriffsfunktionen, die in der Dokumentation der Eigenschaft erscheint, die wiederum in der Dokumentation der Klasse zu finden ist, die die Eigenschaft definiert.

Der Befehlskommentar „ \property “ enthält in der Regel einen \brief Befehl. Bei Eigenschaften ist das \brief Argument des Befehls ein Satzfragment, das in eine einzeilige Beschreibung der Eigenschaft aufgenommen wird. Der Befehl folgt denselben Regeln für die Beschreibung wie der \variable Befehl.

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

    This property's default is false.
*/

\qmlattachedmethod

Der Befehl „ \qmlattachedmethod “ dient zur Dokumentation einer Methode, die an einen QML-Typ angehängt ist (angehängte Eigenschaften). Der Befehl „ \qmlattachedmethod “ wird genauso verwendet wie der \qmlmethod Befehl verwendet.

Das Argument ist der Rest der Zeile und muss die vollständige Methodensignatur sein, beginnend mit dem Rückgabetyp, gefolgt vom Namen des QML-Typs, in dem die Methode deklariert ist, dem Qualifizierer „ :: “ und schließlich dem Methodennamen mit den in Klammern eingeschlossenen Parametertypen und -namen. Wenn eine Methode keine Argumente benötigt, verwende „ () “.

Um beispielsweise eine angehängte Methode namens „ show() “ für den Typ „ ToolTip “ zu dokumentieren:

/*!
    \qmlattachedmethod void QtQuick.Controls::ToolTip::show(string text, int timeout = -1)

    This attached method shows the shared tool tip with \a text for
    \a timeout milliseconds. You can attach the method to any item.
*/

QDoc fügt diese Dokumentation auf der QML-Referenzseite für den Typ „ ToolTip “ ein.

\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. Es muss mit dem Eigenschaftstyp beginnen, gefolgt vom Namen des QML-Typs, in dem die Eigenschaft deklariert ist, dem Qualifizierer „ :: “ und schließlich dem Eigenschaftsnamen.

Um beispielsweise eine boolesche QML-zugeordnete Eigenschaft namens „ 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 nimmt diese angehängte Eigenschaft in die QML-Referenzseite für den Typ „ ListView “ auf.

\qmlattachedsignal

Der Befehl „ \qmlattachedsignal “ dient zur Dokumentation eines anbindbaren Signals. Der Befehl „ \qmlattachedsignal “ wird genauso verwendet wie der \qmlsignal Befehl verwendet.

Das Argument ist der Rest der Zeile. Es sollte aus dem Namen des QML-Typs, in dem das Signal deklariert ist, dem Qualifizierer „ :: “ und schließlich dem Signalnamen bestehen. Beispielsweise wird ein in der QML-Datei „ GridView “ im Element „ “ deklariertes Signal namens „ add() “ wie folgt dokumentiert:

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

QDoc fügt diese Dokumentation auf der QML-Referenzseite für das Element „ GridView “ ein.

\qmlvaluetype

Der Befehl „ \qmlvaluetype “ dient dazu, einen Werttyp für QML zu dokumentieren. Der Befehl nimmt einen Typnamen als einziges Argument entgegen.

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

\qmlclass

Dieser Befehl ist veraltet. Verwenden Sie \qmltype stattdessen.

\qmlenum

Der Befehl „ \qmlenum “ dient zur Dokumentation einer QML-Enumeration. Der Befehl erwartet ein einziges Argument: den vollständigen Namen des Enumerationstyps, einschließlich des übergeordneten QML-Typs und optional des QML-Moduls.

Die Enumeratoren und ihre Beschreibungen werden mithilfe der \value Befehle dokumentiert.

Beispielsweise

/*!
    \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 generiert eine Dokumentation für einen Enumerationskanal mit drei Enumeratoren: Color.R, Color.G und Color.B. Standardmäßig wird der Name des übergeordneten QML-Typs als Präfix für die Enumeratoren verwendet.

Wenn das erste Argument des Befehls `qdoccmd{value}` bereits ein Präfix enthält, wird dieses unverändert übernommen:

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

Hier werden die Enumeratoren als „Channel.R“, „Channel.G“ und „Channel.B“ aufgeführt.

Alternativ ist es möglich, die Dokumentation der Enumeratoren aus einem bestehenden C++- \enum Thema mithilfe des \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 und muss den Rückgabetyp sowie die Parameternamen und -typen in Klammern enthalten. Wenn eine Methode keine Argumente benötigt, verwenden Sie „ () “.

/*!
    \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 fügt diese Dokumentation auf der Typreferenzseite für den Typ „ TextInput “ ein.

\qmltype

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

Wenn der QML-Typ eine entsprechende C++-Klasse hat, können Sie diese Klasse mit dem \nativetype Befehl „context“ 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 ü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 \qmltype Kommentar enthält \nativetype , um anzugeben, dass ein „Transform“ das QML-Äquivalent zur C++-Klasse „ QGraphicsTransform “ ist. Ein „ \qmltype “-Kommentar sollte immer den \since Befehl enthalten, da alle QML-Typen neu sind. Er sollte außerdem eine \brief Beschreibung enthalten. Wenn ein QML-Typ Mitglied einer QML-Typgruppe ist, sollte der \qmltype -Kommentar einen oder mehrere \ingroup Befehle enthalten.

\qmlsingletontype

Der Befehl „ \qmlsingletontype “ dient dazu, einen QML-Singleton-Typ explizit zu dokumentieren. Dieser Befehl ist funktional identisch mit \qmltype, kennzeichnet den Typ jedoch unabhängig von der C++-Implementierung explizit als Singleton.

Ein QML-Singleton-Typ stellt sicher, dass in der QML-Engine nur eine Instanz existiert. Die Singleton-Kennzeichnung wird in der generierten Dokumentation durch den Hinweis „(Singleton)“ im Titel sowie durch einen erläuternden 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.
*/

Bei C++-Klassen, die das Makro „ QML_SINGLETON “ verwenden, sollten Sie stattdessen \qmltype , da QDoc den Singleton-Charakter automatisch aus dem C++-Code erkennt.

Siehe auch \qmluncreatabletype.

\qmluncreatabletype

Der Befehl „ \qmluncreatabletype “ dient dazu, einen Typ explizit zu dokumentieren, der im QML-Typsystem registriert ist, aber nicht direkt in QML instanziiert werden kann.

Dieser Befehl ist funktional identisch mit \qmltype, kennzeichnet den Typ jedoch unabhängig von der C++-Implementierung explizit als nicht erstellbar.

Die Kennzeichnung als „nicht erstellbar“ wird in der generierten Dokumentation durch den Hinweis „(Nicht erstellbar)“ im Titel sowie durch einen erläuternden Vermerk angezeigt.

/*!
    \qmluncreatabletype Dialog
    \inqmlmodule QtQuick.Dialogs

    \brief The base type of native dialogs.
*/

Bei C++-Klassen, die das Makro „ QML_UNCREATABLE “ verwenden, sollten Sie stattdessen \qmltype , da QDoc die Nicht-Erstellbarkeit automatisch aus dem C++-Code erkennt.

Der Befehl „ \qmluncreatabletype “ wurde in Qt 6.12 in QDoc eingeführt.

Siehe auch \qmlsingletontype.

\qmlproperty

Der Befehl „ \qmlproperty “ dient zur Dokumentation einer QML-Eigenschaft. Das Argument ist der Rest der Zeile. Der Argumenttext sollte aus dem Eigenschaftstyp bestehen, gefolgt vom QML-Typnamen, dem Qualifizierer „ :: “ und schließlich dem Eigenschaftsnamen. Wenn wir eine QML-Eigenschaft namens „ x “ im QML-Typ „ Translate “ haben und die Eigenschaft den Typ „ real “ hat, würde der „ \qmlproperty “ dafür wie folgt aussehen:

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

QDoc nimmt diese QML-Eigenschaft in die 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 eine C++-Enumeration bereitstellt, wird die QML-Eigenschaft mit dem Typ „ enumeration “ definiert:

\qmlproperty enumeration ParticleShape3D::ShapeType

Eigenschaften mit Enumerationstyp und solche, die eine bitweise Kombination von Flags enthalten, können den \value Befehl verwenden, um die zulässigen 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 die Modulkennung (oben: „ QtQuick.Controls “) mit dem Wert übereinstimmen, der an den \inqmlmodule Befehl in der zugehörigen Dokumentation unter \qmltype übergeben wird. Ist der Name des QML-Typs, zu dem die Eigenschaft gehört, unter allen Typen im Dokumentationsprojekt eindeutig, kann die Modulkennung weggelassen werden.

\qmlsignal

Der Befehl ` \qmlsignal ` dient zur Dokumentation eines QML-Signals. Das Argument ist der Rest der Zeile. Die Argumente sollten lauten: der QML-Typ, in dem das Signal deklariert ist, der Qualifizierer ` :: ` und schließlich der Name des Signals. Wenn wir ein QML-Signal namens ` 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 fügt diese Dokumentation auf der QML-Referenzseite für den Typ „ MouseArea “ ein.

\qmlmodule

Verwenden Sie den Befehl „ \qmlmodule “, um eine „ QML “-Modulseite zu erstellen. Eine QML-Modulseite ist eine Sammlung von QML-Typen oder sonstigem zugehörigem Material. Der Befehl akzeptiert ein optionales Argument in Form einer „ <VERSION> “-Nummer und ähnelt dem Befehl „group“.

Ein QML-Typ wird einem Modul zugeordnet, indem der \inqmlmodule Befehls zum Kommentarblock, der den Typ dokumentiert. Sie können auf jedes Element eines QML-Moduls verweisen, indem Sie den Modulnamen mit zwei Doppelpunkten (::) 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, auf der alle Elemente des Moduls aufgelistet sind.

/*!
    \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 Topic. Der Befehl nimmt den Modulnamen (Import) ohne Versionsnummer als einziges Argument entgegen.

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

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

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

QDoc gibt eine Import-Anweisung der Form „import <qmlmodule>“ in einer Tabelle am Anfang der QML-Typreferenzseite aus.

Beim Verlinken auf QML-Typen kann der QML-Modulbezeichner im Linkziel erscheinen. Zum Beispiel:

\l {ClickableComponents::}{ClickableButton}

Links zur Typreferenzseite, wobei „ClickableButton“ als Linktext verwendet wird.

\instantiates

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

\nativetype

Der Befehl „ \nativetype “ muss in Verbindung mit dem \qmltype Befehl „topic“ verwendet werden. Der Befehl nimmt eine C++-Klasse als Argument entgegen. 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 “, um anzugeben, wie der Typ in C++ heißt. Dadurch wird sichergestellt, dass der in der Dokumentation für den QML-Typ generierte Requisites-Block einen Eintrag „In C++“ enthält. Die C++-Klasse verfügt über einen entsprechenden Eintrag „In QML“.

Ein QML-Typ kann nur einen nativen Typ haben. QDoc gibt eine Warnung aus, wenn eine Neudefinition auftritt. Es können jedoch mehrere QML-Typen dieselbe C++-Klasse als nativen Typ haben. Die Dokumentation der C++-Klasse 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 umfasst das \qmltype Thema umfasst \nativetype , um anzugeben, dass ein „Transform“ in C++ als „ QGraphicsTransform “ bezeichnet wird.

\typealias

Der Befehl „ \typealias “ ähnelt \typedef, ist jedoch speziell für die Dokumentation eines C++-Typalias vorgesehen:

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

Dies kann wie folgt dokumentiert werden:

/*!
    \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++-Typdefinitionsbezeichners (typedef). Das Argument ist der Name des Typdefinitionsbezeichners. Die Dokumentation für den Typdefinitionsbezeichner wird in die Referenzdokumentation der Klasse, des Namespace oder der Header-Datei aufgenommen, in der der Typdefinitionsbezeichner deklariert ist. Um den Befehl „ \typedef “ mit einer Klasse, einem Namespace oder einer Header-Datei zu verknüpfen, muss der Kommentar „ \typedef “ den Befehl \relates Befehl enthalten.

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

Andere `typedef`s 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 zur Dokumentation einer Klassenmitgliedvariablen oder einer Konstante. Das Argument ist der Name der Variablen oder Konstante. Der Kommentar des Befehls „ \variable “ enthält einen \brief Befehl. QDoc generiert die Dokumentation auf der Grundlage des Textes aus dem Befehl „ \brief “.

Die Dokumentation wird in der Dokumentation der zugehörigen Klasse, der Header-Datei oder des Namespace abgelegt.

Im Falle einer Member-Variablen:

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

Sie können Konstanten auch mit dem Befehl „ \variable “ dokumentieren. Angenommen, Sie haben die Konstanten „ Type “ und „ UserType “ in der Klasse „ QTreeWidgetItem “:

enum { Type = 0, UserType = 1000 };

Für diese können Sie den Befehl ` \variable ` wie folgt verwenden:

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