Doxygen

Aus C++_PHP_und_mehr
Wechseln zu: Navigation, Suche

Ein wundervolles Dokumentationswerkzeug von Dimitri van Heesch. Vielen Dank für diese Hilfe.

Installation

Kubuntu [1]

Doxygen ist in den Ubuntu-Paketquellen vorhanden, aber es wird das Paket doxygen-latex empfohlen, und das ist riesig. Wenn man LaTex nicht benötigt, sollte man darauf verzichten. Leider werden von der Muon-Paketverwaltung[2] auch empfohlen Pakete mit installiert. Ein Ausweg ist die Installation über die Konsole:

sudo apt-get install --no-install-recommends doxygen

Dagegen wird das Paket GraphViz mit dem Tool dot nicht mitinstalliert, welches Doxygen für die wundervollen Vererbungsgraphen nutzt. Sollte also zusätzlich installiert werden.
Verwendet wird dot erst, nachdem in der Konfigurationsdatei HAVE_DOT = YES gesetzt wird.

Gebrauch

Aufruf von

doxygen Konfigurationsdatei

in der Kommandozeile erzeugt und verknüpft Dokumentation zu allen Dateien mit der in der Konfigurationsdatei angegebenen Endung. Wenn in der Konfigurationsdatei 'RECURSIVE = YES' gesetzt ist, werden auch die Unterordner durchsucht. Wenn Konfigurationsdatei weggelassen wird, wird eine Datei namens 'Doxyfile' verwendet.

Einstellungen

doxygen -g

erzeugt eine projekteigene Konfigurationsdatei namens Doxyfile, in der eine Menge "tags" stehen, mit denen Doxygen eingestellt werden kann. zB.

  • PROJECT_NAME = "Projektname": Die Überschrift aller Seiten.
  • JAVADOC_AUTOBRIEF = YES: Der 1. Satz (bis zum 1. Punkt, wenn ein . Teil der Kurzbeschreibung sein soll, muss man ihn mit nachfolgendem \ und Leerzeichen kennzeichnen) wird als Kurzbeschreibung verwendet und taucht ganz oben und in der Auflistung auf[3].
  • EXTRACT_ALL = YES: Auch nicht kommentierte Klassen werden in die Dokumentation aufgenommen. Das ist hilfreich, wenn auch Kommentar fehlt, so wird doch die Klassenhierarchie dargestellt.
  • EXTRACT_STATIC = YES: Auch statische Member werden dokumentiert.
  • RECURSIVE = YES: Dateien werden auch in Unterordnern gesucht.
  • HTML_DYNAMIC_SECTIONS = Yes: Graphen werden beim Öffnen einer Seite versteckt und könne per Mausklick geöffnet und wieder versteckt werden.
  • HAVE_DOT = YES: Erzeugung von Graphen mittels dot (mehr und bessere Graphen).
  • HIDE_UNDOC_RELATIONS = NO: Nur dann werden auch die Klassen aus Bibliotheken in die Graphen mit aufgenommen. Sehr wichtig für Qt, wo fast alles von Klassen aus den Qt-Bibliotheken abgeleitet wird.

Navigationsleiste ändern

doxygen -l

erzeugt eine projekteigene Layoutdatei namens DoxygenLayout.xml. Diese Datei wird beim Aufruf geladen[4]. Modifikationen dieser Datei ändern das Erscheinungsbild der Dokumentation.
<tab>-Elemente im <navindex>-Element in dieser Datei sind die Abschnitte der Navigationsleiste. Es können eigene Elemente mit Attribut 'user' hinzugefügt werden:

<tab type="user" url="Buchhaltung.zip" title="Download"/>

Kommentarformate

Eine SEHR beschränkte Auswahl der Möglichkeiten entsprechend MEINER Präferenz! Andere mögen anderes vorziehen.

  • Javadoc Kommentare (über dem Objekt): /** Kommentar */
   /** Beschreibung zur Nummer */
   int number;
  • Javadoc Kommentare hinter dem Objekt: ///< Kommentar
   int number; ///< Kurzbeschreibung zur Nummer

Kommentare können im Prinzip an jeder beliebigen Stelle stehen, dann muss mit einem Special Command die Zuordnung benannt werden.
Special Command \file ist zB. die einzige Möglichkeit, eine Datei zu kommentieren.

/** \file datei.h
 *Kommentar....
 */

In die Projektseite index.html[5] wird mit \mainpage Kommentar eingefügt.

Spezielle Kommandos

beginnen mit einem \ oder @. Es gibt eine Unmenge von Special Commands, die das Aussehen der Dokumentation beeinflussen. Einige Beispiele:

  • \param : Für die Parameter einer Funktion / Methode.
  • \return : Für den Rückgabewert einer Funktion / Methode.
/** Kurzbeschreibung. Ausführliche Beschreibung.
 \param c a character.
 \param n an integer.
 \exception std::out_of_range parameter is out of range.
 \return a character pointer. */
 char* Funktion(char c, int n);

Spezielle Kommandos können Parameter haben, wobei unterschieden wird zwischen:

  • Einzelwörter: im Doxygen Manual mit <spitzen> Klammern gekennzeichnet.
  • Texte bis zum Ende der Zeile: Im Manual mit (runden) Klammern gekennzeichnet.
  • Paragraphen: Ein Paragraph reicht bis zur nächsten Leerzeile oder dem nächsten Kommando. Im Manual mit {geschweiften} Klammern gekennzeichnet.

[Eckige] Klammern kennzeichnen optionale Parameter.

Code-Teile übernehmen

Oft ist es sinnvoll, in die Dokumentation Snippets aus dem eigentlichem Programm-Code zu übernehmen, als Beispiel oder um Hilfetexte nicht wiederholen zu müssen. Eine Möglichkeit ist

in Verbindung mit

  • \skip pattern: Setzt in file den internen Zeiger auf die nächste Zeile mit pattern.
  • \skipline pattern: Setzt in file den internen Zeiger auf die nächste Zeile mit pattern und fügt diese ein.
  • \until pattern: Fügt alle Zeilen aus file ab dem internen Zeiger bis zur Zeile mit pattern inklusive ein.
  • \line pattern: Fügt die 1. nicht leere Zeile mit pattern hinter dem internen Zeiger ein.
/** Klasse AccountAddChangeDialog: Kurzbeschreibung. Ausführliche Beschreibung.
 * Quellcode zur Klasse in Datei accountaddchangedialog.cpp öffnen:
 * \dontinclude accountaddchangedialog.cpp
 * Einbinden des Hilfetextes von 'cbAccounts':
 * \skip ui->cbAccounts->setWhatsThis(
 * \until )
 * Einbinden des Hilfetextes von 'checkDelete':
 * \skip ui->checkDelete->setWhatsThis(
 * \until )
 */

fügt die Befehle zum Setzen der WhatsThis inklusive der Texte in die Doku ein.
Damit das alles funktioniert, muss in der Konfigurationsdatei (zB. Doxyfile) der Beispielpfad gesetzt werden, geht auch mit '.' für den aktuellen Ordner:

  • EXAMPLE_PATH = /Pfad/zum/Ordner oder
  • EXAMPLE_PATH = .
  • EXAMPLE_RECURSIVE = YES

Test

Es ist sinnvoll, jede Methode zu testen, erscheint sie auch noch so simpel. Um eine Testbeschreibung einzufügen, wichtig für die Reproduzierbarkeit, gibt es das Kommando \test. Damit wird der nachfolgende Paragraph gekennzeichnet und eine Kopie in einer Test-Liste angelegt. Test-Liste ist über den Abschnitt Zusätzliche Informationen erreichbar.

Bilder

Mit \image können Bilder in die Dokumentation aufgenommen werden. Es muss das Ausgabeformat, zB. html und der Dateinamen benannt werden, eine Unterschrift und Größe ist optional:

\image html bild.png

Es können die Bildformate verwendet werden, die der Browser unterstützt.
Damit das alles funktioniert, muss in der Konfigurationsdatei (zB. Doxyfile) der Bilderpfad gesetzt werden:

  • IMAGE_PATH = /Pfad/zum/Ordner

Kommentarformatierung

Es sind eine große Anzahl von HTML-Tags zulässig, zB. <table> oder <H1>.
Es können Listen mit HTML-Tags, den Special Commands \li oder \arg oder mit -(Aufzählungszeichen) und -#(nummeriert) erzeugt werden[6]. Bei -, -# gibt der Spalteneinzug die Aufzählungsebene an.
Wenn man für Doxygen reservierte Zeichen verwenden will, muss man sie mit \ maskieren.

Automatische Link-Erzeugung

Falls innerhalb einer Beschreibung Namen von Klassen und ihrer Member, Funktionen, Typdefinition und Dateien verwendet werden, die in der Dokumentation vorkommen, werden automatisch Links auf deren Dokumentationsseiten erzeugt. Das funktioniert unter Linux[7] problemlos, unter Windows[8] weigert sich Doxygen aber, Header-Dateien zu verlinken. Workaround ist das spezielle Kommandopaar \link - \endlink um den Dateinamen. Dann wird auf die 1. Seite[9] verlinkt, die den Dateinamen enthält, bzw. die allererste Seite, wenn die Datei nicht dokumentiert ist.

Doxygen und Qt

Doxygen kann aus der erzeugten html-Dokumentation eine Qt-kompatible Dokumentation generieren, eine Qt Compressed Help (SQL-Datenbankdatei mit der Erweiterung .qch) im Unterordner qch im Projektordner, parallel zum Ordner html. Diese kann im Qt-Creator über Extras->Einstellungen->Hilfe->Dokumentation hinzugefügt werden. Dann wird mit F1 die zugehörige Seite einer Klasse oder Methode in der Doxygen-Dokumentation aufgerufen, genau wie bei Qt-Klassen. Dazu sind in der Konfigurationsdatei Doxyfile folgende Tags zu setzen:

  • GENERATE_QHP = YES: Es wird ein Index der HTML-Dateien als Qt Help Project (eine xml-Datei mit Erweiterung .qhp) erzeugt. Aus dieser wird mit qthelpgenerator die Qt Compressed Help erzeugt.
  • QHP_NAMESPACE = Buchhaltung.doxygen.Project: Eindeutiger Name der Doku.
  • QHP_VIRTUAL_FOLDER = doc: Virtuelles Wurzelverzeichnis aller in der Qt Compressed Help angesprochenen Dateien. Wenn unterschiedliche Dokumentationen das gleiche 'Virtual Folder' haben, können sie über relative Links mit einander verknüpft werden.
  • QHG_LOCATION = /Pfad/zum/Qt/Version/gcc_64/bin/qhelpgenerator: Der qthelpgenerator wird nach erstellen der HTMLs automatisch aufgerufen.

Fußnoten

  1. getestet für 12.04
  2. Wahrscheinlich der Ubuntu-Paketverwaltung.
  3. In Kommentaren im JavaDoc - Stil /** <Kommentar> */
  4. Mit Tag 'LAYOUT_FILE' im Doxyfile kann die Layoutdatei ausgwählt werden, Vorgabe DoxygenLayout.xml.
  5. Die Seite, die zuerst aufgerufen wird.
  6. Die in der doxygen-Dokumentation unter Markdown-Support beschriebenen Möglichkeiten +, *, 1. funktionieren bei mir (doxygen 1.7.6.1, Kubuntu 12:04) nicht
  7. Kubuntu 14.04, Doxygen 1.8.6
  8. Win7, Doxygen 1.8.11
  9. Ich habe noch keinen Weg gefunden, Dateien gleichen Namens, aber aus unterschiedlichen Ordnern, zu unterscheiden.