Gemeinsam zu mehr Effizienz in der Anwendungserstellung
K (→Wie wird dokumentiert) |
K (→Wie wird dokumentiert) |
||
| Zeile 25: | Zeile 25: | ||
Beispiele: | Beispiele: | ||
| - | * {{doxy|page= | + | * {{doxy|page=class_qpc_stoppuhr.html|text=mittels Doxygen generierte Dokumentation}} |
| - | * {{websvn | + | * {{websvn|path=base/modErrorHandler.bas|text=VBA-Modul}} |
| - | * {{websvn | + | * {{websvn|path=misc/QpcStoppuhr.cls|text=VBA-Klasse}} |
=== Module === | === Module === | ||
Inhaltsverzeichnis |
Ein wichtiger Bestandteil der Code-Bibliothek ist die Dokumentation der Module. Der Großteil dieser Code-Dokumentation kann in den Modulen selbst gestaltet werden. Falls genauerer Anleitungen mit Bildern erforderlich sind, kann dieser Teil ins Wiki verlagert werden.
Kommentare im Code sollten das Lesen des Codes unterstützen. Es ist allerdings nicht notwendig in einer If-Anweisung wie if x = y then einen Kommentar wie "prüfen ob x = y ist" anzufügen. Den Ablauf einer Prozedur sollte grundsätzlich aus dem Code erkennbar sein. Kommentare sollten nur unterstützend wirken. Sobald umfangreiche Kommentare für das Verstehen eines Prozedurablaufs notwendig werden, ist das meist ein Anzeichen für eine notwendige Aufteilung der Prozedur in mehrere überschaubare Prozeduren.
Die Code-Dokumentation für die Public-Elemente ist mit Doxygen-Tags im Module bzw. in der Klasse zu gestalten, damit eine html-Dokumentation bzw. eine chm-Datei automatisch erstellt werden kann. Der Doxygen-Kommentarblock wird für Klassen und Module im Kopf des jeweiligen VBA-Codemoduls eingefügt. Für Prozeduren in Modulen und Eigenschaften, Methoden und Ereignisse in Klassen wird der Doxygen-Block direkt über die Dekalrationszeile eingefügt.
Ein Doxygen-Block wird mit '/** eingeleitet und endet mit '**/ zwischen diesen Zeilen dürfen nur Kommentarzeilen stehen.
Kommentare innerhalb von Prozeduren, die nicht in der HTML-Dokumentation landen sollen, dürfen nicht mit den Doxygen-Kennungen eingrenzt werden.
Beispiele:
'--------------------------------------------------------------------------------------- ' Module: %Modulname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung des Moduls % ' </summary> ' <remarks> ' % Detailbeschreibung und Zusatzinformationen % ' </remarks> ' \ingroup %Gruppen-Kennung% '**/ '<-- Ende Doxygen-Block '<codelib> '<-- Start CodeLib-Block ' <file>%Pfad/Dateiname%</file> '<-- CodeLib-Abladeort und Kennung ' <license>_codelib/license.bas</license> '<-- Verweis auf die Lizenz ' <use>%Pfad/Dateiname%</use> '<-- Im Code-Modul benötigtes Element ' <replace>%Pfad/Dateiname%</replace> '<-- zu ersetzendes Code-Modul ' <test>%Pfad/Dateiname%</test> '<-- Verweis auf ein Test-Modul '</codelib> '<-- Ende CodeLib-Block '--------------------------------------------------------------------------------------- ' %Hinweise, die nicht in der Html-Dokumentation stehen sollen, ' aber für einen Programmierer dieses Moduls hilfreich sind.% ' Option Compare Text Option Explicit [...]
' <ref><name>DAO</name><major>5</major><minor>0</minor><guid>{00025E01-0000-0000-C000-000000000046}</guid></ref>
'--------------------------------------------------------------------------------------- ' Sub: %Prozedurname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung der Funktion (Aufgabe der Funktion) % ' </summary> ' <param name="%Parameter 1%">%Beschreibung des 1. Parameters</param> ' <remarks> ' % Detailbeschreibung und Zusatzinformationen % ' </remarks> '**/ '<-- Ende Doxygen-Block '--------------------------------------------------------------------------------------- Public Sub %Prozedurname%(ByVal %Parameter 1% As %typ%) [...]
'--------------------------------------------------------------------------------------- ' Function: %Prozedurname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung der Funktion (Aufgabe der Funktion) % ' </summary> ' <param name="%Parameter 1%">%Beschreibung des 1. Parameters</param> ' <param name="%Parameter 2%">%Beschreibung des 2. Parameters</param> ' <returns>%Beschreibugn des Rückgabewertes</returns> ' <remarks> ' % Detailbeschreibung und Zusatzinformationen % ' </remarks> '**/ '<-- Ende Doxygen-Block '--------------------------------------------------------------------------------------- Public Function %Prozedurname%(ByVal %Parameter 1% As %typ%, ByVal %Parameter 2% As %typ%) As %typ% [...]
'--------------------------------------------------------------------------------------- ' Class: %Klassenname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung der Klasse % ' </summary> ' <remarks> ' % Detailbeschreibung und Zusatzinformationen % ' </remarks> ' \ingroup MISC '<-- Zuordnung zur Doxygengruppe '**/ '<-- Ende Doxygen-Block '<codelib> '<-- Start CodeLib-Block ' <file>%Pfad/Dateiname%</file> '<-- CodeLib-Abladeort und Kennung ' <license>_codelib/license.bas</license> '<-- Verweis auf die Lizenz ' <use>%Pfad/Dateiname%</use> '<-- Im Code-Modul benötigtes Element ' <replace>%Pfad/Dateiname%</replace> '<-- zu ersetzendes Code-Modul ' <test>%Pfad/Dateiname%</test> '<-- Verweis auf ein Test-Modul '</codelib> '<-- Ende CodeLib-Block '--------------------------------------------------------------------------------------- ' %Hinweise, die nicht in der Html-Dokumentation stehen sollen, ' aber für einen Programmierer dieses Klasse hilfreich sind.% '
Für Methoden gilt die gleiche Syntax wie bei einer Function bzw. Sub in einem Modul
'--------------------------------------------------------------------------------------- ' Property: %Eigenschaftsname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung der Eigenschaft % ' </summary> ' <remarks> ' % Detailbeschreibung und Zusatzinformationen % ' </remarks> '**/ '<-- Ende Doxygen-Block '--------------------------------------------------------------------------------------- Public Property Get %Eigenschaftsname%() As %typ%
'--------------------------------------------------------------------------------------- ' Event: %Ereignisname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung des Ereignisses % ' </summary> ' <param name="%Parameter 1%">%Beschreibung des 1. Parameters</param> ' <param name="%Parameter 2%">%Beschreibung des 2. Parameters</param> ' <remarks> ' % Detailbeschreibung und Zusatzinformationen % ' </remarks> '**/ '<-- Ende Doxygen-Block Public Event %Ereignisname%(ByVal %Parameter 1% As %typ%, ByVal %Parameter 2% As %typ%)
'--------------------------------------------------------------------------------------- ' Enum: %Enumname% '--------------------------------------------------------------------------------------- '/** '<-- Start Doxygen-Block ' <summary> ' % Kurzbeschreibung der Aufzählung % ' </summary> ' <list type="table"> ' <item><term>%Element 1% (1)</term><description>%Beschreibung Element 1%</description></item> ' <item><term>%Element 2% (2)</term><description>%Beschreibung Element 2%</description></item> ' </list> '**/ '<-- Ende Doxygen-Block '--------------------------------------------------------------------------------------- Public Enum %Enumname% %Element 1% = 1 %Element 2% = 2 End Enum
Der Doxygen-Kommentarblock kann bei Bedarf mit weiteren Doxygen-Tags erweitert werden. Auf Auflistung aller Tags gibt es im Doxygen-Manual.
Für vereinfachtes Ergänzen der Kommentarblöcke ist das VBE-COM-Add-In Mz-Tools hilfreich.
Weiterführende Links: Doxygen-Hilfe : Doxygen Manual der offiziellen Doxygen-Website