Dokumentationskategorien

Es gibt verschiedene Arten vordefinierter Dokumentationskategorien oder -typen:

• Artikel
• C++-API-Dokumentation
• QML-Typ-Dokumentation
• Code-Beispiel

QDoc kann eine Seite je nach Typ formatieren. Darüber hinaus ermöglichen Stylesheets eine zusätzliche Steuerung der Darstellung der einzelnen Kategorien.

API-Dokumentation

QDoc eignet sich hervorragend zur Erstellung von API-Dokumentation auf der Grundlage von Quellcode und Dokumentation in QDoc-Kommentaren. Insbesondere kennt QDoc die Architektur von Qt und kann das Vorhandensein von Dokumentation zu Qt-C++-Klassen, -Funktionen oder -Eigenschaften überprüfen. QDoc gibt Warnungen und Fehler aus, wenn es eine Dokumentation nicht einer Code-Entität zuordnen kann oder wenn eine Code-Entität keine Dokumentation aufweist.

Im Allgemeinen gibt es für jede Qt-Code-Entität wie Eigenschaften, Klassen, Methoden, Signale und Aufzählungen einen entsprechenden „topic“-Befehl. QDoc ordnet die Dokumentation anhand der C++-Namenskonventionen dem Quellcode zu.

QDoc analysiert die Header-Dateien (in der Regel „ .h “-Dateien), um eine Baumstruktur der Klassenstrukturen zu erstellen. Anschließend analysiert QDoc die Quelldateien und Dokumentationsdateien, um die Dokumentation der Klassenstruktur zuzuordnen. Danach generiert QDoc eine Seite für die Klasse.

Sprachliche Stilrichtlinien

Um eine qualitativ hochwertige API-Dokumentation zu erstellen, folgen die Qt-API-Referenzen bestimmten Sprachrichtlinien. Während der Inhalt dieser Seite zeigt, wie API-Dokumentation erstellt wird, veranschaulichen die Stilrichtlinien, wie die Referenzmaterialien eine einheitliche Sprachverwendung gewährleisten.

• C++-Dokumentationsstil
• QML-Dokumentationsstil

Dokumentation von QML-Typen

In der Welt von QML gibt es zusätzliche Elemente, die dokumentiert werden müssen, wie z. B. QML-Signale, angehängte Eigenschaften und QML-Methoden. Intern nutzen sie zwar Qt-Technologien, doch die QML-API-Dokumentation erfordert andere Layout- und Namenskonventionen als die Qt-C++-API-Dokumentation.

Eine Liste der QML-bezogenen QDoc-Befehle:

• \qmlattachedmethod
• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - Erstellt eine Dokumentation für einen QML-Typ
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

Um einen QML-Typ zu dokumentieren, erstellen Sie zunächst einen QDoc-Kommentar, der den \qmltype Befehl als Themenbefehl verwendet.

QML-Parser

Wenn Ihr QML-Typ in einer QML-Datei definiert ist, dokumentieren Sie ihn dort. Wenn Ihr QML-Typ durch eine C++-Klasse dargestellt wird, dokumentieren Sie ihn in der CPP-Datei dieser C++-Klasse und fügen Sie den \nativetype Befehl ein, um den Namen der C++-Klasse anzugeben. Dokumentieren Sie einen QML-Typ nicht in einer cpp- Datei, wenn der QML-Typ in einer qml- Datei definiert ist.

Wenn Sie einen QML-Typ in einer QML -Datei dokumentieren, platzieren Sie jeden QDoc-Kommentar direkt über der Entität, auf die sich der Kommentar bezieht. Platzieren Sie beispielsweise den QDoc-Kommentar, der den \qmltype Befehl (den Themenkommentar) enthält, direkt über dem äußeren QML-Typ in der QML-Datei. Platzieren Sie den Kommentar zur Dokumentation einer QML-Eigenschaft direkt über der Eigenschaftsdeklaration und verfahren Sie ebenso bei QML-Signal-Handlern und QML-Methoden. Beachten Sie, dass Sie bei der Dokumentation von QML-Eigenschaften in einer QML-Datei den \qmlproperty Befehl als Themenbefehl einfügen (was bei der Dokumentation von QML-Typen in CPP-Dateien erforderlich ist), da der QML-Parser jeden QDoc-Kommentar automatisch der nächsten von ihm geparsten QML-Deklaration zuordnet. Das Gleiche gilt für Kommentare zu QML-Signal-Handlern und QML-Methoden. Manchmal ist es jedoch sinnvoll, einen oder mehrere \qmlproperty Befehle in den Kommentar einzufügen, z. B. wenn der Eigenschaftstyp ein anderer QML-Typ ist und Sie möchten, dass der Benutzer nur bestimmte Eigenschaften innerhalb dieses anderen QML-Typs verwendet, nicht jedoch alle. Wenn Sie jedoch eine Eigenschaft dokumentieren, die einen Alias hat, platzieren Sie den QDoc-Kommentar dafür direkt über der Alias-Deklaration. In diesen Fällen muss der QDoc-Kommentar den Befehl \qmlproperty Befehl enthalten, da QDoc nur so den Typ der mit einem Alias versehenen Eigenschaft erkennen kann.

Wenn du einen QML-Typ in der cpp- Datei der zugehörigen C++-Klasse (sofern vorhanden) dokumentierst, platzierst du normalerweise jeden QDoc-Kommentar direkt über die Entität, die er dokumentiert. QDoc verwendet jedoch nicht den QML-Parser, um diese Dateien zu analysieren (es wird der C++-Parser verwendet), sodass diese QML-QDoc-Kommentare an beliebiger Stelle in der cpp-Datei erscheinen können. Beachten Sie, dass QML-QDoc-Kommentare in cpp-Dateien die QML-Topic-Befehle verwenden müssen, d. h., der \qmltype Befehl im QDoc-Kommentar für den QML-Typ enthalten sein, und ein \qmlproperty Befehl in jedem QDoc-Kommentar zu einer QML-Eigenschaft enthalten sein.

QML-Module

Ein QML-Typ gehört zu einem Modul. Das Modul kann alle zugehörigen Typen für eine Plattform umfassen oder eine bestimmte Version von Qt Quick. Beispielsweise gehören die QML-Typen aus „ Qt Quick 2“ zum Modul „ Qt Quick 2“, während es für die älteren, in Qt 4 eingeführten Typen auch ein Modul „ Qt Quick 1“ gibt.

QML-Module ermöglichen die Gruppierung von QML-Typen. Der \qmltype Befehl „topic“ muss einen \inqmlmodule „context“-Befehl enthalten, um den Typ einem QML-Modul zuzuordnen. Ebenso muss ein \qmlmodule „topic“-Befehl in einer separaten „ .qdoc “-Datei vorhanden sein, um die Übersichtsseite für das Modul zu erstellen. Die Übersichtsseite listet die QML-Typen des QML-Moduls auf.

Die Links zu den QML-Typen müssen daher ebenfalls den Modulnamen enthalten. Befindet sich beispielsweise ein Typ namens „ TabWidget “ im Modul „ UIComponents “, muss er als „ UIComponents::TabWidget “ verlinkt werden.

Schreibgeschützte und interne QML-Eigenschaften

QDoc erkennt QML-Eigenschaften, die als „ readonly “ gekennzeichnet sind. Beachten Sie, dass die Eigenschaft mit einem Wert initialisiert werden muss.

readonly property int sampleReadOnlyProperty: 0

Eigenschaften und Signale, die nicht für die öffentliche Schnittstelle bestimmt sind, können mit dem \internal Befehl gekennzeichnet werden. QDoc veröffentlicht die Dokumentation dann nicht in den generierten Ausgaben.

Artikel und Übersichten

Artikel und Übersichten sind eine Schreibweise, die sich am besten eignet, um eine zusammenfassende Darstellung zu einem Thema oder Konzept zu liefern. Sie können eine Technologie vorstellen oder erörtern, wie ein Konzept angewendet werden kann, ohne dabei jedoch die genauen Schritte allzu detailliert zu beschreiben. Diese Art von Inhalten kann jedoch als Einstieg für Leser dienen, um Anleitungen und Referenzmaterialien zu finden, die dies tun, wie z. B. Tutorials, Beispiele und Klassendokumentation. Ein Beispiel für einen Überblick könnte eine Produktseite sein, wie z. B. eine allgemeine Erörterung von „ Qt Quick “, einzelner Module, Entwurfsprinzipien oder Werkzeuge.

Um anzugeben, dass es sich bei einem Dokument um einen Artikel handelt, fügen Sie dem Befehl „ \page “ das Schlüsselwort „article“ hinzu:

/*!
    \page overview-qt-technology.html
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

Der Abschnitt „Befehle zum Verfassen von Themen “ enthält eine Auflistung der verfügbaren Argumente für den Befehl „ \page “.

Code-Beispiele

Beispiele sind eine effektive Möglichkeit, die praktische Anwendung einer bestimmten Technologie oder eines Konzepts zu veranschaulichen. Im Zusammenhang mit Middleware geschieht dies in der Regel in Form einer Anwendung mit einfachem Code und klaren Erläuterungen dazu, was der Code bewirkt. Jedes Modul, jede API, jedes Projekt, jedes Muster usw. sollte mindestens ein gutes Beispiel enthalten.

Ein Beispiel kann von einem begleitenden Tutorial begleitet werden. Das Tutorial erklärt und beschreibt den Code, während das Code-Beispiel den Code-Inhalt darstellt, den Benutzer studieren können. Code-Beispiele können Begleittexte enthalten, die nicht im Tutorial vorkommen.

QDoc erstellt mithilfe des Befehls \example Befehl.

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc verwendet das in der Eingabevariablen `exampledirs ` angegebene Verzeichnis, um die Qt-Project-Datei (.pro) zu finden und die Beispieldateien zu generieren. Die generierte HTML-Datei erhält den Dateinamen ` declarative-ui-components-tabwidget.html`. QDoc listet außerdem den gesamten Beispielcode auf.