Dokumentation schreiben

QDoc-Kommentare

Die Dokumentation ist in QDoc-Kommentaren enthalten, die durch die Kommentare /*! und */ abgegrenzt sind. Beachten Sie, dass dies gültige Kommentare in C++ und QML sind.

Innerhalb eines QDoc-Kommentars wird //! als einzeiliger Dokumentationskommentar verwendet; der Kommentar selbst und alles, was danach folgt, bis zu einem Zeilenumbruch, wird in der generierten Ausgabe ausgelassen.

QDoc analysiert C++- und QML-Dateien, um nach QDoc-Kommentaren zu suchen. Um einen bestimmten Dateityp explizit auszulassen, lassen Sie ihn in der Konfigurationsdatei aus.

QDoc-Befehle

QDoc verwendet Befehle, um Informationen über die Dokumentation abzurufen. Topic Befehle bestimmen den Typ des Dokumentationselements, die context Befehle liefern Hinweise und Informationen über ein Thema und markup Befehle liefern Informationen darüber, wie QDoc ein Stück Dokumentation formatieren soll.

QDoc Themen

Jeder QDoc-Kommentar muss einen Topic-Typ haben. Ein Thema unterscheidet ihn von anderen Themen. Um einen Thementyp anzugeben, verwenden Sie einen der verschiedenen Themenbefehle.

QDoc sammelt ähnliche Themen und erstellt eine Seite für jedes Thema. Zum Beispiel werden alle Aufzählungen, Eigenschaften, Funktionen und Klassenbeschreibungen einer bestimmten C++ Klasse in einer Seite untergebracht. Eine generische Seite wird mit dem Befehl \page angegeben, wobei der Dateiname das Argument ist.

Beispiel für Topic-Befehle:

• \enum - für die Dokumentation von Aufzählungen
• \class - für die Dokumentation von C++-Klassen
• \qmltype - für die Dokumentation von QML-Typen
• \page - für die Erstellung einer Seite.

Ein QDoc-Kommentar kann mit einigen Einschränkungen mehrere Themenbefehle in derselben Kategorie enthalten. Auf diese Weise ist es möglich, einen einzigen Kommentar zu schreiben, der alle Überladungen einer Funktion (unter Verwendung mehrerer \fn-Befehle ) oder alle Eigenschaften in einer QML-Eigenschaftsgruppe (unter Verwendung von \qmlproperty-Befehlen ) in einem Durchgang dokumentiert.

Wenn ein QDoc-Kommentar mehrere Themenbefehle enthält, ist es möglich, zusätzliche Kontextbefehle für einzelne Themen in Folgekommentaren bereitzustellen:

/*!
    \qmlproperty string Type::element.name
    \qmlproperty int Type::element.id

    \brief Holds the element name and id.
*/

/*!
    \qmlproperty int Type::element.id
    \readonly
*/

Hier markiert der Folgekommentar die Eigenschaft element.id als schreibgeschützt, während element.name beschreibbar bleibt.

Der Befehl \page dient zum Erstellen von Artikeln, die nicht Teil der Quelldokumentation sind. Der Befehl kann ebenfalls zwei Argumente akzeptieren: den Dateinamen des Artikels und den Dokumentationstyp. Die möglichen Typen sind:

• howto
• overview
• tutorial
• faq
• attribution - verwendet für die Dokumentation von Lizenzzuweisungen
• article - Standard, wenn es keinen Typ gibt

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

    \brief All the questions about altruism, answered.

    ...
*/

Auf der Seite Themenbefehle finden Sie Informationen zu allen verfügbaren Themenbefehlen.

Themenkontexte

Kontextbefehle geben QDoc einen Hinweis auf den Kontext des Themas. Wenn zum Beispiel eine C++-Funktion veraltet ist, sollte sie mit dem Befehl \deprecated als solche gekennzeichnet werden. Ebenso geben die Seitennavigation und der Seitentitel QDoc zusätzliche Seiteninformationen.

QDoc erstellt zusätzliche Links oder Seiten für diese Kontexte. Eine Gruppe wird z.B. mit dem Befehl \group erstellt und die Mitglieder haben den Befehl \ingroup. Der Gruppenname wird als Argument übergeben.

Die Seite Context Commands enthält eine Auflistung aller verfügbaren Kontextbefehle.

Dokumentation Markup

QDoc kann Text auszeichnen, ähnlich wie andere Auszeichnungs- oder Dokumentationswerkzeuge. QDoc kann einen Textabschnitt fett markieren, wenn der Text mit dem Befehl \b markiert wurde.

\b{This} text will be in \b{bold}.

Auf der Seite Markup Commands finden Sie eine vollständige Liste der verfügbaren Markup Commands.

Anatomie der Dokumentation

Damit QDoc eine Seite erstellen kann, müssen einige wesentliche Bestandteile vorhanden sein.

• Weisen Sie einem QDoc-Kommentar ein Thema zu - Ein Kommentar kann eine Seite, eine Eigenschaftsdokumentation, eine Klassendokumentation oder einer der verfügbaren Themenbefehle sein.
• Geben Sie dem Thema einen Kontext - QDoc kann bestimmte Themen mit anderen Seiten verknüpfen, z.B. veraltete Funktionen, wenn die Dokumentation mit \deprecated markiert ist.
• Markieren Sie Abschnitte des Dokuments mit Markup-Befehlen - QDoc kann Layouts erstellen und die Dokumentation für die Dokumentation formatieren.

In Qt wurde die Klasse QVector3D mit dem folgenden QDoc-Kommentar dokumentiert:

/*!
    \class QVector3D
    \brief The QVector3D class represents a vector or vertex in 3D space.
    \since 4.6
    \ingroup painting-3D

    Vectors are one of the main building blocks of 3D representation and
    drawing.  They consist of three coordinates, traditionally called
    x, y, and z.

    The QVector3D class can also be used to represent vertices in 3D space.
    We therefore do not need to provide a separate vertex class.

    \note By design values in the QVector3D instance are stored as \c float.
    This means that on platforms where the \c qreal arguments to QVector3D
    functions are represented by \c double values, it is possible to
    lose precision.

    \sa QVector2D, QVector4D, QQuaternion
*/

Sie hat einen Konstruktor, QVector3D::QVector3D(), der mit dem folgenden QDoc-Kommentar dokumentiert wurde:

/*!
    \fn QVector3D::QVector3D(const QPoint& point)

    Constructs a vector with x and y coordinates from a 2D \a point, and a
    z coordinate of 0.
*/

Die verschiedenen Kommentare können sich in verschiedenen Dateien befinden und QDoc wird sie je nach Thema und Kontext sammeln. Die aus den Schnipseln resultierende Dokumentation wird in die Klassendokumentation QVector3D generiert.

Beachten Sie, dass die Dokumentation, die unmittelbar vor der Funktion oder Klasse im Quellcode steht, kein Thema haben muss. QDoc geht dann davon aus, dass die Dokumentation über dem Code die Dokumentation für diesen Code ist.

Ein Artikel wird mit dem Befehl \page erstellt. Das erste Argument ist die HTML-Datei, die QDoc erstellen soll. Das Thema wird mit Kontextbefehlen ergänzt, den Befehlen \title und \nextpage. Es gibt noch einige andere QDoc-Befehle wie den Befehl \list.

/*!
    \page generic-guide.html
    \title Generic QDoc Guide
    \nextpage Creating QDoc Configuration Files
    There are three essential materials for generating documentation with QDoc:

    \list
        \li \c QDoc binary (\c {qdoc})
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist
*/

Der Abschnitt über Themenbefehle gibt einen Überblick über verschiedene andere Thementypen.