doxygen
Installation und Anwendung
Für doxygen gibt es eine vorcompilierte Variante, die sogenannten Binaries. Nach dem man sie heruntergelanden und entpackt hat kann man sie als root mit dem Befehl
./configure
make install
installieren. Das Programm wird standardmäßig nach /usr/local/bin/doxygen installiert.
Um ein Projekt zu dokumentieren, ruft man zunächst
doxygen -g
z.B. im Hauptverzeichnis des Projekts auf. doxygen produziert nun eine Standardkonfigurationsdatei names Doxyfile, die die Arbeitsweise von Doxygen steuert. Mit dieser Datei kann man doxygen nun erneut aufrufen.
doxygen Doxyfile
Doxygen durchforstet nun das Projektverzeichnis und erzeugt im Ordner ./html die Dokumentation. Falls man nicht möchte das Latex Documentation erstellt wird, so editiert man die Datei Doxyfile und sucht den Schlüssel GENERATE_LATEX und setzt den Wert des Schlüssels auf NO.
Wenn man Doxygen nur mit dem Befehl doxygen Doxyfile aufruft, so sucht doxygen nach zu dokumentierenden Quellen in den Werten des Schlüssels INPUT in der Konfigurationsdatei (Doxyfile). Standardmäßig ist dort kein Wert eingetragen und doxygen untersucht somit nur das Verzeichnis in dem es aufgerufen wurde. Man muss also die Konfigurationsdatei bearbeiten und alle gewünschten Ordner eintragen. Den Ausgabeordner kann man mit dem Schlüssel OUTPUT_DIRECTORY anpassen (z.B. auf doc)
C Programme dokumentieren mit doxygen
doxygen ist in der Standardeinstellung auf C++ optimiert. Um C Programme zu dokummentieren sollte man folgende Anpassungen in der Konfigurationsdatei (Doxyfile) vornehmen:
EXTRACT_ALL YES
OPTIMIZE_OUTPUT_FOR_C YES
JAVADOC_AUTOBRIEF YES
JAVADOC_AUTOBRIEF hat nichts direkt mit C zu tun sondern erlaubt in JavaDoc Kommentaren das erstellen des brief Kommentars indem man eine Zeile mit einem Punkt abschliesst.
Um eine Datei zu dokumentieren ist es nicht nötig irgendwas zu tun, da doxygen das automatisch tut. Möchte man allerdings, das ein brief Kommentar neben dem Dateinamen in der Dokumentation auftaucht, dann muss man folgendes in der Kopfkommentar der Datei schreiben.
/**
* \file main.c
*
* \brief This is the brief comment.
*
* This is the detailed
* comment which is detailed.
*/
Hierbei gibt es zwei Sachen zu beachten.
- hinter \file muss der tatsächliche Name der Datei stehen sonst verweigert doxygen seinen Dienst.
- Die Zeile \brief muss mit einem Punkt abgeschlossen werden sonst verweigert doxygen seinen Dients.
Um eine Funktion zu kommentieren schreibt man folgendes vor die Funktion:
/**
* This is the main function.
*
* This is the detailed comment.
*/
Wenn man JAVADOC_AUTOBRIEF auf YES gestellt hat, dann wird mit der ersten Zeile der Kurzkommentar und mit dem Rest der ausführliche Kommentar erzeugt. Man beachte, das die brief Kommentarzeile unbedingt mit einem Punkt abgeschlossen sein muss, da ansonsten doxygen seinen Dients verweigert.
Um einen Rückgabetype und den Sinn des Rückgabedatums einer Funktion zu beschreiben verwendet man den Befehl.
\return bla bla bla.
oder
@param
falls JAVADOC_AUTOBRIEF in der Doxyfile auf YES gestetzt ist.
doxygen aus Eclipse heraus aufrufen
Um doxygen komfortabel aufrufen zu können, wählen Sie den Menüpunkt Run > External Tools > External Tools... aus. Im erscheinenden Dialog markieren Sie den Eintrag Program in der Auswahlliste und klicken Sie dann auf den Button "New Launch Configuration". Tragen Sie in das Feld Location den Pfad zu ihrem Doxygen ein z.B. /usr/local/bin/doxygen und tragen Sie in das Feld Working directory den Pfad für das entsprechende Projekt ein. Ändern Sie den Namen auf z.B. doxygen. Nun können Sie doxygen (falls es eine Doxyfile gibt) durch eine Auswahl des Menüpunktes Run > External Tools > doxygen starten.