Einführung in QDoc

QDoc ist ein Werkzeug, das von Qt-Entwicklern verwendet wird, um Dokumentation für Softwareprojekte zu erstellen. Es extrahiert QDoc-Kommentare aus Projekt-Quelldateien und formatiert diese Kommentare dann als HTML-Seiten oder DocBook XML-Dokumente. QDoc findet QDoc-Kommentare in .cpp Dateien und in .qdoc Dateien. QDoc sucht nicht nach QDoc-Kommentaren in .h Dateien. Ein QDoc-Kommentar beginnt immer mit einem Ausrufezeichen (!)). Ein 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 erzeugt QDoc die HTML-Seite QObject class reference.

Dieses Handbuch erklärt, wie Sie die QDoc-Befehle in QDoc-Kommentaren verwenden, um gute Dokumentation in Ihre Quelldateien einzubetten. Es wird auch erklärt, wie Sie eine QDoc-Konfigurationsdatei erstellen, die Sie QDoc auf der Kommandozeile übergeben.

QDoc starten

Der Name des QDoc-Programms ist qdoc. Um QDoc von der Kommandozeile aus zu starten, geben Sie ihm den Namen einer Konfigurationsdatei:

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

QDoc erkennt das Suffix .qdocconf als eine QDoc-Konfigurationsdatei. In der Konfigurationsdatei teilen Sie QDoc mit, wo die Projekt-Quelldateien, Header-Dateien und .qdoc Dateien zu finden sind. Hier teilen Sie QDoc auch mit, welche Art von Ausgabe erzeugt werden soll (HTML, DocBook XML...) und wo die erzeugte Dokumentation abgelegt werden soll. Die Konfigurationsdatei enthält auch andere Informationen für QDoc.

Siehe Die QDoc-Konfigurationsdatei für eine Anleitung, wie man eine QDoc-Konfigurationsdatei einrichtet.

Wie QDoc funktioniert

QDoc beginnt mit dem Lesen der Konfigurationsdatei, die Sie in der Kommandozeile angegeben haben. Es speichert alle Variablen aus der Konfigurationsdatei zur späteren Verwendung. Eine der ersten Variablen, die verwendet wird, ist outputformats. Diese Variable teilt QDoc mit, welche Ausgabegeneratoren es ausführen soll. Der Standardwert ist HTML, d.h. wenn Sie outputformats in Ihrer Konfigurationsdatei nicht setzen, wird QDoc HTML-Ausgaben erzeugen. Das ist normalerweise das, was Sie sowieso wollen, 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 der Variablen headers, um alle Header-Dateien für Ihr Projekt zu finden und zu analysieren. QDoc durchsucht die Header-Dateien nicht nach QDoc-Kommentaren. Es analysiert die Header-Dateien, um einen Master-Tree mit allen Elementen zu erstellen, die dokumentiert werden sollen, mit anderen Worten, die Elemente, für die QDoc QDoc-Kommentare finden soll.

Nachdem alle Header-Dateien analysiert und der Master-Tree der zu dokumentierenden Elemente erstellt wurde, verwendet QDoc den Wert der sourcedirs-Variable und/oder den Wert der sources-Variable, um alle .cpp und .qdoc Dateien für Ihr Projekt zu finden und zu analysieren. Dies sind die Dateien, die QDoc nach QDoc-Kommentaren durchsucht. Denken Sie daran, dass ein QDoc-Kommentar mit einem Ausrufezeichen beginnt: /*!.

Für jeden gefundenen QDoc-Kommentar sucht QDoc im Masterbaum nach dem Element, zu dem die Dokumentation gehört. Dann interpretiert es die QDoc-Befehle in dem Kommentar und speichert die interpretierten Befehle und den Kommentartext in dem Baumknoten für das Element.

Schließlich durchläuft QDoc den Master Tree. Für jeden Knoten, wenn dieser eine Dokumentation gespeichert hat, ruft QDoc den durch die Variable outputformats spezifizierten Ausgabegenerator auf, um die Dokumentation zu formatieren und in das in der Konfigurationsdatei in der Variable outputdir angegebene Verzeichnis zu schreiben.

Befehlsarten

QDoc interpretiert drei Arten von Kommandos:

• Themen-Befehle
• Kontext-Befehle
• Markup-Befehle

Topic-Befehle identifizieren das Element, das Sie dokumentieren, z.B. eine C++-Klasse, eine Funktion, einen Typ oder eine zusätzliche Textseite, die nicht auf ein zugrunde liegendes C++-Element abgebildet wird.

Kontextbefehle teilen QDoc mit, wie sich das dokumentierte Element zu anderen dokumentierten Elementen verhält, z.B. Links zur nächsten und vorherigen Seite, Einbeziehung in Seitengruppen oder Bibliotheksmodule. Kontextbefehle können auch Informationen über das dokumentierte Element liefern, die QDoc nicht aus den Quelldateien entnehmen kann, z.B. ob das Element thread-safe ist, ob es sich um eine überladene oder reimplementierte Funktion handelt oder ob es veraltet ist.

Markup-Befehle teilen QDoc mit, wie Text- und Bildelemente im Dokument gerendert werden sollen, oder wie die Gliederungsstruktur des Dokuments aussieht.