Dokumentieren mit Eclipse und Doxygen

Transkript

1 Dokumentieren mit Eclipse und Doxygen Boris Budweg, Version 0.2 Abstract: Kurze Anleitung für die Benutzung von Doxygen und Eclox in Eclipse. Doxygen-Kommentare / Schlüsselwörter...2 Beispiel...2 Erstellen einer Konfigurationsdatei...3 Konfiguration der Dokumentation...4 Bauen und Anzeigen der Dokumentation...6 Weiterführendes...7 Eclipse-Vorlage...8 1

2 Doxygen-Kommentare / Schlüsselwörter Doxygen Kommentare sind gewöhnliche C-Kommentare, die einem bestimmten Muster folgen. Sie beginnen immer mit /** und enden mit */. Besondere Schlüsselwörter werden wie folgt verwendet (kleine Auswahl): Am Anfang einer datum Vor einer Funktion: Der erste Satz ist die Kurzbeschreibung und endet beim ersten parametername rückgabewert-beschreibung Alle weiteren Sätze im Doxygen-Kommentar werden der (langen) Beschreibung der Datei/Funktion zugeordnet. Beispiel /** main.c budweg 2009/11/23 * * dies ist ein einfaches beispiel für * die verwendung von funktionen. * */ #include"stdio.h" /** hier werden alle fragen * beantwortet. fragenr nummer einer frage antwort auf fragenr * * diese funktion ist besonders einfach */ int AntwortAufAlleFragen(int fragenr) { return 42; } /** dies ist die hauptfunktion. */ void main() { int a = AntwortAufAlleFragen(10); printf("%i\n", a); } 2

3 Erstellen einer Konfigurationsdatei Klicken Sie rechts auf ihr Projekt. New - Other: Auf der folgenden Seite wird ein Name für das Doxyfile vorgeschlagen der Name Ihres Projektes. Klicken Sie einfach Finish. 3

4 Konfiguration der Dokumentation Doxygen bietet unzählige Optionen. Die hier vorgeschlagenen sollen einen Überblick über einige nützliche bieten. Öffnen Sie das neu erstellte Doxyfile: Konfigurieren Sie das Doxyfile vorerst wie folgt: 4

5 Dies sind die Basiseinstellungen. Unter dem Reiter Advanced finden Sie noch weit mehr Optionen. Warn for undocumented Function Parameters sollten Sie einschalten, wenn Sie immer vollständig dokumentieren wollen: Der Caller Graph ist der umgedrehte Call graph, und manchmal ebenso nützlich: Wichtig: Wie jede andere Datei in Eclipse, muss auch diese Konfigurationsdatei gespeichert werden (Geänderte Optionen werden mit einem * angezeigt). Drücken Sie [Strg]-S oder klicken Sie auf das Diskettensymbol. 5

6 Bauen und Anzeigen der Dokumentation Nach dem Speichern(!) klicken Sie rechts auf das Doxyfile und selektieren Sie Build Documentation : Das Konsolenfenster zeigt verschiedene Meldungen während des Build-Prozesses. Dabei entsteht in Ihrem Projekt ein Unterverzeichnis html, in welchem Sie eine index.html finden. Diese öffnen Sie mit einem Doppelklick in Eclipse. Alternativ können Sie natürlich auch z.b. in einem Explorer-Fenster diese Datei suchen und sie mit Ihrem gewohnten Browser öffnen. Im linken Frame der Seite klappen Sie die File list auf. Dort sind alle Dateien des Projekts gelistet. Klicken Sie auf die main.c, um die dazugehörige Dokumentation anzuzeigen: 6

7 Weiterführendes Auf der Doxygen-Homepage im Internet finden Sie eine vollständige Dokumentation aller Doxygen-Schlüsselwörter und Optionen. Unter anderem lassen sich auch Bilder (mit dem z.b. Flussdiagramme) in die Dokumentation einbinden. Sie können auch Beispiele für die Benutzung der Funktionen einfügen ). Mit Doxygen lernen Sie übrigens nicht nur C zu dokumentieren, denn Doxygen unterstützt viele Sprachen. 7

8 Eclipse-Vorlage Wie Sie sicherlich schon bemerkt haben, erstellt Ihnen Eclipse beim Einfügen neuer Source- (oder Header-) Dateien in ein Projekt Standard-Kommentare. Diese lassen sich soweit anpassen, dass Sie diese als Vorlage für Ihre Doxygen-Kommentierung verwenden können. Klicken Sie dafür auf Window-Preferences und führen Sie folgende Schritte aus: Ab jetzt wird der oben eingegebene Text jedes Mal beim Erstellen einer neuen Datei im Kopf eingefügt. Anpassen an Ihre Datei/Funktionen müssen Sie natürlich noch selbst. 8