Weitere Informationen

Doxygen ist ein Tool, welches automatisch aus Kommentaren von Header-Dateien eine Dokumentation für das Projekt erzeugen kann. Diese Dokumentation kann von neuen Mitgliedern des Teams (bzw. Leuten, die nicht am Code gearbeitet haben) benutzt werden, um den Code zu verstehen und Verbesserungen vorzunehmen. Wichtig ist dabei, dass die Kommentare aussagekräftig sind um den größten Effekt zu erzielen.

Doxygen verwendet eine bestimmte Syntax um normale Kommentare von Doxygen-Kommentaren zu unterscheiden. In C++ ist folgendes normal:

/* Dies ist eine absolut schwierige Funktion */
void absoluteSchwierigeFunktion(int par1, int par2);

Mithilfe von Doxygen kann man Funktionen, Methoden, Klassen, Namespaces, … dokumentieren. Dabei verwendet Doxygen verschiedene Syntaxen, wir verwenden hier folgende:

/// absolute schwierige Funktion
void absoluteSchwierigeFunktion(int par1, int par2);

Mithilfe von /// ist es möglich eine kurze Beschreibung ( brief ) der Funktion anzugeben. Es ist damit nicht möglich lange Texte zu schreiben und es ist nicht möglich Rückgabewerte oder Parameter zu beschreiben. Das geht folgendermaßen.

/**
 * \brief absolute schwierige Funktion
 * 
 * Dies ist eine verdammt schwierige Funktion, ich wäre vorsichtig, wenn ich die benützen müsste.
 * \param par1 der erste Parameter gibt eine Zahl an
 * \param par2 der zweite Parameter sollte zwischen 1 und 100 liegen und gibt die relative häufigkeit an.
 * \return nothing
 **/
void absoluteSchwierigeFunktion(int par1, int par2);

Hier werden ebenfalls die Parameter ( param ) und der Rückgabewert ( return ) beschrieben. Außerdem wird ein langer Erklärungstext angegeben. Beachte bitte die Freizeile zwischen brief und dem langen Text.

Selbiges funktioniert bei Klassen, enums, structs oder unions. Bei Membervariablen bietet sich an nur /// zu verwenden, da keine weiter Beschreibung von Nöten ist. Membervariablen (oder Werte von enums) lassen sich ebenfalls auch so dokumentieren:

/// ein Enum-Typ.
enum MyEnum
{
    ERSTERWERT,  ///< erster Wert
    ZWEITERWERT, ///< zweiter Wert
    DRITTERWERT, ///< dritter Wert
    LETZERWERT   ///< vierter und letzter Wert
};

Namespaces werden mit dem Parameter \namespace <nowiki> // dokumentiert. Für einen guten Stil sollte die Verwendung von // <nowiki> /// und brief nicht innerhalb eines Projektes gewechselt werden (für Methoden). Hier ist eine Beispielklasse, die mit Doxygen dokumentiert wurde:

/**
 * \brief eine Beispielklasse
 **/
class example
{
    public:
        /**
         * \brief Konstruktor, erstellt die Klasse mit member1=2, member2=3 und a=4
         **/
        example();
        /**
         * \brief Destruktor, löscht das Objekt und die Referenz auf das nächste
         **/ 
        ~example();
 
        /**
         * \brief gibt die Länge des Beispiels zurück
         * \return die Länge des Beispiels als ganze Zahl (int)
         **/ 
        int length();
        /**
         * \brief gibt die Klasse auf stdout aus
         **/ 
        void out();
        /**
         * \brief gibt den Request-ID zurück, errechnet Zeug.
         * \param par1 gibt Zeug an
         * \param par2 gibt ebenfalls Zeug an
         * \return Request-ID
         **/ 
        int req(int par1, int par2);
 
    private:
        /// member1, gibt Zeug an
        int member1;
        /// member2 gibt Zeug an
        int member2;
        /// a ist Member der Klasse und speichert sich die Länge des Beispiels
        float a;        
}

Mittels den Befehlen \author und \date kann man für die beschriebenen Funktionen / Klassen Authoren bzw. Erstellungs / Änderungsdaten angeben. Für die Nachvollziehbarkeit der Authorenschaft sollte das unbedingt benutzt werden.

Mithilfe von Doxygen kann man die Kommentare quasi automatisiert in eine Funktionsreferenz umwandeln lassen. Dazu ist es am einfachsten doxygen-wizard (auch doxywizard) zu benutzen. Dort kann man das Scan-Directory eingeben, einige Informationen über das Projekt, das Ziel-Directory und anschließend im dritten Tab auf „Run Doxygen“ und dann auf „Show HTML-Output“ klicken. Die Ausgabe als .tex oder RTF ist ebenfalls möglich.