| |
 Gäste Online: 5
Keine Mitglieder Online
Registrierte Mitglieder: 1,050
Neustes Mitglied: Hydralistika
|
|
|
| Quellcode-Dokumentation mit Doxygen |
Warum Quellcode Dokumentation?
Das ist eine der häufigsten Fragen, wenn man Leuten von Doxygen erzählt. Hier sind die wichtigsten vier Gründe, aus denen man seinen Quellcode dokumentieren sollte:
- Man behält selber einen besseren Überblick über sein Projket, denn den verliert man bei größeren Projekten ja manchmal
- Sollten andere Leute an dem Programm mitarbeiten (bspw. bei Open-Source-Projekten) können sie die Dokumentation als erste Anlaufstelle nutzen und müssen sich nicht durch den Sourcecode hangeln
- Erstellt man z.B. eine Bibliothek, bekommt man immer eine aktuelle Dokumentation und muss Änderungen nicht mühsam per Hand eingeben
- Natürlich ist die Nutzung von Doxygen gesparte Zeit, weil man den Quellcode ja sowieso ausreichend kommentieren sollte und mit Doxygen muss man nicht alles z.B. in Word eintippen
Es gibt noch eine ganze Reihe von Gründen, aber das sind erstmal die wirhlich wichtigen.
Installation von Doxygen
Als erstes geht ihr am besten auf die Doxygen-Homepage (www.doxygen.org) und downloadet euch dann das entsprechende Paket für euer Betriebssystem. In dem nachfolgenden Abschnitten wird davon ausgegangen, dass ihr ein Linux-artiges System verwendet. Windows-Nutzer müssen die Kommandos etwas ändern. Installiert das Paket auf eurem System. Öffnet nun eine Konsole und geht doxygen ein. Sollte es einen Fehler geben, dass der Befehl nicht gefunden wurde, solltet ihr die PATH_Variable erweitern. Unter Linux navigiert ihr dazu in euer Home-Verzeichnis und gebt den befehl vim .profile ein. Es öffnet sich ein Konsoleneditir. In die Datei fügt ihr die folgenden Zeilen ein:
PATH = /pfad/zu/doxygen:$PATH
export PATH
Meldet euch nun neu am System an. Ihr solltet jetzt Doxygen starten können.
Die Kommentierung des Quellcodes
Nun beginnt die eigentliche Arbeit. Wir müssen den Quellcode entsprechend den Doxygen-Konventionen kommentieren. Dazu unterstützt Doxygen erstmal sehr viele Stile, ich will euch an dieser Stelle den bekanntesten vorstellen, das javaDoc Format:
/**
* Diese Funktion macht absolut nichts ...
*/
void donothing(void)
{
return;
}
Wenn ihr Parameter und / oder Rückgabewerte habt nehmt ihr die folgenden Schlüsselwörter:
/**
* Diese Funktion gibt den Parameter zurück ...
* @param value Der Parameter
* @return Der Wert des Parameter
*/
int function(int value)
{
return value;
}
Wir erstellen die Dokumentation
Wir haben jetzt etwas Code zusammen und können uns jetzt einmal daran probieren eine Dokumentation anzulegen. Wir nutzen dazu den DoxyWizard.
Im ersten Schritt wählt ihr die Option Wizard, im Doxygen zu konfigurieren. Geht jetzt die entsprechenden Daten zu eurem Programm ein. Wählt dann euren Projektordner aus. Sollte euer Projekt unterordner haben, solltet ihr ein Häkchen bei "Scan recursively" machen. Darunter gebt ihr an, in welchem ordner die fertige Dokumentation gespeichert werden soll. Es ist immer sehr nützlich, einen Ordner namens "doc" oder "doxygen" im Projektverzeichnis zu haben, wo man die Dokumentation direkt zur hand hat. Im nächsten Tag wählt ihr unten eure Programmiersprache aus, für die Doxygen die Dokumentation optimieren soll. Im Tab "Output" wählen wir aus, in welchen Format wir die Dokumentation erstellt haben wollen. Die für euch wichtigsten sollten erst einmal HTML und LaTeX sein. Wählt noch die Optionen zu diesen beiden Ausgabeformaten und dann gehts zum letzten Tab "Diagrams". hier könnt ihr auswählen, ob Doxygen ein Klassendiagramm erstellen soll. Es ist eure Entscheidung, aber ich empfinde diese Funktion eher als Spielzeug und eine Funktion für Schonheitsfanatiker. Sie ist nicht wirklich nützlich.
Jetzt sind wir mit der Konfiguration fertig. Speichert das File im zweiten Schritt mit "Save" im Projektverzeichnis ab. Ihr könntet jetzt im Wizard weiterarbeiten, ich finde aber, das die Arbeit über die Konsole jetzt deutlich besser funktioniert. Ihr navigiert in der Konsole in euer Projektverzeichnis. Jetzt gebt ihr einfach doxygen ein. Jetzt sollten im entsprechenden Ordner Unterordner mit den entsprechenden Dateivarianten vorhanden sein.
Sollte eine leere Dokumentation erstellt werden, müst ihr etwas mit der Konfigurationsdatei herumspiele. Meisten müsst ihr die "EXTRACT_" Optionen alle auf YES setzen, damit funktioniert es.
Kommentierung - Klappe die Zweite
Natürlich kommen wir mit den paar Schlüsselwörter, die wir bis jetzt kennen, nicht sonderlich weit. Also wird es jetzt Zeit, noch ein paar neue zu erlernen.
/** \file test_2.cpp Eine Datei
* Eine kurze Beschreibung der Datei.
* Und jetzt sollten wir noch eine längere Beschreibung
* machen, denn ansonsten macht Code-Dokumentierung
* ja keinen Spaß.
* @author Cooler Typ
* @version 1000.99.888
*/
/** Eine globale Variable
* Hier muss wieder eine längere Beschreibung hin.
*
*/
extern int beispiel;
/** \class CBeispiel
* Eine Klasse.
* Und auch hier wieder eine längere Beschreibung.
*/
class CBeispiel
{
public:
/**
* Eine coole Funktion.
* Eine längere Beschreiung ;)
* \bug Funktioniert nicht!
* \todo Bug berichtigen
* @param param Ein Parameter
* @return Den Parameter
*/
int funktion(int param) { return 0; }
};
Diese neuen Schlüsselwörter müssten eigentlich selbsterklärend sein. Wichtig ist noch: Die Kurzbeschreibungen müssen immer mit einen Punkt beendet werden. Alles was danach kommt, zählt zur längeren Beschreibung.
Noch ein paar Tipps und Tricks
Jetzt sind wir schon fast am Ende dieses Tutorials angelangt. Am Ende möchte ich noch ein paar Tipps für eure weitere Arbeit mit Doxygen geben.
Zuerst wollen wir etwas in die Konfigurationdatei hineinschauen. Hier kann man als erstes die Sprache der Dokumentation mit dem Schlüsselwort OUTPUT_LANGUAGE ändern. Sollte euer programm sich noch in der Entwicklung befinden, könnt ihr euch eure Bug- und Todo-Vermerke in einer Liste anzeigen lassen. Dazu ändert ihr die Schlüsselwörter GENERATE_TODOLIST und GENERATE_BUGLIST. Wollt ihr den Sourcecode mit in der Dokumentation veröffentlichen, könnt ihr das Schlüsselwort SOURCE_BROWSER auf YES setzen. Standardmässig werden eure Kommentare aber herausgeschnitten. Das könnt ihr mit dem Schlüsselwort STRIP_CODE_COMMENTS ändern.
Als nächstes will ich noch einmal zur Dokumentation selbst kommen. Ihr soltet, wenn ihr eine Funktion anlegt, sofort die entsprechenden Kommentare anfertigen und es nicht schleifen lasse, euer Programm üppig zu dokumentieren. Später habt ihr keine Lust mehr bzw. macht es nur auf die Schnelle. Ihr solltet auch immer bedenken, dass ihr die Dokumentation nicht nur für euch , sondern auch für andere Leute macht, die diese verstehen müssen.
In diesem Zuge will ich euch auch noch schnell den Befehl \example vorstellen. Ihr gebt mit ihm eine Beispieldatei an, in dem die entsprechende Funktion genutzt wird. Nach dem Befehl ist wieder eine kurze Beschreibung und eine lange Beschreibung einzufügen.
The End
Und schon ist es wieder vorbei, dieses schöne Toturial. Ich hoffe euch hat es gefallen und ihr habt sobiel gelernt, dass ihr in Zukunft auch Doxygen nutzt.
Wenn ihr euch noch weiterbilden wollt, könnt ihr auch mal einen Blick in die Dokumentation( 8-D ) von Doxygen werfen. Dort könnt ihr euch noch ein paar Sachen herausnehmen, die ich in diesem Tutorial noch nicht vorgestellt hab.
Sollten noch Fragen sein, sprecht mich bei www.isogames.de per PN an.
Dieses Tutorial wurde freundlicherweise von androphinx bereitgestellt.
|
|
am 07. Dezember 2008 11:19
Schönes tut, werde mir doxygen direkt mal anschauen  |
am 29. April 2010 08:12
Sehr schöner Beitrag! Ich suchte einige Tutorials auf http://rapidpedia.com search engine, aber nichts gutes gefunden, Ihr Artikel hat mir sehr viel geholfen! Nun will ich weniger Probleme bei der Arbeit mit doxygen haben. |
|
|
|
Bitte einloggen, um einen Kommentar zu schreiben.
|
|
|
Noch kein Mitglied? Klicke hier um dich zu registrieren.
Passwort vergessen? Fordere Hier ein neues an
|
|
|
|
Naja k kurdt hat mal seinen Senf dazugegeben, aber sonst.. 
