VBA-Code mit Doxygen dokumentieren

Jeder Programmierer muss einmal Farbe bekennen: Nämlich, wenn er ältere, umfangreiche und komplexe Anwendungen wieder ausgräbt und sich in diese einarbeitet, weil der Kunde änderungswünsche äußert. Wohl dem, der gut dokumentiert hat – er findet sich mit Sicherheit gleich besser zurecht als ohne Dokumentation. Noch einfacher haben Sie es, wenn Sie Methoden und Eigenschaften Ihrer Anwendungen schön übersichtlich in einer Hilfedatei nachlesen können. Doch wer betreibt schon einen solchen Aufwand Die Antwort ist einfach: Jeder, der Spaß daran und den vorliegenden Beitrag gelesen hat.

Wozu externe Code-Dokumentation

Sie werden sicher zustimmen, dass Kommentare im Code die Lesbarkeit erhöhen. Eine Beschreibung der Aufgabe einer Prozedur und die Bedeutung der Parameter erleichtert deren Verwendung. Auch Kommentare im Code-Block vereinfachen ihre Überarbeitung, wenn man nach einiger Zeit in einer Prozedur einen Fehler beseitigen muss oder eine Erweiterung einbauen möchte.

Doch warum sollten Sie Code-Kommentare in einer Hilfedatei oder einer .html-Seite bereitstellen, wenn der Kommentar jederzeit im Code nachgelesen werden kann Für folgende Szenarien ist eine externe Hilfe-Datei sinnvoll:

• Code-Bibliotheken (Access-mde/accde oder COM-dll)
• Schnittstellenbeschreibungen
• Modularer Anwendungsaufbau (inkl. Kapselung von Code in Klassen)

Davon abgesehen kann es natürlich auch so nützlich sein, nicht jedes Mal im Modul einzelne Objekte oder Methoden aufzusuchen, wenn man einmal eine Beschreibung nachsehen möchte – zumal ja meist auch noch eine Menge Code enthalten ist und die Beschreibungen nicht gleich erkennbar sind.

Ein Kommentar in einer privaten (nach außen nicht sichtbaren) Prozedur einer Klasse hat für eine externe Code-Dokumentation eher wenig Bedeutung, da für den Benutzer dieser Klasse die internen Methoden nach dem Konzept der Kapselung keine Rolle spielen.

Den Benutzer einer solchen Klasse interessieren viel mehr die nach außen sichtbaren Elemente wie Methoden, Eigenschaften und Ereignisse. Fasst man deren Beschreibung in einer gut lesbaren Struktur zusammen, entsteht ein nützliches Werkzeug zum Schreiben von Code, der auf die Klasse zugreift, da nicht immer in der Klasse nachgelesen werden muss.

Stellen Sie sich einmal vor, wenn zum Access-Objekt-Modell keine Online-Hilfe verfügbar wäre.

Jeder Access-VBA-Programmierer würde viel Zeit mit der Suche nach den passenden Parameter-Werten der Methoden aus diesen Access-Klassen verschwenden. Mit der Online-Hilfe reicht ein Blick in die Dokumentation der betroffenen Methode und man erhält einen Überblick über die Einsatzmöglichkeiten.

Mit dem Einsatz des OpenSource-Tools Doxygen können Sie eine ähnliche Dokumentation Ihres Codes erreichen, ohne besonderen Mehraufwand durch die Dokumentation zu betreiben. Sie müssen nur die Anmerkungen, die Sie zu Prozeduren, Modul-Köpfen und so weiter schreiben, in eine für Doxygen erkennbare Form bringen (s. Listing 1).

Listing 1: Beispiel für Prozedur-Kommentar

''-------------------------------------------------------------------
'' Function: DeleteTableDef (2009-06-28)
''-------------------------------------------------------------------
''/**
'' <summary>
'' Tabelle im Frontend löschen
'' </summary>
'' <param name="sTabName">Tabellen-Name</param>
'' <returns>Boolean</returns>
'' <remarks>
'' </remarks>
''**/
''------------------------------------------------------------------
Public Function DeleteTableDef(ByVal sTabName As String) As Boolean
    ...
End Function

Das Resultat ist beeindruckend – Abb. 1 liefert einen kleinen Vorgeschmack auf das, was sich mit dem hier vorgestellten Tool erreichen lässt. Voraussetzung ist natürlich das Anlegen einer Kommantarzeil in entsprechender Syntax.

Bild 1: Eine mit unserem Tool und Doxygen erstellte .chm-Datei

Was folgt

In diesem Beitrag zeigen wir Ihnen zunächst, welche Tools Sie für die automatische Erstellung der Dokumentation aus benutzerdefinierten Kommentaren im Quellcode benötigen und wie Sie diese installieren. Danach stellen wir das Tool Doxygen vor und zeigen, wie es grundsätzlich funktioniert.

Da Sie aber mit Access arbeiten und natürlich gern alles mit dieser Anwendung erledigen würden, haben wir Ihnen noch ein Add-In gebaut, das die Eingabe der nötigen Parameter und die Steuerung von Doxygen erlaubt. Ganz zum Schluss lernen Sie, wie die Syntax der Kommentare aussehen muss, damit Doxygen diese verarbeiten kann.

Hilfstools

Bevor Sie eine Dokumentation Ihres Codes mit Doxygen erstellen können, müssen Sie einige Hilfsmittel herunterladen. Folgende Programme und Tools werden benötigt:

• Doxygen zum Erzeugen der Dokumentation: http://www.stack.nl/~dimitri/doxygen/
• Vbfilter, ein awk-Skript zum Konvertieren des VB-Codes in einen von Doxygen auswertbaren Text: http://www.stack.nl/~dimitri/doxygen/dl/vbfilter.zip (Beschreibung siehe http://www.stack.nl/~dimitri/doxygen/helpers.html)
• Unix tools (sh.exe, gawk.exe, tee.exe) – diese werden für die vbfilter.bat benötigt: http://sourceforge.net/projects/unxutils/
• Optional: HTML Help Workshop

Die hier beschriebenen Tools werden wohlgemerkt nur für die Erstellung der Dokumentation benötigt. Der Benutzer kann später ohne spezielle Software auf diese zugreifen.

Die Doxygen-Installation beginnen Sie mit der Ausführung der Setup-Datei doxygen-1.x.x-setup.exe. Nach der Doxygen-Installation müssen Sie die VB-Filter installieren. Dazu kopieren Sie die Dateien aus der vbfilter.zip-Datei in ein beliebiges Verzeichnis.

Dieses Verzeichnis darf im Verzeichnispfad kein Leerzeichen enthalten. Später benötigen Sie bei der Verwendung von Doxygen Schreibrechte in diesem Verzeichnis (beachten Sie das vor allem, wenn Sie Windows Vista oder Windows 7 verwenden).

Ein passender Ablageort wäre C:\ProgramData\doxygen\vbfilter.

In das gleiche Verzeichnis kopieren Sie auch die Dateien sh.exe, gawk.exe und tee.exe aus der Zip-Datei UnxUtils.zip.

Konfiguration

Nachdem alle Dateien installiert wurden, sollten Sie die Datei vbfilter.bat anpassen, damit sichergestellt ist, dass sh.exe erreicht werden kann.

Ergänzen Sie dafür in der Batch-Datei eine Zeile (s. Listing 2, Zeile 2), die auf das Laufwerk c:\ wechselt, in dem Ihre vbfilter-Programmdateien liegen.

Listing 2: Die Konfigurationsdatei Vbfilter.bat

@echo off
C:
cd %1%
set teeCommand=./tee -a ''%2%.doxylog''
set awkCommand=./gawk.exe -f vbfilter.awk ''%2%''
set fullCommand="%awkCommand% | %teeCommand%"
rem sh.exe -c %fullCommand%
sh.exe -c "./gawk.exe -f vbfilter.awk ''%2%''"

Die allgemeine Konfiguration ist damit abgeschlossen. Starten Sie nun den Doxywizard aus dem Programm-Menü.

In der ersten Eingabemaske (siehe Bild 2) stellen Sie den Projektnamen und das Verzeichnis der Code-Dateien ein. In dieses Verzeichnis müssen Sie die VBA-Module aus der Access-Datenbank exportieren, deren Kommentare Doxygen verarbeiten soll (wie dies geschieht, erläutern wir weiter unten).

Bild 2: Startmaske von Doxywizard

Danach stellen Sie in dieser Maske das Zielverzeichnis ein. In das Zielverzeichnis beziehungsweise dessen html-Unterverzeichnis schreibt Doxygen die .html-Dateien und die Hilfedatei. Normalerweise reicht für das Zielverzeichnis die Angabe eines Punktes aus.

Mit dieser Einstellung wird das Verzeichnis der Doxygen-Konfigurationsdatei als Basis-Pfad verwendet und die .html-Dateien werden in das Unterverzeichnis html eingefügt. Natürlich können Sie die Dateien auch in ein html-Unterverzeichnis im Verzeichnis der zu dokumentierenden Access-Datenbank schreiben lassen.

Username or Email

Passwort

Angemeldet bleiben