Quickstart Doxygen

Einleitung

Dieser Artikel soll eine Hilfe sein, beim erstellen oder aktualisieren von Dokumentationen von Quellcode mit Doxygen.

Was ist Doxygen

Doxygen ist ein Tool womit Quellcode-Dokumentationen der Sprachen C,C++ oder HTML.

Anleitung

Schritt 1: Doxygen installieren

Als erstes sollten sie überprüfen, ob Doxygen schon installiert ist. Dafür können Sie zum Beispiel in der Windows-Suchleiste nach "Doxywizard" suchen. Sollten sie dieses Programm nicht haben, ist Doxygen nicht auf ihrem Gerät installiert.

Um Doxygen nun zu installieren, laden Sie sich hier die aktuelle Version herunter.

Schritt 2: Doxygen-Konfigurationsdatei erstellen

Um in Doxygen eine Konfigurationsdatei zu erstellen, müssen sie im Doxywizard auf den Reiter "Expert" umschalten.

Schritt 3: Konfigurationsdatei anpassen

Sollten Sie schon eine bestehende Konfigurationsdatei für ihr Doxygen Projekt haben, können Sie diese Anpassen in dem Sie sie über "File->Open" in Doxywizard laden und dann unter dem Reiter "Expert" anpassen.

Schritt 4: Kommentare in deinem Code hinzufügen

Kommentare in dem C-Code können einfach über das C-Projekt selber eingefügt werden. Es gibt allerdings Tags die Doxygen erkennt und diese anders verarbeitet.

C-Code Tags

Tag	Target	Bedeutung	Beispiel
brief	Modul, Datei, Funktion	Kurzbeschreibung	/** * @brief Berechnet die Summe von zwei Ganzzahlen */
details	Modul, Datei, Funktion	Ausführliche Beschreibung des Verhaltens	/** * @brief Berechnet die Summe von zwei Ganzzahlen * @details Diese Funktion nimmt zwei Integer als Eingabe und addiert diese zusammen und gibt ihre Summe zurück. */
param	Parameter	Beschreibung des Funktionsparameters	/** * @param a Der erste zu addierende Integer. * @param b Der zweite zu addierende Integer. */
return	Funktion	Beschreibung des Rückgabewerts	/** * @return Die Summe von a und b. */
retval	Funktion	Beschreibung möglicher Rückgabewerte	/** * @retval 0 Erfolgreich. * @retval -1 Fehlerhafte Eingabe. */
author	Modul, Datei, Funktion	Gibt den Autor des Codes an	/** * @author Daniel Mustermann /*
version	Modul, Datei, Funktion	Gibt die Versionsnummer des Codes an	/** * @version 1.0 */
see	Modul, Datei, Funktion	Gibt Verweise auf andere Funktionen oder Klassen an	/** * @see multiply() */
deprecated	Modul, Datei, Funktion	Markiert eine Funktion, Klasse oder Modul als veraltet	/** * @deprecated Diese Funktion wird in der nächsten Version entfernt */
warning	Modul, Datei, Funktion	Fügt eine Warnung für den Benutzer hinzu	/** * @warning Diese Funktion darf nicht als Interrupt verwendet werden! /*
struct	Struktur	Beschreibt eine Struktur	/** * @struct Point * @brief Stellt einen Punkt im 2D-Raum dar. */ struct Point { int x; int y; };
union	Union	Beschreibt eine Union-Datenstruktur	/** * @union Data * @brief Eine Union, die entweder einen Integer oder einen Float speichert. */ union Data { int i; float f; }; */
enum	Enum	Beschreibt eine Aufzählung	/** * @enum Color * @brief Enumeration für Farben. */ enum Color { RED, GREEN, BLUE };
var	Klasse, Struktur	Dokumentiert eine Variable oder ein Datenmitglied	/** * @var int x * @brief Die x-Koordinate des Punkts. */ int x;
class	Klasse	Dokumentiert eine Klasse	/** * @class Shape * @brief Abstrakte Klasse für Formen. */
namespace	Namespace	Dokumentiert einen Namespace	/** * @namespace mynamespace * @brief Namespace für spezielle Funktionen. */
file	Datei	Gibt den Dateinamen an	/** * @file example.c * @brief Diese Datei enthält Beispielcode. */
ingroup	Code-Element	Ordnet Code zu Gruppen zusammen	/** * @ingroup MathFunctions * @brief Diese Funktion gehört zur Gruppe der mathematischen Funktionen. */
def	Definition	Dokumentiert ein #define-Definition	/** * @def PI * @brief Wert der Zahl Pi. */ #define PI 3.14159
todo	Modul, Datei, Funktion	Dokumentiert eine zukünftige Veränderung	/** * @todo Fehlerbehandlung verbessern. */
bug	Modul, Datei, Funktion	Dokumentiert fehlerhaften Code	/** * @bug Diese Funktion gibt bei negativen Zahlen falsche Ergebnisse zurück. */
test	Test-Funktion	Dokumentiert einen Testfall	/** * @test Test mit den Werten 1 und 2 für die Summe. */
dot	Überall	Fügt DOT-Code für ein Graphviz-Diagramm hinzu	/** * @dot * digraph G { * A -> B; * B -> C; * } * @enddot */

Schritt 5: Dokumentation generieren

Am Schluss müssen Sie nur noch auf den Knopf "Fertig stellen" klicken und die Dokumentation sowie gegebenenfalls die Konfigurationsdatei wird erstellt