Diese Befehle bieten verschiedene Funktionen, die mit dem visuellen Erscheinungsbild der Dokumentation und dem Prozess der Dokumentationserstellung zusammenhängen.

\annotatedlist

Der Befehl \annotatedlist zeigt eine Liste der Mitglieder einer Gruppe an, wobei jedes Mitglied mit einem kurzen Text aufgeführt wird. Unten sehen 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
*/

Dies erzeugt eine Liste aller C++-Klassen und/oder QML-Typen in der draganddrop-Gruppe. Eine C++-Klasse oder ein QML-Typ in der draganddrop-Gruppe hat \ingroup draganddrop in ihrem \class- oder \qmltype-Kommentar.

Die Gruppenmitglieder werden in aufsteigender Reihenfolge nach dem für den Benutzer sichtbaren Namen oder Titel sortiert. Seit QDoc 6.8 unterstützen \annotatedlist und \generatelist auch die benutzerdefinierte Sortierung unterstützen.

Siehe auch \generatelist und Sortieren von Gruppenmitgliedern.

\qtcmakepackage

Verwenden Sie den Befehl \qtcmakepackage, um CMake-Paketinformationen zu Klassen und Namespaces hinzuzufügen. Diese Informationen erscheinen dann in einer Tabelle am oberen Rand der Klassen- oder Namespace-Dokumentationsseite. Zum Beispiel:

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

    ...
*/

QDoc wird dies ausgeben als

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, die Klassen und Namespaces hinzugefügt werden, zu überschreiben. Der Befehl muss in Verbindung mit den Befehlen \module und \qtcmakepackage} verwendet werden.

Siehe auch \module und \qtcmakepackage}

\generatelist

Der Befehl \generatelist expandiert zu einer Liste von Links zu den Dokumentationsentitäten, die mit einem \ingroup-Befehl gruppiert wurden, oder zu Entitäten, 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
*/

Dies erzeugt die Seite All Classes. Der Befehl akzeptiert die folgenden Argumente:

<group-name>

Mit einem Gruppennamen als einzigem Argument listet QDoc alle Entitäten auf, die den Befehl \ingroup <group-name> verwenden.

Sortieren von Gruppenmitgliedern

Wenn eine Liste von Gruppenmitgliedern erzeugt wird, werden diese in aufsteigender Reihenfolge sortiert, basierend auf dem für den Benutzer sichtbaren Namen oder Titel. Seit QDoc 6.8 kann die Standard-Sortierreihenfolge geändert werden:

\generatelist [descending] changelogs

Angenommen, die Gruppe " Changelogs" besteht aus Seiten, die Änderungen in verschiedenen Versionen enthalten, dann wird die Liste in absteigender Reihenfolge erzeugt (neueste Version zuerst).

Sortierschlüssel

Seit QDoc 6.8 kann ein benutzerdefinierter Sortierschlüssel einem oder mehreren Gruppenmitgliedern zugewiesen werden, indem der \meta Befehl:

\meta sortkey {sort key}

Die Sortierung (auf- oder absteigend) erfolgt dann auf der Grundlage dieses Schlüssels bzw. dieser Schlüssel und nicht mehr nach den für den Benutzer sichtbaren Titeln.

annotatedclasses

Das Argument annotatedclasses liefert eine Tabelle mit den Namen aller Klassen und einer Beschreibung der einzelnen Klassen. Jeder Klassenname ist ein Verweis auf die Referenzdokumentation der Klasse. Zum Beispiel:

Eine C++-Klasse wird mit dem Befehl \class dokumentiert. Die Beschriftung der Klasse wird aus dem Argument des \brief-Befehls des Klassenkommentars übernommen.

annotatedexamples

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

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

annotatedattributions

Das Argument annotatedattributions liefert eine vollständige Liste aller Attribute in Form einer Reihe von Tabellen, die die Titel aller Attribute und eine Beschreibung der einzelnen Attribute enthalten. Jeder Titel ist ein Link zu der Seite der Zuschreibung.

Für jedes Modul (das Attribute hat) wird eine eigene Tabelle erstellt, vorausgesetzt, das Modul hat eine Konfigurationsvariable navigation.landingpage definiert. Die Landingpage-Variable wird als Titel für eine Überschrift 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 nach dem Zeichen sortiert, das auf das gemeinsame Präfix folgt. Das gemeinsame Präfix für die Qt-Klassen ist z.B. Q. Das Argument des gemeinsamen Präfixes ist optional. Wenn kein gemeinsames Präfix angegeben wird, werden die Klassennamen nach ihrem ersten Zeichen sortiert.

Jeder Klassenname wird zu einem Link auf die Referenzdokumentation der Klasse. Dieser Befehl wird verwendet, um die Seite All Classes auf diese Weise zu erzeugen:

/*!
    \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 Befehl \class dokumentiert.

classesbymodule

Wenn dieses Argument verwendet wird, ist ein zweites Argument erforderlich, das das Modul angibt, dessen Klassen aufgelistet werden sollen. QDoc erzeugt eine Tabelle, die diese Klassen enthält. Jede Klasse wird mit dem Text des zugehörigen \brief-Befehls aufgelistet.

Zum Beispiel 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 Mitglied des angegebenen Moduls ist, muss mit dem Befehl \inmodule in ihrem \class-Kommentar gekennzeichnet werden.

qmltypesbymodule

Ähnlich wie das Argument classesbymodule, jedoch für die Auflistung der QML-Typen (mit Ausnahme der QML-Wertetypen) aus dem mit dem zweiten Argument angegebenen QML-Modul verwendet.

qmlvaluetypesbymodule

Ähnlich wie das Argument qmltypesbymodule, listet aber stattdessen QML-Wertetypen auf.

functionindex

Das Argument functionindex liefert eine vollständige alphabetische Liste aller dokumentierten Mitgliedsfunktionen. Es wird normalerweise nur verwendet, um die Qt-Funktionsindexseite auf diese Weise zu erzeugen:

/*!
    \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 legalese Argument weist QDoc an, eine Liste der Lizenzen im aktuellen Dokumentationsprojekt zu erzeugen. Jede Lizenz wird mit dem Befehl \legalese identifiziert.

overviews

Mit dem Argument overviews wird QDoc angewiesen, eine Liste durch Verkettung der Inhalte aller \group-Seiten zu erzeugen. Qt verwendet es, um die Übersichtsseite auf diese Weise zu erzeugen:

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

Das Argument attributions wird verwendet, um QDoc anzuweisen, eine Liste der Attributionen in der Dokumentation zu erzeugen.

related

Das Argument related wird in Kombination mit den Befehlen \group und \ingroup verwendet, um alle Übersichten aufzulisten, die sich auf eine bestimmte Gruppe beziehen. Zum Beispiel wird die Seite für die Seite Programmierung mit Qt auf diese Weise erzeugt:

/*!
    \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 Seite, die auf dieser Gruppenseite aufgeführt ist, enthält den Befehl:

\ingroup qt-basic-concepts

Siehe auch \annotatedlist.

\if

Der \if-Befehl und der entsprechende \endif-Befehl umschließen Teile eines QDoc-Kommentars, die nur eingefügt werden, wenn die durch das Argument des Befehls angegebene Bedingung erfüllt 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 gerendert, wenn das Präprozessor-Symbol opensourceedition definiert und in der defines-Variable in der Konfigurationsdatei angegeben ist, damit QDoc den Code innerhalb von #ifdef und #endif verarbeitet:

defines = opensourceedition

Sie können das Präprozessor-Symbol auch manuell in der Kommandozeile definieren. Weitere Informationen finden Sie in der Dokumentation der defines-Variable.

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

\endif

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

Weitere Informationen finden Sie in der Dokumentation des \if-Befehls.

Siehe auch \if, \else, defines und falsehoods.

\else

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

Der Befehl \else kann nur innerhalb von \if ...\endif-Befehlen verwendet werden, ist aber nützlich, wenn es nur zwei Alternativen gibt.

\include

Der Befehl \include sendet die gesamte oder einen Teil der durch sein erstes Argument angegebenen Datei an den QDoc-Eingabestrom, um als QDoc-Kommentarausschnitt verarbeitet zu werden.

Der Befehl ist nützlich, wenn ein Ausschnitt von Befehlen oder Text an mehreren Stellen in der Dokumentation verwendet werden soll. Verwenden Sie den Befehl \include überall dort, wo Sie ein Snippet in die Dokumentation einfügen wollen. Die Datei, die den einzubindenden Textausschnitt enthält, muss sich unter dem/den in der QDoc-Konfigurationsvariablen sourcedirs oder exampledirs angegebenen Pfad(en) befinden. Es kann entweder eine beliebige Quelldatei sein, die von QDoc geparst wird (oder sogar die gleiche, in der der \include-Befehl verwendet wird), oder eine beliebige andere Textdatei. Um Snippets in einer separaten Datei zu speichern, die nicht von QDoc geparst werden soll, verwenden Sie eine Dateierweiterung, 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 Folge von QDoc-Befehlen und Text, aber ohne die einschließenden QDoc-Kommentare /*! ... */ . Wenn Sie die gesamte benannte Datei einschließen wollen, lassen Sie das zweite Argument leer. Wenn Sie nur einen Teil der Datei einschließen wollen, sehen Sie sich die Form mit zwei Argumenten unten an. 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 filename snippet-identifier

Es ist Zeitverschwendung, für jedes QDoc-Include-Snippet, das Sie an mehreren Stellen in der Dokumentation verwenden wollen, eine eigene Datei .qdocinc zu erstellen, zumal Sie wahrscheinlich in jeder dieser Dateien den Copyright-/Lizenzhinweis unterbringen müssen. Wenn Sie mehrere Snippets einbinden wollen, können Sie sie alle in eine einzige Datei packen und jede mit:

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

Dann können Sie die Zwei-Argument-Form des Befehls verwenden:

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

Die Folge von QDoc-Befehlen und Text, die zwischen den beiden Tags mit demselben Namen wie das zweite Argument gefunden wird, wird an den QDoc-Eingabestrom gesendet. Sie können sogar verschachtelte Snippets haben.

Zusätzliche Argumente

Seit QDoc 6.3 werden alle weiteren Argumente, die dem \include-Befehl übergeben werden, zum Einfügen von Zeichenketten in den eingebundenen Inhalt verwendet. Um eine Zeichenkette 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 die Argumente in geschweifte Klammern ein, um sicherzustellen, dass QDoc das gesamte Argument, einschließlich möglicher Leerzeichen, so wiedergibt, wie Sie es erwarten.

Beispiel: Das folgende Snippet befindet sich in einer Datei includes.qdocinc:

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

Dann wird 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 wird verwendet, um der Dokumentation Metadaten hinzuzufügen. Der Befehl hat zwei Argumente: Das erste Argument ist der Name des Metadaten-Attributs, das zweite Argument ist der Wert für das Attribut. Jedes Argument sollte in geschweifte Klammern eingeschlossen 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 haben einen bestimmten Zweck:

Beispiel Metadaten

Ein weiterer Verwendungszweck des \meta-Befehls besteht darin, Metadaten (Tags) in die Beispieldokumentation aufzunehmen. Standardmäßig generiert QDoc Beispiel-Tags, die auf dem \Titel und dem Modulnamen des Beispiels basieren. Diese Tags werden im Willkommensmodus von Qt Creator angezeigt und helfen dem Benutzer 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 den folgenden Tags führen: tutorial,basic,hello,world. Übliche Wörter wie Beispiel werden ignoriert.

Beispiele ausschließen

Wenn Sie ein Beispiel als defekt markieren, wird es aus der generierten Manifestdatei ausgeschlossen und somit aus dem Willkommensmodus von Qt Creator entfernt.

\meta {tag} {broken}

Beispiel-Installationspfade

Der Befehl \meta in Kombination mit dem Argument installpath gibt den Speicherort eines installierten Beispiels an. Dieser Wert hat Vorrang vor dem Wert, der mit der Konfigurationsvariablen examplesinstallpath festgelegt wurde.

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

Siehe auch examplesinstallpath.

Status

Das Argument status für den Befehl \meta fügt eine benutzerdefinierte Statusbeschreibung für eine \class oder einen \qmltype hinzu. Diese Beschreibung wird dann in einer Tabelle oben auf der Typreferenzseite angezeigt.

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

Siehe auch statusbezogene Befehle.

\noautolist

Der Befehl \noautolist gibt an, dass die kommentierte Liste von 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 Befehl \group verwendet werden, um die Liste der Gruppenmitglieder auszulassen, wenn diese manuell aufgelistet wurden.

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 \qmlmodule -Befehl für das QtQuick.Controls-Modul enthält. Derselbe Kommentar enthält einen \noautolist Befehl, um die automatische Listenerzeugung zu deaktivieren, und einen \generatelist, 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 die \example-Dokumentation angewendet werden, wo er bewirkt, dass die automatisch generierte Liste von Dateien und Bildern, die zu einem Beispielprojekt gehören, weggelassen wird.

\omit

Der Befehl \omit und der entsprechende Befehl \endomit grenzen Teile der Dokumentation ab, die QDoc auslassen 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 begrenzen einen Block mit Rohcode in der Auszeichnungssprache.

Der Befehl benötigt ein Argument, das das Format des Codes angibt.

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

Zum Beispiel wird "\raw HTML" nur Code erzeugen, wenn QDoc HTML-Dokumentation erzeugt.

\sincelist

Der Befehl \sincelist führt zu einer detaillierten Aufschlüsselung der neuen Bestandteile der dokumentierten API in einer bestimmten Version. Beispiel für die Verwendung:

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

   \sincelist 6.8
*/

\sincelist benötigt ein einziges Argument, eine Versionszeichenfolge. Die generierte Ausgabe enthält alle Funktionen, die mit einem \since-Befehl oder einer since-Klausel markiert sind, die mit der Versionszeichenkette übereinstimmt.

\unicode

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

Der Befehl benötigt ein Argument, das das Zeichen als Ganzzahl angibt. Standardmäßig wird die Basis 10 angenommen, es sei denn, es wird ein '0x'- oder '0'-Präfix angegeben (für Basis 16 bzw. 8).