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.
Für eine übersichtliche Gliederung der Dateien empfehlen wir folgende Verzeichnisstruktur:
<Verzeichnis der .mdb/.accdb-Datei> -Doxygen (Zielverzeichnis) -Html -Pictures -Source (Exportverzeichnis beziehungsweise Source-Code-Verzeichnis)
In das Verzeichnis Doxygen speichern Sie die Doxygen-Konfigurationsdatei und in das Verzeichnis Source exportieren Sie die VBA-Module.
Damit Doxygen die Textdateien mit dem VB-Code erkennt, müssen Sie deren Dateierweiterung im Bereich Expert des Doxygen-Fensters im Bereich Input in der Eigenschaft FILE_PATTERNS eintragen (siehe Bild 3). Üblicherweise sind das die Erweiterungen *.bas und *.cls.
Bild 3: Doxygen-Konfiguration: File-Patterns
Den wichtigsten Konfigurationsschritt nehmen Sie im gleichen Bereich weiter unten für die Eigenschaft INPUT_FILTER vor (siehe Bild 4). In dieser Eigenschaft müssen Sie die VB-Filter durch folgenden Eintrag aktivieren (passen Sie den Pfad den Gegebenheiten Ihres Dateisystems an):
Bild 4: Doxygen-Konfiguration: Input-Filter
C:/ProgramData/doxygen/vbfilter/vbfilter.bat C:\ProgramData\doxygen\vbfilter
Nach dem Speichern der Doxygen-Konfigurationsdatei können Sie nun Ihre Code-Dokumentation erstellen. Dazu exportieren Sie zunächst die VBA-Module Ihrer Datenbank in das eingestellte Code-Verzeichnis und starten im Doxywizard-Register Run die Erzeugung der html-Dateien.
Zum Testen können Sie die Module des DBMS-Connection-Wizards verwenden, der in der letzten Ausgabe vorgestellt wurde – sie enthalten bereits einige von Doxygen verarbeitbare Kommentare.
Falls Sie nicht nur .html-Dateien erstellen wollen, sondern auch eine Hilfe-Datei erzeugt werden soll, benötigen Sie noch den HTML Help Workshop von Microsoft, dessen hhc.exe-Datei Sie in der HTML-Register-Eigenschaft HHC_LOCATION einstellen – vorher müssen Sie jedoch noch die Option GENERATE _HTMLHELP aktivieren (siehe Bild 5).
Bild 5: Doxygen-Konfiguration: CHM-Eigenschaften
Geben Sie außerdem unter CHM_FILE noch Pfad und Dateiname der zu erstellenden .chm-Datei an. Die .chm-Hilfe-Datei wird von Doxygen erzeugt und in das html-Verzeichnis eingefügt.
Access Add-In: Doxygen-Wizard
Damit der Aufwand für die Doxygen-Konfiguration nicht zu groß wird und Sie die VBA-Module mühelos exportieren können, haben wir Ihnen ein Access-Menü-Add-In erstellt.
Sie finden die zum Zeitpunkt der Drucklegung dieses Magazins aktuelle Version auf der Heft-CD beziehungsweise im Downloadbereich von http://www.access-im-unternehmen.de. Da das Tool jedoch weiterentwickelt wird, finden Sie die aktuelle Version jeweils hier: http://access.joposol.com/download/DoxygenWizard.zip
Zum Installieren speichern Sie die Datei DoxygenWizard.mda in einem beliebigen Verzeichnis. Starten Sie dann Access und rufen Sie den Add-In-Manager auf.
Fügen Sie die soeben gespeicherte .mda-Datei zu den vorhandenen Add-Ins hinzu. Anschließend finden Sie dieses im Menü der verfügbaren Add-Ins unter dem Namen Doxygen-Wizard.
Im Register Grundeinstellungen (s. Abb. 6) tragen Sie zunächst den Projektnamen und die Versionsnummer ein. Als Nächstes stellen Sie in dieses Register das Code-Verzeichnis und das Zielverzeichnis für die .html-Dateien ein.
Ende des frei verfügbaren Teil. Wenn Du mehr lesen möchtest, hole Dir ...
den kompletten Artikel im PDF-Format mit Beispieldatenbank
diesen und alle anderen Artikel mit dem Jahresabo