Einführung in QDoc

QDoc ist ein Werkzeug, das von Qt-Entwicklern zur Erstellung von Dokumentation für Softwareprojekte verwendet wird. Es extrahiert QDoc-Kommentare aus den Quelldateien des Projekts und formatiert diese Kommentare anschließend als HTML-Seiten oder DocBook-XML-Dokumente. QDoc findet QDoc-Kommentare in „ .cpp “-Dateien und in „ .qdoc “-Dateien. In „ .h “-Dateien sucht QDoc nicht nach QDoc-Kommentaren. Ein QDoc-Kommentar beginnt immer mit einem Ausrufezeichen (!). Beispiel:

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

Aus dem obigen QDoc-Kommentar generiert QDoc die HTML-Seite „ QObject class reference “.

Dieses Handbuch erklärt, wie Sie die QDoc-Befehle in QDoc-Kommentaren verwenden, um eine gute Dokumentation in Ihre Quelldateien einzubetten. Außerdem wird erläutert, wie Sie eine QDoc-Konfigurationsdatei erstellen, die Sie über die Befehlszeile an QDoc übergeben.

QDoc ausführen

Der Name des QDoc-Programms lautet „ qdoc “. Um QDoc über die Befehlszeile auszuführen, geben Sie den Namen einer Konfigurationsdatei an:

$ ../../bin/qdoc ./config.qdocconf

QDoc erkennt die Endung „ .qdocconf “ als QDoc-Konfigurationsdatei. In der Konfigurationsdatei legen Sie fest, wo QDoc die Quelldateien, Header-Dateien und „ .qdoc “-Dateien des Projekts finden soll. Außerdem legen Sie dort fest, welche Art von Ausgabe generiert werden soll (HTML, DocBook XML …) und wo die generierte Dokumentation abgelegt werden soll. Die Konfigurationsdatei enthält außerdem weitere Informationen für QDoc.

Anweisungen zum Einrichten einer QDoc-Konfigurationsdatei finden Sie unter „Die QDoc-Konfigurationsdatei “.

So funktioniert QDoc

QDoc beginnt damit, die von Ihnen in der Befehlszeile angegebene Konfigurationsdatei einzulesen. Es speichert alle Variablen aus der Konfigurationsdatei für die spätere Verwendung. Eine der ersten Variablen, die es verwendet, ist „ outputformats “. Diese Variable teilt QDoc mit, welche Ausgabegeneratoren es ausführen soll. Der Standardwert ist „HTML“; wenn Sie also in Ihrer Konfigurationsdatei keinen Wert für „ outputformats “ festlegen, generiert QDoc eine HTML-Ausgabe. Das ist in der Regel ohnehin das, was Sie wünschen, aber Sie können auch „DocBook“ angeben, um stattdessen eine DocBook-Ausgabe zu erhalten.

Als Nächstes verwendet QDoc die Werte der Variablen „headerdirs“ und/oder „headers“, um alle Header-Dateien Ihres Projekts zu finden und zu analysieren. QDoc durchsucht Header-Dateien nicht nach QDoc-Kommentaren. Es analysiert die Header-Dateien, um einen Master-Baum aller Elemente zu erstellen, die dokumentiert werden sollen – mit anderen Worten: der Elemente, für die QDoc QDoc-Kommentare finden soll.

Nachdem alle Header-Dateien analysiert und der Hauptbaum der zu dokumentierenden Elemente erstellt wurde, verwendet QDoc den Wert der Variablen „sourcedirs“ und/oder den Wert der Variablen „sources“, um alle „ .cpp “- und „ .qdoc “-Dateien Ihres Projekts zu finden und zu analysieren. Dies sind die Dateien, die QDoc nach QDoc-Kommentaren durchsucht. Beachten Sie, dass ein QDoc-Kommentar mit einem Ausrufezeichen beginnt: /*!.

Für jeden gefundenen QDoc-Kommentar durchsucht es den Masterbaum nach dem Element, zu dem die Dokumentation gehört. Anschließend interpretiert es die QDoc-Befehle im Kommentar und speichert die interpretierten Befehle sowie den Kommentartext im Baumknoten des jeweiligen Elements.

Abschließend durchläuft QDoc den Master-Baum. Für jeden Knoten, der über gespeicherte Dokumentation verfügt, ruft QDoc den durch die Variable „ outputformats “ angegebenen Ausgabegenerator auf, um die Dokumentation zu formatieren und in das Verzeichnis zu schreiben, das in der Konfigurationsdatei in der Variable „outputdir“ angegeben ist.

Befehlstypen

QDoc interpretiert drei Arten von Befehlen:

• Themenbefehle
• Kontextbefehle
• Markup-Befehle

Themenbefehle identifizieren das Element, das Sie dokumentieren, zum Beispiel eine C++-Klasse, eine Funktion, einen Typ oder eine zusätzliche Textseite, die keinem zugrunde liegenden C++-Element zugeordnet ist.

Kontextbefehle teilen QDoc mit, in welcher Beziehung das dokumentierte Element zu anderen dokumentierten Elementen steht, zum Beispiel durch Verweise auf die nächste und vorherige Seite, die Einbindung in Seitengruppen oder Bibliotheksmodule. Kontextbefehle können außerdem Informationen über das dokumentierte Element liefern, die QDoc nicht aus den Quelldateien entnehmen kann, zum Beispiel, ob das Element threadsicher ist, ob es sich um eine überladene oder neu implementierte Funktion handelt oder ob es veraltet ist.

Markup-Befehle teilen QDoc mit, wie Text- und Bildelemente im Dokument dargestellt werden sollen, oder geben Auskunft über die Gliederungsstruktur des Dokuments.