Kategorien der Dokumentation

Es gibt mehrere Arten von vordefinierten Dokumentationskategorien oder -typen:

• How-To's
• Anleitung
• Übersicht
• Artikel
• FAQ (Häufig gestellte Fragen)
• C++ API-Dokumentation
• QML-Typ-Dokumentation
• Code-Beispiel

QDoc hat die Möglichkeit, eine Seite je nach Typ zu formatieren. Darüber hinaus können Stylesheets zusätzliche Kontrolle über die Anzeige der einzelnen Kategorien bieten.

API-Dokumentation

QDoc zeichnet sich durch die Erstellung von API-Dokumentation aus, wenn ein Satz von Quellcode und Dokumentation in QDoc-Kommentaren vorliegt. Insbesondere kennt QDoc die Architektur von Qt und kann die Existenz von Qt C++ Klassen-, Funktions- oder Eigenschaftsdokumentation überprüfen. QDoc gibt Warnungen und Fehler aus, wenn es eine Dokumentation nicht mit einer Code-Entität assoziieren kann oder wenn eine Code-Entität keine Dokumentation hat.

Im Allgemeinen hat jede Qt Code-Entität wie Eigenschaften, Klassen, Methoden, Signale und Aufzählungen einen entsprechenden Themenbefehl. QDoc assoziiert die Dokumentation mit dem Quelltext unter Verwendung der C++-Namensregeln.

QDoc analysiert die Header-Dateien (typischerweise .h Dateien), um einen Baum der Klassenstrukturen zu erstellen. Dann analysiert QDoc die Quelldateien und Dokumentationsdateien, um die Dokumentation an die Klassenstruktur anzuhängen. Anschließend erzeugt QDoc eine Seite für die Klasse.

Sprachstile

Um eine qualitativ hochwertige API-Dokumentation zu erstellen, folgen die Qt-API-Referenzen einer bestimmten Sprachrichtlinie. Während der Inhalt dieser Seite zeigt, wie man API-Dokumentation erstellt, zeigen die Stilrichtlinien, wie die Referenzmaterialien einem konsistenten Sprachgebrauch folgen.

• C++ Dokumentationsstil
• QML-Dokumentationsstil

Dokumentieren von QML-Typen

In der Welt von QML gibt es zusätzliche Einheiten, die wir dokumentieren müssen, wie QML-Signale, angehängte Eigenschaften und QML-Methoden. Intern verwenden sie Qt-Technologien, jedoch erfordert die QML-API-Dokumentation ein anderes Layout und andere Benennungskonventionen als die Qt-C++-API-Dokumentation.

Eine Liste von QML-bezogenen QDoc-Befehlen:

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - erstellt eine QML-Typ-Dokumentation
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

Um einen QML-Typ zu dokumentieren, beginnen Sie mit der Erstellung eines QDoc-Kommentars, der den Befehl \qmltype 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 für diese C++-Klasse und fügen einen \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, für die der Kommentar gilt. Platzieren Sie zum Beispiel den QDoc-Kommentar, der den \qmltype-Befehl (den Topic-Kommentar) enthält, direkt über dem äußeren QML-Typ in der qml-Datei. Platzieren Sie den Kommentar für die Dokumentation einer QML-Eigenschaft direkt über der Eigenschaftsdeklaration, und so weiter für QML-Signalhandler und QML-Methoden. Beachten Sie, dass Sie bei der Dokumentation von QML-Eigenschaften in einer qml-Datei den \qmlproperty-Befehl normalerweise nicht als Topic-Befehl einfügen (was Sie bei der Dokumentation von QML-Typen in cpp-Dateien tun müssen), da der QML-Parser jeden QDoc-Kommentar automatisch mit der nächsten QML-Deklaration verknüpft, die er analysiert. Dasselbe gilt für QML-Signalhandler- und QML-Methodenkommentare. Manchmal ist es jedoch sinnvoll, einen oder mehrere \qmlproperty-Befehle in den Kommentar aufzunehmen, z. B. wenn der Eigenschaftstyp ein anderer QML-Typ ist und der Benutzer nur bestimmte Eigenschaften innerhalb dieses anderen QML-Typs verwenden soll, aber nicht alle. Wenn Sie jedoch eine Eigenschaft dokumentieren, die einen Alias hat, platzieren Sie den QDoc-Kommentar für diese Eigenschaft direkt über der Alias-Deklaration. In diesen Fällen muss der QDoc-Kommentar einen \qmlproperty-Befehl enthalten, da QDoc nur auf diese Weise den Typ der verknüpften Eigenschaft erkennen kann.

Wenn Sie einen QML-Typ in der cpp-Datei der zugehörigen C++-Klasse dokumentieren (sofern diese eine hat), platzieren Sie normalerweise jeden QDoc-Kommentar direkt über der Entität, die er dokumentiert. QDoc verwendet jedoch nicht den QML-Parser, um diese Dateien zu parsen (der C++-Parser wird verwendet), so dass diese QML-QDoc-Kommentare überall 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 Befehl \qmltype muss im QDoc-Kommentar für den QML-Typ erscheinen, und ein \qmlproperty-Befehl muss in jedem QML-Eigenschafts-QDoc-Kommentar erscheinen.

QML-Module

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

QML-Module ermöglichen die Gruppierung von QML-Typen. Der Topic-Befehl \qmltype muss einen Context-Befehl \inqmlmodule enthalten, um den Typ mit einem QML-Modul zu verbinden. Ebenso muss ein \qmlmodule topic-Befehl in einer separaten Datei .qdoc vorhanden sein, um die Übersichtsseite für das Modul zu erstellen. Auf der Übersichtsseite werden die QML-Typen des QML-Moduls aufgelistet.

Die Links zu den QML-Typen müssen daher auch den Namen des Moduls 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 Befehl \internal markiert werden. QDoc wird die Dokumentation in den generierten Ausgaben nicht veröffentlichen.

Artikel & Übersichten

Artikel und Übersichten sind ein Schreibstil, der am besten dazu geeignet ist, ein Thema oder ein Konzept zusammenfassend darzustellen. Sie können eine Technologie einführen oder erörtern, wie ein Konzept angewendet werden kann, ohne jedoch die genauen Schritte zu detailliert zu erläutern. Diese Art von Inhalt kann jedoch als Einstiegspunkt für die Leser dienen, um Lehr- und Referenzmaterialien zu finden, wie z. B. Tutorials, Beispiele und Klassendokumentation. Ein Beispiel für einen Überblick könnte eine Produktseite sein, z. B. eine Diskussion auf höchster Ebene über Qt Quick, einzelne Module, Designprinzipien oder Werkzeuge.

Um zu kennzeichnen, dass es sich bei einem Dokument um einen Artikel handelt, hängen Sie das Schlüsselwort article an den Befehl \page an:

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

    \brief provides a technology never seen before.

*/

Der Abschnitt Befehle zum Schreiben von Themen enthält eine Liste der verfügbaren Argumente für den Befehl \page.

Tutorials, Anleitungen, FAQ's

Tutorials, How-To's und FAQ's sind allesamt Lehrmaterial, da sie den Leser anleiten oder ihm Vorschriften machen. Tutorials sind Inhalte, die den Leser entlang eines progressiven Lernpfades für ein Konzept oder eine Technologie führen. How-To's und FAQ's(Frequently Asked Questions - häufig gestellte Fragen) bieten Anleitungen, indem sie Material in Form von Antworten auf häufig gestellte Themen präsentieren. Anleitungen und häufig gestellte Fragen (FAQ) sind so gestaltet, dass sie leicht nachgeschlagen werden können und nicht unbedingt in einer linearen Abfolge präsentiert werden.

Um diese Typen zu erstellen, markieren Sie die Seiten, indem Sie dem Befehl \page das Argument type übergeben. Das Argument type ist das zweite Argument, während der Dateiname das erste ist.

/*!
    \page altruism-faq.html
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

Der Abschnitt Befehle zum Schreiben von Themen enthält eine Liste der verfügbaren Argumente für den Befehl \page.

Code-Beispiele

Beispiele sind ein effektives Mittel, um die praktische Anwendung einer bestimmten Technologie oder eines Konzepts zu demonstrieren. Wenn es um Middleware geht, geschieht dies normalerweise in Form einer Anwendung mit einfachem Code und klaren Erklärungen, was der Code tut. Jedes Modul, API, Projekt, Muster usw. sollte mindestens ein gutes Beispiel haben.

Ein Beispiel kann von einem Tutorial begleitet werden. Das Tutorial beschreibt den Code, während das Codebeispiel den Inhalt des Codes darstellt, den die Benutzer studieren können. Codebeispiele können begleitenden Text haben, der nicht im Tutorial enthalten ist.

QDoc erstellt eine Seite, die den Beispielcode mit einer Beschreibung enthält, indem es den Befehl \example verwendet.

/*!
    \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 Variable exampledirs angegebene Verzeichnis, um die Qt-Projektdatei (.pro) zu finden und die Beispieldateien zu erzeugen. Die generierte HTML-Datei trägt den Namen declarative-ui-components-tabwidget.html. QDoc wird auch den gesamten Beispielcode auflisten.