Hintergrund
Im Rahmen von .NET-Projekten sind XML-Kommentare eine gute Möglichkeit seine Methoden und Klassen zu kommentieren. Die Kommentare werden von der Entwicklungsumgebung ausgewertet und vom integrierten Intellisense angezeigt wenn man eine der dokumentierten Klassen oder Methoden verwendet.
Visual Studio bietet die Möglichkeit bei jedem Build-Vorgang die kompletten XML-Kommentare in eine XML-Datei zu extrahieren. Die extrahierte XML-Datei kann verwendet werden um von anderen Applikationen aus auf die Dokumentation zuzugreifen ist aber als Referenz / Dokumentation eher weniger geeignet.
Will man die Dokumentation z.B. auf einer Projekt-Webseite veröffentlichen oder daraus ein PDF-Dokument generieren bietet sich Doxygen als freies Dokumentations-System an.
Doxygen
doxygen bietet die Möglichkeit direkt aus dem Code eine HTML oder LaTeX-Dokumentation zu generieren. In Verbindung mit dot oder graphviz besteht sogar die Möglichkeit die Abhängigkeiten der Klassen grafisch darstellen zu lassen. Im folgenden beschreibe ich die Installation von Doxygen und wie man aus einem C#-Projekt eine HTML-Dokumentation generiert.
- Download von doxygen und Installation mit den Defualt-Einstellungen
- Konfiguration von doxygen über das Doygen GUI frontend
- Unter “Project”:
- Pfad für Arbeitsverzeichnis festlegen
- Projektname, Version, Logo etc. definieren
- Pfad auswählen in dem sich die Quellen des C#-Projekts befinden und ggf. Rekursive Suche verwenden
- Ausgabeverzeichnis für die Dokumentation definieren - Unter “Mode”:
- Auswählen ob alle oder nur dokumentierte Entitäten extrahiert werden sollen
- Programmiersprache für die die Ausgabe optimiert werden soll wählen (hier C#) - Unter “Output”:
- HTML Ausgabe wählen
- falls gewünscht kann man die Farben der Webseite und eine Navigationsleiste parametrieren - Unter “Diagrams”:
- Hier habe ich das dot Werkzeug aus dem GraphViz Paket gewählt, weil damit deutlich bessere Diagramme generiert werden als mit dem integrierten Klassendiagramm-Generator - Unter dem Reiter “Expert” kann die zu generierende Dokumentation noch im Detail angepasst werden.
- Unter dem “Topic” “Project” sollte der Wert “OUTPUT_LANGUAGE” auf “German” gesetzt werden falls man deutsche Kommentare verwendet hat
- Die Option “FULL_PATH_NAMES” sollte deaktiviert werden das sonst der Projekt-Pfad komplett mit in die Dokumentation aufgenommen wird.
- Um die Diagramme erzeugen zu können muss der Pfad zum GraphViz-Paket unter “Dot” angegeben werden. - – Die anderen Optionen können verwendet werden um ein Fein-Tuning der Dokumentation vorzunehmen. Die einzelnen
- Unter dem Reiter “Run” mit “Run doxygen” den Vorgang starten…
- Doxygen sucht nun im angegebenen Verzeichnis nach Source-Code und generiert daraus die Dokumentation im HTML-Format.
- Nach Abschluss des Vorgangs lässt sich über den Button “Show HTML output” die generierte HTML-Dokumentation aufrufen.