Zur Hauptseite ... Zum Onlinearchiv ... Zum Abonnement ... Zum Newsletter ... Zu den Tools ... Zum Impressum ... Zum Login ...

Achtung: Dies ist nicht der vollständige Artikel, sondern nur ein paar Seiten davon. Wenn Sie hier nicht erfahren, was Sie wissen möchten, finden Sie am Ende Informationen darüber, wie Sie den ganzen Artikel lesen können.

Kompletten Artikel lesen?

Einfach für den Newsletter anmelden, dann lesen Sie schon in einer Minute den kompletten Artikel und erhalten die Beispieldatenbanken.

E-Mail:

Gedrucktes Heft

Diesen Beitrag finden Sie in Ausgabe 1/2010.

Unser Angebot für Sie!

Lesen Sie diesen Beitrag und 500 andere sofort im Onlinearchiv, und erhalten Sie alle zwei Monate brandheißes Access-Know-how auf 72 gedruckten Seiten! Plus attraktive Präsente, zum Beispiel das bald erscheinende Buch 'Access 2010 - Das Grundlagenbuch für Entwickler'!

Diesen Beitrag twittern

Zusammenfassung

Dokumentieren Sie den VBA-Code Ihrer Anwendungen und erstellen Sie .chm-Dateien auf Basis dieser Kommentare.

Techniken

VBA, Dokumentation

Voraussetzungen

Access 2000 und höher

Beispieldateien

DoxygenWizard.mda

Shortlink

www.access-im-unternehmen.de/703

VBA-Code mit Doxygen dokumentieren

Josef Pötzl, Graz

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.

pic007.png

Abb. 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 (s. Abb. 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).

dg_start.png

Abb. 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:

Sie haben das Ende des frei verfügbaren Teils des Artikels erreicht. Lesen Sie weiter, um zu erfahren, wie Sie den vollständigen Artikel lesen und auf viele hundert weitere Artikel zugreifen können.

Sind Sie Abonnent?Jetzt einloggen ...
 

Kompletten Artikel lesen?

Einfach für den Newsletter anmelden, dann lesen Sie schon in einer Minute den kompletten Artikel und erhalten die Beispieldatenbanken.

E-Mail:

Verwandte Beiträge:

Effizientes Codieren

Grundlagen der Quellcodeverwaltung

Tabellen und Felder dokumentieren

Optionen in Properties speichern

Rund um Binärzahlen

TreeView-Konfigurator

Erweitern des VBA-Editors

Beschreibung von Tabellen und Co. nutzen

Modale Dialoge mal anders

Formulare generieren

Fehlersuche und –behandlung mit Access

Zippen ohne Zusatzkomponente

Validieren mit Klasse

© 2003-2015 André Minhorst Alle Rechte vorbehalten.