Diese Befehle bieten verschiedene Funktionen, die sich auf die optische Gestaltung der Dokumentation sowie auf den Prozess der Dokumentationserstellung beziehen.

\annotatedlist

Der Befehl „ \annotatedlist “ erweitert sich zu einer Liste der Mitglieder einer Gruppe, wobei jedes Mitglied mit seinem Kurztext aufgeführt wird. Nachfolgend finden Sie ein Beispiel aus der Qt-Referenzdokumentation:

/*!
   ...
   \section1 Drag and Drop Classes

   These classes deal with drag and drop and the necessary mime type
   encoding and decoding.

   \annotatedlist draganddrop
*/

\ingroup Dadurch wird eine Liste aller C++-Klassen und/oder QML-Typen in der Gruppe „draganddrop“ generiert. Eine C++-Klasse oder ein QML-Typ in der Gruppe „draganddrop“ enthält in ihrem \class oder \qmltype Kommentar.

Die Gruppenelemente werden in aufsteigender Reihenfolge nach dem für den Benutzer sichtbaren Namen oder Titel sortiert. Seit QDoc 6.8 unterstützen „ \annotatedlist “ und \generatelist unterstützen zudem eine benutzerdefinierte Sortierung.

Siehe auch \generatelist und „Sortieren von Gruppenmitgliedern“.

\cmakepackage

Verwenden Sie den Befehl „ \cmakepackage “, um CMake-Paketinformationen zu Klassen und Namespaces hinzuzufügen. Diese Informationen werden dann in einer Tabelle oben auf der Dokumentationsseite der Klasse oder des Namespaces angezeigt. Beispiel:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc gibt dies wie folgt aus:

Foo-Namensraum

Ein Namespace. Mehr...

Kopfzeile:	#include <Bar>
CMake:	find_package(Baz REQUIRED) target_link_libraries(mytarget PRIVATE Baz::Baz)

Siehe auch \module und \cmakecomponent}

\cmakecomponent

Verwenden Sie den Befehl „ \cmakecomponent “, um Informationen zu CMake-Komponenten zu Klassen und Namespaces hinzuzufügen. Diese Informationen werden dann in einer Tabelle oben auf der Dokumentationsseite der Klasse oder des Namespaces angezeigt. Beispiel:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDoc gibt dies wie folgt aus:

Foo-Namespace

Ein Namespace. Mehr...

Kopfzeile:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::Baz)

Siehe auch \module und \cmakepackage}

\cmaketargetitem

Verwenden Sie den Befehl ` \cmaketargetitem `, um den Elementteil der CMake- target_link_libraries sinformationen zu überschreiben, der zu Klassen und Namespaces hinzugefügt wird. Der Befehl muss in Verbindung mit dem Befehl \module und \cmakecomponent . Beispiel:

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \cmaketargetitem Qt6::BazPrivate
    \brief A namespace.

    ...
*/

QDoc gibt dies wie folgt aus:

Foo-Namespace

Ein Namespace. Mehr...

Kopfzeile:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)

Siehe auch \module und \cmakecomponent}

\qtcmakepackage

Verwenden Sie den Befehl „ \qtcmakepackage “, um CMake-Paketinformationen zu Klassen und Namespaces hinzuzufügen. Diese Informationen werden dann in einer Tabelle oben auf der Dokumentationsseite der Klasse oder des Namespaces angezeigt. Zum Beispiel:

/*!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDoc gibt dies wie folgt aus:

Foo-Namespace

Ein Namespace. Mehr...

Kopfzeile:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz)

\qtcmaketargetitem

Verwenden Sie den Befehl „ \qtcmaketargetitem “, um den „item “-Teil der CMake- target_link_libraries -Informationen zu überschreiben, die zu Klassen und Namespaces hinzugefügt werden. Der Befehl muss in Verbindung mit dem Befehl \module und \qtcmakepackage Befehlen verwendet werden.

Siehe auch \module und \qtcmakepackage}

\generatelist

Der Befehl „ \generatelist “ wird zu einer Liste von Links auf Dokumentationselemente erweitert, die anhand eines \ingroup Befehl gruppiert sind, oder zu Elementen, die einem der unten aufgeführten Argumente entsprechen. Ein Beispiel aus der Qt-Referenzdokumentation:

/*!
   \page classes.html
   \title All Classes

   For a shorter list that only includes the most
   frequently used classes, see \l{Qt's Main Classes}.

   \generatelist classes Q
*/

Dadurch wird die Seite „Alle Klassen “ generiert. Der Befehl akzeptiert die folgenden Argumente:

<group-name>

Wird als einziges Argument ein Gruppenname angegeben, listet QDoc alle Entitäten auf, die den Befehl „ \ingroup <group-name> “ verwenden.

Sortieren von Gruppenmitgliedern

Bei der Erstellung einer Liste der Gruppenmitglieder werden diese in aufsteigender Reihenfolge nach dem für den Benutzer sichtbaren Namen oder Titel sortiert. Seit QDoc 6.8 kann die Standardsortierreihenfolge geändert werden:

\generatelist [descending] changelogs

Angenommen, die Gruppe „Changelogs“ besteht aus Seiten, die Änderungen in verschiedenen Versionen beschreiben, wird die Liste in absteigender Reihenfolge erstellt (die neueste Version steht an erster Stelle).

Sortierschlüssel

Seit QDoc 6.8 kann einem oder mehreren Gruppenmitgliedern mithilfe des \meta Befehl:

\meta sortkey {sort key}

Die Sortierung (aufsteigend oder absteigend) erfolgt dann anhand dieser Schlüssel und nicht anhand der für den Benutzer sichtbaren Titel.

annotatedclasses

Das Argument „ annotatedclasses “ liefert eine Tabelle mit den Namen aller Klassen und einer Beschreibung der jeweiligen Klasse. Jeder Klassenname ist ein Link zur Referenzdokumentation der Klasse. Zum Beispiel:

Eine C++-Klasse wird mit dem \class Befehl dokumentiert. Die Anmerkung zur Klasse wird aus dem Argument des Befehls \brief Befehls des Klassenkommentars.

annotatedexamples

Das Argument „ annotatedexamples “ liefert eine vollständige Liste aller Beispiele in Form einer Reihe von Tabellen, die die Titel aller Beispiele sowie eine Beschreibung jedes Beispiels enthalten. Jeder Titel ist ein Link zur Dokumentation des jeweiligen Beispiels.

Für jedes Modul (das über dokumentierte Beispiele verfügt) wird eine eigene Tabelle generiert, sofern das Modul die Konfigurationsvariable `navigation.landingpage` definiert hat. Die Variable `landingpage` wird als Titel für eine Kopfzeile verwendet, die jeder Tabelle vorangestellt wird.

annotatedattributions

Das Argument „ annotatedattributions “ liefert eine vollständige Liste aller Quellenangaben in Form einer Reihe von Tabellen, die die Titel aller Quellenangaben sowie eine Beschreibung der einzelnen Quellenangaben enthalten. Jeder Titel ist ein Link zur Seite der jeweiligen Quellenangabe.

Für jedes Modul (das Attribute enthält) wird eine separate Tabelle generiert, vorausgesetzt, das Modul hat die Konfigurationsvariable „navigation.landingpage“ definiert. Die Variable „landingpage“ wird als Titel für eine Kopfzeile verwendet, die jeder Tabelle vorangestellt wird.

classes <prefix>

Das Argument „ classes “ liefert eine vollständige alphabetische Liste der Klassen. Das zweite Argument, „ <prefix> “, ist das gemeinsame Präfix für die Klassennamen. Die Klassennamen werden anhand des Zeichens sortiert, das auf das gemeinsame Präfix folgt. Beispiel: Das gemeinsame Präfix für die Qt-Klassen lautet „ Q “. Das Argument für das gemeinsame Präfix ist optional. Wird kein gemeinsames Präfix angegeben, werden die Klassennamen anhand ihres ersten Zeichens sortiert.

Jeder Klassenname wird zu einem Link zur Referenzdokumentation der Klasse. Dieser Befehl wird verwendet, um die Seite „Alle Klassen“ wie folgt zu generieren:

/*!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
*/

Eine C++-Klasse wird mit dem \class Befehl dokumentiert.

classesbymodule

Wird dieses Argument verwendet, ist ein zweites Argument erforderlich, das das Modul angibt, dessen Klassen aufgelistet werden sollen. QDoc generiert eine Tabelle, die diese Klassen enthält. Jede Klasse wird mit dem Text ihres \brief Befehl.

Beispielsweise kann dieser Befehl auf einer Modulseite wie folgt verwendet werden:

/*!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

    ...
*/

Jede Klasse, die zum angegebenen Modul gehört, muss in ihrem \inmodule Befehl in ihrem „ \class “-Kommentar gekennzeichnet werden.

qmltypesbymodule

Ähnlich wie das Argument „ classesbymodule “, wird hier jedoch verwendet, um die QML-Typen (mit Ausnahme der QML-Werttypen) aus dem mit dem zweiten Argument angegebenen QML-Modul aufzulisten.

qmlvaluetypesbymodule

Ähnlich wie das Argument „ qmltypesbymodule “, listet jedoch stattdessen QML-Werttypen auf.

functionindex

Das Argument „ functionindex “ liefert eine vollständige alphabetische Liste aller dokumentierten Mitgliedsfunktionen. Es wird normalerweise nur zur Erstellung der Qt-Funktionsindexseite auf folgende Weise verwendet:

/*!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
*/

legalese

Das Argument „ legalese “ weist QDoc an, eine Liste der Lizenzen im aktuellen Dokumentationsprojekt zu erstellen. Jede Lizenz wird mithilfe des \legalese Befehl identifiziert.

overviews

Das Argument „ overviews “ wird verwendet, um QDoc anzuweisen, eine Liste zu erstellen, indem der Inhalt aller \group Seiten zusammenzufügen. Qt nutzt es, um die Übers ichtsseite auf folgende Weise zu erstellen:

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

Das Argument „ attributions “ wird verwendet, um QDoc anzuweisen, eine Liste der Quellenangaben in der Dokumentation zu erstellen.

related

Das Argument „ related “ wird in Kombination mit dem \group und \ingroup Befehlen verwendet, um alle Übersichten aufzulisten, die sich auf eine bestimmte Gruppe beziehen. Beispielsweise wird die Seite „Programmieren mit Qt“ auf diese Weise generiert:

/*!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
*/

Jede auf dieser Gruppenseite aufgeführte Seite enthält den Befehl:

\ingroup qt-basic-concepts

Siehe auch \annotatedlist.

\if

Der Befehl „ \if “ und der entsprechende Befehl „ \endif “ umschließen Teile eines QDoc-Kommentars, die nur dann einbezogen werden, wenn die durch das Argument des Befehls angegebene Bedingung wahr ist.

Der Befehl liest den Rest der Zeile und wertet ihn als C++-#if-Anweisung aus.

/*!
   \if defined(opensourceedition)

   \note This edition is for the development of
   \l{Qt Open Source Edition} {Free and Open Source}
   software only; see \l{Qt Commercial Editions}.

   \endif
*/

Dieser QDoc-Kommentar wird nur ausgegeben, wenn das Präprozessorsymbol ` opensourceedition ` definiert und in der Variablen `defines` in der Konfigurationsdatei angegeben ist, damit QDoc den Code innerhalb von `#ifdef` und `#endif` verarbeitet:

defines = opensourceedition

Sie können das Präprozessorsymbol auch manuell über die Befehlszeile definieren. Weitere Informationen finden Sie in der Dokumentation zur Variablen „defines “.

Siehe auch \endif, \else, ` defines ` und ` falsehoods`.

\endif

Der Befehl „ \endif “ und der entsprechende Befehl „ \if “ umschließen Teile eines QDoc-Kommentars, die eingefügt werden, wenn die durch das \if Argument des Befehls angegebenen Bedingung wahr ist.

Weitere Informationen finden Sie in der Dokumentation zum \if Befehls.

Siehe auch \if, \else, Definitionen und Falschaussagen.

\else

Der Befehl „ \else “ gibt eine Alternative an, falls die Bedingung im \if Befehl falsch ist.

Der Befehl „ \else “ kann nur innerhalb der Befehle „\if “ … „ \endif “ verwendet werden, ist jedoch nützlich, wenn nur zwei Alternativen vorhanden sind.

\include

Der Befehl ` \include ` übergibt die durch sein erstes Argument angegebene Datei ganz oder teilweise an den QDoc-Eingabestrom, damit sie als QDoc-Kommentarausschnitt verarbeitet wird.

Der Befehl ist nützlich, wenn ein Ausschnitt aus Befehlen oder Text an mehreren Stellen in der Dokumentation verwendet werden soll. Verwenden Sie den Befehl ` \include `, wo immer Sie einen Ausschnitt in die Dokumentation einfügen möchten. Die Datei, die den einzufügenden Ausschnitt enthält, muss sich unter einem der Pfade befinden, die in der QDoc-Konfigurationsvariable `sourcedirs` oder `exampledirs` aufgeführt sind. Es kann sich dabei entweder um eine beliebige von QDoc geparste Quelldatei (oder sogar um dieselbe, in der der Befehl „ \include “ verwendet wird) oder um eine beliebige andere Textdatei handeln. Um Ausschnitte in einer separaten Datei zu speichern, die nicht von QDoc geparst werden soll, verwenden Sie eine Dateiendung, die nicht in „sources.fileextensions“ aufgeführt ist; zum Beispiel „ .qdocinc “.

Der Befehl kann ein oder mehrere Argumente haben. Das erste Argument ist immer ein Dateiname. Der Inhalt der Datei muss eine QDoc-Eingabe sein, d. h. eine Abfolge von QDoc-Befehlen und Text, jedoch ohne die umschließenden QDoc-Kommentar-Trennzeichen /*! … */ . Wenn Sie die gesamte benannte Datei einbinden möchten, lassen Sie das zweite Argument leer. Wenn Sie nur einen Teil der Datei einbinden möchten, beachten Sie die unten beschriebene Form mit zwei Argumenten. Hier ist ein Beispiel für die Form mit einem Argument:

/*!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
*/

\include Dateiname Snippet-Bezeichner

Es ist Zeitverschwendung, für jedes QDoc-Include-Snippet, das Sie an mehreren Stellen in der Dokumentation verwenden möchten, eine separate „ .qdocinc “-Datei anzulegen, insbesondere da Sie wahrscheinlich in jede dieser Dateien den Copyright-/Lizenzhinweis einfügen müssen. Wenn Sie mehrere Snippets einbinden möchten, können Sie diese alle in einer einzigen Datei zusammenfassen und jedes einzelne wie folgt umschließen:

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

Anschließend können Sie die Zwei-Argument-Form des Befehls verwenden:

\include examples/signalandslots.qdocinc snippet-id2
\include examples/objectmodel.qdocinc another-snippet-id

Die Abfolge aus QDoc-Befehlen und Text, die sich zwischen den beiden Tags mit dem gleichen Namen wie das zweite Argument befindet, wird an den QDoc-Eingabestrom gesendet. Sie können sogar verschachtelte Schnipsel verwenden.

Zusätzliche Argumente

Seit QDoc 6.3 werden alle weiteren Argumente, die an den Befehl ` \include ` übergeben werden, zum Einfügen von Zeichenfolgen in den eingebundenen Inhalt verwendet. Um eine Zeichenfolge an einer bestimmten Stelle im Inhalt einzufügen, fügen Sie einen Backslash gefolgt von einer Ziffer (1..9) hinzu. Die Ziffern entsprechen der Reihenfolge in der Argumentliste. Schließen Sie Argumente in geschweifte Klammern ein, um sicherzustellen, dass QDoc das gesamte Argument, einschließlich möglicher Leerzeichen, wie von Ihnen erwartet rendert.

Beispiel: Angenommen, die folgende Codeausschnitt befindet sich in einer Datei includes.qdocinc:

//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]

Dann die folgende Zeile „ \include “:

\include includes.qdocinc {usage} {detailed output} {Verbose}

Rendert

Um eine detaillierte Ausgabe zu aktivieren, wählen Sie „ Verbose “ > „ Enable “.

\meta

Der Befehl „ \meta “ dient zum Hinzufügen von Metadaten zur Dokumentation. Der Befehl hat zwei Argumente: Das erste Argument ist der Name des Metadatenattributs, das zweite Argument ist der Wert für das Attribut. Jedes Argument sollte in geschweifte Klammern gesetzt werden, wie in diesem Beispiel gezeigt:

/*!
    \example demos/coffee
    \title Coffee Machine
    \brief A Qt Quick application with a state-based custom user interface.

    \meta {tags} {quick,embedded,states,touch}
    \meta {category} {Application Examples}
*/

Eine Reihe von Metadatenattributen hat einen bestimmten Zweck:

Beispiel-Metadaten

Eine weitere Verwendung des Befehls „ \meta “ besteht darin, Metadaten (Tags) in die \example Dokumentation einzufügen. Standardmäßig generiert QDoc Beispiel-Tags auf der Grundlage des \title und des Modulnamens. Diese Tags werden im „Willkommensmodus“ von „ Qt Creator “ angezeigt und helfen den Benutzern bei der Navigation durch die Liste der Beispiele.

Zusätzliche Tags können mit „ \meta {tag} {tag1} “ oder „ \meta {tags} {tag1,[tag2,...]} “ erstellt werden. Zum Beispiel:

/*!
    \example helloworld
    \title Hello World Example
    \meta {tags} {tutorial,basic}
*/

Dies würde zu folgenden Tags führen: tutorial,basic,hello,world. Gängige Wörter wie „Beispiel“ werden ignoriert.

Beispiele ausschließen

Wenn ein Beispiel als fehlerhaft markiert wird, wird es aus der generierten Manifestdatei ausgeschlossen und somit effektiv aus dem Willkommensmodus von Qt Creator entfernt.

\meta {tag} {broken}

Beispiele für Installationspfade

Der Befehl „ \meta “ in Kombination mit dem Argument „ installpath “ gibt den Speicherort eines installierten Beispiels an. Dieser Wert überschreibt den Wert, der über die Konfigurationsvariable „ examplesinstallpath “ festgelegt wurde.

/*!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
*/

Siehe auch examplesinstallpath.

Status

Ein „ status “-Argument für den Befehl „ \meta “ fügt eine benutzerdefinierte Statusbeschreibung für ein \class oder ein \qmltypehinzu. Diese Beschreibung erscheint dann in einer Tabelle oben auf der Typreferenzseite.

/*!
    \class QNativeInterface::QAndroidApplication
    \meta {status} {Android-specific}
*/

Siehe auch statusbezogene Befehle.

Metadaten des Dokuments

Ein Argument vom Typ „ keywords “ für den Befehl „ \meta “ fügt die angegebenen Schlüsselwörter als Metadaten zum generierten Dokument hinzu:

\meta {keywords} {reference, internal}

In der HTML-Ausgabe werden diese Schlüsselwörter als ` <meta name="keywords" content="..."> `-Element generiert.

\noautolist

Der Befehl „ \noautolist “ gibt an, dass die kommentierte Liste der C++-Klassen oder QML-Typen, die automatisch am Ende der C++- oder QML-Modulseite generiert wird, weggelassen werden soll, da die Klassen oder Typen manuell aufgelistet wurden. Dieser Befehl kann auch zusammen mit dem \group Befehl verwendet werden, um die Liste der Gruppenmitglieder wegzulassen, wenn diese manuell aufgeführt werden.

Der Befehl muss in einer eigenen Zeile stehen. Siehe Qt Quick Controls QML Types für ein Beispiel. Die Seite wird aus „ qtquickcontrols2-qmlmodule.qdoc “ generiert. Dort finden Sie einen QDoc-Kommentar, der den Befehl „ \qmlmodule “ für das Modul „ QtQuick.Controls“ enthält. Derselbe Kommentar enthält einen Befehl „ \noautolist “, um die automatische Listengenerierung zu deaktivieren, sowie einen \generatelist Befehl, um die QML-Typen in einem bestimmten Abschnitt des Dokuments aufzulisten.

Dieser Befehl wurde in QDoc 5.6 eingeführt.

Seit Qt 5.10 kann dieser Befehl auch auf \example Dokumentation angewendet werden, wobei dadurch die automatisch generierte Liste der zu einem Beispielprojekt gehörenden Dateien und Bilder weggelassen wird.

\omit

Der Befehl „ \omit “ und der entsprechende Befehl „ \endomit “ grenzen Teile der Dokumentation ab, die QDoc überspringen soll. Zum Beispiel:

/*!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
*/

\raw (vermeiden!)

Der Befehl „ \raw “ und der entsprechende Befehl „ \endraw “ grenzen einen Block mit Code in der Markup-Sprache ab.

Der Befehl erwartet ein Argument, das das Format des Codes angibt.

QDoc generiert den angegebenen Code nur dann, wenn das vom Benutzer festgelegte Format erzeugt wird.

Beispielsweise wird bei der Eingabe von „\raw HTML“ nur dann Code generiert, wenn QDoc eine HTML-Dokumentation erstellt.

\sincelist

Der Befehl „ \sincelist “ liefert eine detaillierte Aufschlüsselung der neuen Ergänzungen zur dokumentierten API in einer bestimmten Version. Anwendungsbeispiel:

/*!
   \page newclasses612.html
   \title New Classes and Functions in 6.12
   \brief A comprehensive list of new classes and functions in 6.12.

   \sincelist 6.12
*/

\sincelisterfordert ein einziges Argument, eine Versionszeichenfolge. Die generierte Ausgabe enthält alle Funktionen, die mit einem \since Befehl oder einer „since“-Klausel gekennzeichnet sind, die mit der Versionszeichenfolge übereinstimmen.

\unicode

Mit dem Befehl „ \unicode “ können Sie ein beliebiges Unicode-Zeichen in das Dokument einfügen.

Der Befehl erwartet ein Argument, das das Zeichen als Ganzzahl angibt. Standardmäßig wird die Basis 10 angenommen, sofern kein Präfix „0x“ oder „0“ angegeben wird (für die Basis 16 bzw. 8).