Josef Pötzl: /* Wie wird dokumentiert */

Josef Pötzl — Thu, 24 Jun 2010 16:52:01 GMT

Wie wird dokumentiert

← Nächstältere Version		Version vom 16:52, 24. Jun. 2010
Zeile 25:		Zeile 25:

	Beispiele:		Beispiele:
-	* {{doxy\|page=~~index~~.html\|text=mittels Doxygen generierte Dokumentation}}	+	* {{doxy\|page=class_qpc_stoppuhr.html\|text=mittels Doxygen generierte Dokumentation}}
-	* {{websvn~~.draft~~\|path=~~branches~~/~~draft/com/modDirectCOM~~.bas\|text=VBA-Modul}}	+	* {{websvn\|path=base/modErrorHandler.bas\|text=VBA-Modul}}
-	* {{websvn~~.draft~~\|path=~~branches/draft/~~misc/QpcStoppuhr.cls\|text=VBA-Klasse}}	+	* {{websvn\|path=misc/QpcStoppuhr.cls\|text=VBA-Klasse}}

	=== Module ===		=== Module ===

Josef Pötzl: /* Wie wird dokumentiert */

Josef Pötzl — Thu, 24 Jun 2010 16:50:21 GMT

Wie wird dokumentiert

← Nächstältere Version		Version vom 16:50, 24. Jun. 2010
Zeile 25:		Zeile 25:

	Beispiele:		Beispiele:
-	* {{~~svn~~\|~~rep~~=~~test\|path=_codelib/doc/html/~~index.html\|text=mittels Doxygen generierte Dokumentation}}	+	* {{doxy\|page=index.html\|text=mittels Doxygen generierte Dokumentation}}
-	* {{websvn~~/file\|rep=CodeLib~~\|path=branches/draft/com/modDirectCOM.bas\|text=VBA-Modul}}	+	* {{websvn.draft\|path=branches/draft/com/modDirectCOM.bas\|text=VBA-Modul}}
-	* {{websvn~~/file\|rep=CodeLib~~\|path=branches/draft/misc/QpcStoppuhr.cls\|text=VBA-Klasse}}	+	* {{websvn.draft\|path=branches/draft/misc/QpcStoppuhr.cls\|text=VBA-Klasse}}

	=== Module ===		=== Module ===

Josef Pötzl: /* Modulkopf */

Josef Pötzl — Tue, 20 Apr 2010 22:40:26 GMT

Modulkopf

Neue Seite

{{TOCright}}
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.

== Was wird dokumentiert ==
[[Kategorie:Richtlinien:Dokumentation|{{PAGENAME}}]]
[[Kategorie:Programmierung]]

* Pflicht
** Modul- u. Klassenbeschreibung
** Public-Elemente von Modulen und Klassen
* Optional
** Hinweise im Code

{{note|text=Kommentare im Code sollten das Lesen des Codes unterstützen. Es ist allerdings nicht notwendig in einer If-Anweisung wie <code lang="vb">if x = y then</code> 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.
}}

== Wie wird dokumentiert ==
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:
* {{svn|rep=test|path=_codelib/doc/html/index.html|text=mittels Doxygen generierte Dokumentation}}
* {{websvn/file|rep=CodeLib|path=branches/draft/com/modDirectCOM.bas|text=VBA-Modul}}
* {{websvn/file|rep=CodeLib|path=branches/draft/misc/QpcStoppuhr.cls|text=VBA-Klasse}}

=== Module ===
==== Modulkopf ====
<source lang="vb">
'---------------------------------------------------------------------------------------
' 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

[...]

</source>

* <file> ist eine Pflicht-Angabe
* <license> kennzeichnet die Lizenz, unter der der Code freigegeben wird
* <use> ist notwendig, wenn Abhängigkeiten existieren (darf mehrmals verwendet werden).
* <replace> kommt zum Einsatz, wenn ein bestimmtes Modul überschrieben werden soll.
* <test> gibt ein Test-Modul (für Unit-Tests) an (darf mehrmals verwendet werden).
* <ref> gibt eine erforderliche Bibliotheks-Referenz an (darf mehrmals verwendet werden).
*: Beispiel:
*:<code>' <ref><name>DAO</name><major>5</major><minor>0</minor><guid>{00025E01-0000-0000-C000-000000000046}</guid></ref></code>

==== Prozeduren ====
===== Sub =====
<source lang="vb">
'---------------------------------------------------------------------------------------
' 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%)
[...]
</source>

===== Function =====
<source lang="vb">
'---------------------------------------------------------------------------------------
' 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%
[...]
</source>

=== Klassen ===
==== Klassenkopf ====
<source lang="vb">
'---------------------------------------------------------------------------------------
' 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.%
'
</source>

==== Methoden ====
Für Methoden gilt die gleiche Syntax wie bei einer Function bzw. Sub in einem Modul

==== Eigenschaften ====
<source lang="vb">
'---------------------------------------------------------------------------------------
' Property: %Eigenschaftsname%
'---------------------------------------------------------------------------------------
'/** '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung der Eigenschaft %
' </summary>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
'**/ '<-- Ende Doxygen-Block
'---------------------------------------------------------------------------------------
Public Property Get %Eigenschaftsname%() As %typ%
</source>

==== Ereignisse ====
<source lang="vb">
'---------------------------------------------------------------------------------------
' 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%)
</source>

=== Sonstiges ===
==== Enum-Anweisung ====

<source lang="vb">
'---------------------------------------------------------------------------------------
' 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
</source>

== Hinweise ==

Der Doxygen-Kommentarblock kann bei Bedarf mit weiteren Doxygen-Tags erweitert werden. Auf Auflistung aller Tags gibt es im [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen-Manual].

Für vereinfachtes Ergänzen der Kommentarblöcke ist das VBE-COM-Add-In [[Hilfe:Mz-Tools|Mz-Tools]] hilfreich.

{{related links|links=[[Hilfe:Doxygen|Doxygen-Hilfe]] : [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen Manual der offiziellen Doxygen-Website]}}

Richtlinien für die Code-Dokumentation - Versionsgeschichte

Josef Pötzl: /* Wie wird dokumentiert */

Josef Pötzl: /* Wie wird dokumentiert */

Josef Pötzl: /* Modulkopf */