Konfigurationsdatei für Doxygen erstellen

Mit Hilfe von Doxygen können schnell und komfortabel Code Dokumentationen für C# erstellt werden. Dazu erstellt man für ein Projekt einmalig eine Konfigurationsdatei und kann diese dann entweder über die Doxygen GUI oder direkt über das Einbinden eines Externen Tools in Visual Studio Express erstellen.

Damit Doxygen verwendet werden kann, muss man es zunächst von der Doxygen Homepage heruntergeladen werden (http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc).

Hinweis: Unter Windows verwendet man am besten das Installationspaket, weil darin auch Doxywizard enthalten ist, mit dessen Hilfe man einfach Konfigurationsdateien für ein Projekt anlegt. Doxywizard wird im Folgenden verwendet um Doxygen zu konfigurieren.

Nach der Installation von Doxygen ruft man zunächst Doxywizard auf. Dies wird verwendet, um eine Doxygen-Konfigurationsdatei für ein C# Projekt zu erstellen. Wie es auf der Doxygen Homepage so schön heißt: Du willst die Konfigurationsdatei nicht im Texteditor erstellen… 😉

Am einfachsten verwendet man den Reiter Wizard um das Projekt anzulegen. Ein paar wenige Experteneinstellungen sind auch notwendig, aber die machen wir dann ganz zum Schluss.

Ich verwende zum verdeutlichen, wie was gemeint ist ein Beispielprojekt, welches FooBar heißt und in C:\Projekte\Foobar liegt. In kursiv sind dann die Beispiel-Werte angegeben.
  • Unter „Step 1: “ wird zunächst der Installationsordner von Doxygen angegeben. Hier wird die Ausgabe erfolgen, wenn keine weitere Angabe erfolgt.C:\Programme\Doxygen
  • Unter „Step 2: “ und dem Reiter „Wizard“ markieren wir zunächst „Project“ und geben die Rahmendaten für das Projekt ein
    • Project Name: Name des Projekts. Hier sollte der gleiche Name verwendet werden, der auch im VS-Projekt benutzt wird.
      FooBar
    • Project synopsis: Kurzbeschreibung des Projekts.
      FooBar ist ein Beispielprojekt um zu zeigen, wie man Doxgen konfiguriert.
    • Project version or id: Die Version des Projekts. Hier bietet sich an, die Version des Assemblies zu verwenden.
      1.0.0.0
    • Project logo: Hier wird ein Logo ausgewählt. Das Logo wird oben links in der Ecke angezeigt und sollte die Maße 200×50 nicht überschreiten.
      Wir verwenden für Invid-Projekte das Logo „Firmen-Logo_Kameleon_rechts_dunkelblau_blau_klein.jpg“. Kann leer bleiben.
    • Source code directory: Das Basisverzeichnis, in dem die Quellen zu finden sind.
      C:\Projekte\Foobar
    • Scan recursively: Hier wird angegeben, ob Unterverzeichnisse mit einbezogen werden sollen. Da es nicht schadet, den Haken zu setzen, wenn man keine Unterverzeichnisse hat, würde ich ihn immer aktivieren.
    • Destination directory: Verzeichnis, in das die Ausgabe erfolgen soll. Sinnvollerweise ist das das Projektverzeichnis. Es kann aber auch etwa ein Netzlaufwerk im Intranet sein.
      C:\Projekte\Foobar
  • Nun markieren wir „Mode“ um weitere Einstellungen vorzunehmen
    • Select the desired extraction mode: Hier wird angegeben, ob nur per Doc-Comment dokumentierte Entities oder auch undokumentierte ausgegeben werden sollen. Da man hier spätestens sieht, wo noch Dokumentation fehlt, sollte hier „All Entities“ angegeben werden. Das hängt aber vom Verwendungszweck ab.
      All Entities
    • Select programming language […]: Hier sollten wir natürlich die Optimierung für C# (und Java) aktivieren
      Optimize for Java or C# output
  • Nun markieren wir „Output“ um weitere Einstellungen für die Generierung vorzunehmen
    • HTML: Generiert eine HTML-Ausgabe, welche in jedem DHTML- und Javascript-fähigen Browser eine gute Figur abgibt. Die unterschiedlichen Möglichkeiten geben an, wie die Ausgabe im Detail erfolgt:
      • plain HTML: Eine einfache, einseitige HTML-Seite mit entsprechenden Verlinkungen
      • with navigation panel: Zusätzlich ein Navigationspanel an der linken Seite, in dem zwischen den einzelnen Bestandteilen des Projekts gesprungen werden kann
      • eine einzige .chm Datei, welche dann als Microsoft Hilfedatei verwendet werden kann.
      • With search function: ergänzt ein Suchfeld in der oberen rechten Ecke, mit dem man komfortabel in der Dokumentation suchen kann (setzt Javascript im Browser voraus).
      • Über den Button „Change color“ erreicht man einen Dialog, in dem man die Farbe der HTML-Seiten beeinflussen kann.

      HTML [x] / with navigation panel / With search function

    • LaTeX: Generiert eine LaTeX-Datei Die Verwendung setzt [http://de.wikipedia.org/wiki/LaTeX LaTeX] voraus.
      Latex [ ]
    • Man Pages: Ein mir unbekanntes Werkzeug. Kann ich nichts zu sagen. Generiert .cs.3-Dateien.
    • Rich Text Format (RTF): Erstellt ein RTF-Dokument. Evt. sinnvoll, wenn man die Dokumentation verschicken möchte. Muss aber irgendwie noch parametriert werden.
    • XML: Eine XML-basierte Ausgabe. Evt. sinnvoll, wenn man eigene Generatoren für die Dokumentation verwendet.
  • Zuletzt markieren wir „Diagrams“
    • Die Auswahl „use built-in class diagram generator“ ist bestens geeignet, solange man nicht ohnehin bereits GraphViz einsetzt.
  • Anschließend aktivieren wir den Reiter“Expert“. Hier gehe ich nur auf die Einstellungen ein, die relevant sind. Alles weitere auf eigene Gefahr 😉
    • Build:
      • EXTRACT_ STATIC: Dieser Schalter aktiviert, dass auch statische Methoden dokumentiert werden. Das schließt vor allem auch Extension Methods mit ein.

Um die Dokumention nun zu erstellen, wählt man den Reiter „Run“ und klickt auf „Run doxygen“. Die entsprechenden Ausgaben werden dann im entsprechend konfigurierten Ordner erstellt.

Wenn die Dokumentation soweit ok ist, kann die Konfiguration gespeichert werden. Ich würde sie im Projektordner unter dem Namen der Solutiondatei mit erweiterter Änderung abspeichern (siehe Doxygen als Externes Tool in Visual Studio Express anlegen für den Grund) .  Wenn man aber immer die GUI verwendet um die Doku zu generieren sind der Ablageort und der Name wahlfrei.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.