Dokumentation verfassen

QDoc-Kommentare

Die Dokumentation ist in QDoc-Kommentaren enthalten, die durch /*! und */ begrenzt werden. 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 weggelassen.

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

QDoc-Befehle

QDoc verwendet Befehle, um Informationen über die Dokumentation abzurufen. Die Befehle „ Topic “ bestimmen den Typ des Dokumentationselements, die Befehle „ context “ liefern Hinweise und Informationen zu einem Thema, und die Befehle „ markup “ liefern Informationen darüber, wie QDoc einen Dokumentationsabschnitt formatieren soll.

QDoc-Themen

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

QDoc fasst ähnliche Themen zusammen und erstellt für jedes Thema eine eigene Seite. Beispielsweise werden alle Aufzählungen, Eigenschaften, Funktionen und die Klassenbeschreibung einer bestimmten C++-Klasse auf einer Seite zusammengefasst. Eine allgemeine Seite wird mit dem \page Befehl festgelegt, wobei der Dateiname als Argument dient.

Beispiele für Themenbefehle:

• \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 - zum Erstellen einer Seite.

Mehrere Themen

Ein QDoc-Kommentar kann – mit einigen Einschränkungen – mehrere Themenbefehle derselben Kategorie enthalten. Auf diese Weise ist es möglich, einen einzigen Kommentar zu verfassen, der alle Überladungen einer Funktion (mithilfe mehrerer \fn Befehle) oder alle Eigenschaften in einer QML-Eigenschaftsgruppe (mit \qmlproperty Befehle) auf einmal zu dokumentieren.

Wenn ein QDoc-Kommentar mehrere Thema-Befehle enthält, ist es möglich, zusätzliche Kontextbefehle für einzelne Themen in nachfolgenden Kommentaren anzugeben:

/*!
    \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 ` weiterhin beschreibbar bleibt.

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

Themenkontexte

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

QDoc erstellt für diese Kontexte zusätzliche Links oder Seiten. Beispielsweise wird mithilfe des \group Befehl erstellt, und die Mitglieder erhalten den \ingroup Befehl. Der Gruppenname wird als Argument übergeben.

Auf der Seite „Kontextbefehle“ finden Sie eine Auflistung aller verfügbaren Kontextbefehle.

Dokumentationsmarkup

QDoc kann Text ähnlich wie andere Markup - oder Dokumentationswerkzeuge formatieren. QDoc kann einen Textabschnitt fett formatieren, wenn der Text mit dem \b Befehl markiert ist.

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

Auf der Seite „Markup-Befehle“ finden Sie eine vollständige Liste der verfügbaren Markup-Befehle.

Aufbau der Dokumentation

Damit QDoc eine Seite erstellen kann, müssen im Wesentlichen 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.
• Weisen Sie dem Thema einen Kontext zu – QDoc kann bestimmte Themen mit anderen Seiten verknüpfen, beispielsweise veraltete Elemente, wenn die Dokumentation mit \deprecated.
• Markieren Sie Abschnitte des Dokuments mit Markup-Befehlen – QDoc kann Layouts erstellen und die Dokumentation entsprechend 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 verfügt über 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 unterschiedlichen Dateien befinden, und QDoc sammelt sie je nach Thema und Kontext. Die aus den Ausschnitten resultierende Dokumentation wird in die Dokumentation der Klasse ` QVector3D ` generiert.

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

Ein Artikel wird mit dem Befehl \page Befehl erstellt. Das erste Argument ist die HTML-Datei, die QDoc erstellen wird. Das Thema wird durch Kontextbefehle ergänzt, nämlich die \title und \nextpage . Es gibt mehrere weitere QDoc-Befehle, wie beispielsweise den \list Befehl.

/*!
    \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 Themenarten.