*## End
Die Syntaxbeschreibung verwendet dabei einen senkrechten Strich für alternative Parameter und ein Leerzeichen für die Trennung gleichzeitig verwendbarer Parameter. Ob ein Parameter optional oder zwingend ist, wird in der Parameterbeschreibung mitgeteilt.
Zusätzlich zu den Kommentarbereichen werden folgende Informationen aus der Klassenbibliothek von Visual FoxPro als Information zur Klasse von dem genannten Werkzeug automatisch übernommen:
- Name der Klasse
- Name der Klassenbibliothek
- Name der Superklasse
- Name der Basisklasse
Diese Informationen können um weitere Felder aus den Klassenbibliotheken oder um indirekt ermittelbare Informationen erweitert werden, sofern dies als notwendig erachtet wird. Für diese einzeiligen Informationen wurden keine weiteren "Tags" angelegt, da die Eintragung in einer Eigenschaft einfacher und betriebssicherer (keine Tagschreibfehler) erscheint.
Dokumentation der Klasse
Jede Klasse besitzt eine Methode "zClassComment" (dieser Methodenname ist einmalig global frei konfigurierbar, muß aber einheitlich verwendet werden). Diese Methode dient ausschließlich der Dokumentation der Klasse und wird vollständig als Beschreibung der Klasse nach Rational Rose übernommen. Dabei können mehrere Abschnitte mit dem nachfolgenden Aufbau jeweils einmalig eingefügt werden. Sofern keine der Klauseln verwendet wird oder sofern ein Titel verwendet wird, wird die Beschreibung als "Beschreibung lang" übernommen. Der Titel kann dabei beliebig variabel gehalten werden, allerdings darf als erstes Wort weder "Methode" noch "Eigenschaft" noch eine der alternativen Klauseln verwendet werden. Die Unterscheidungen durch verschiedene Klauseln in dieser Dokumentationsmethode spielen in Rational Rose (bis auf den Stereotype) eigentlich keine Rolle sondern werden für die mögliche Extraktion der Angaben in eine WinWord-Dokumentation der Klasse via Rose Soda benötigt. Zusätzlich ist hier ein Dokumentationsabschnitt "Beispiel" zulässig, Beschreibung dieser Klausel siehe weiter unten. Folgende Kommentarklauseln können in dieser globalen Dokumentationsmethode der Klasse verwendet werden:
*##Beschreibung
*##Interface
*##Stereotype <name des stereotype>
*##Eigenschaft <name der eigenschaft> <datentyp> [protected]
*##Beispiel
*##Historie
Diese Kommentarabschnitte haben beschreibende Inhalte gemäß folgender Tabelle:
Bereich |
Inhaltsbeschreibung |
Beschreibung |
Allgemeine Beschreibung der Klasse |
Stereotype |
Einordnung der Klasse zu einer Kategorie gemäß Liste in Projekthandbuch |
Interface |
Beschreibung der Schnittstelle / Nutzungsprotokoll |
History |
Beschreibung der Klassenhistorie / Versionshistorie |
Beispiel |
Beispiel für die Verwendung der Klasse und deren Methoden |
Eigenschaft |
Ausführliche Beschreibung von Eigenschaften |
Ein Kommentar des Typs Beschreibung sieht dann folgendermaßen aus:
*##Beschreibung
Der Text landet in der Beschreibung
*## End
Ein Kommentar des Typs Stereotype sieht folgendermaßen aus:
*##Stereotype Serviceklasse
Aus diesem Abschnitt wird der Stereotyp entnommen.
*## End
Ein Kommentar des Typs Interface sieht folgendermaßen aus:
*## Interface
Der Text nach der Kennung wird als Beschreibung des Interface interpretiert.
*## End
Meist beschränkt man sich dabei allerdings auf einen Kommentar des Typs Beschreibung, ggf. einen Kommentar mit einem Beispielaufruf und dann folgen die Beschreibungen der Eigenschaften der Klasse.
Dokumentation von Eigenschaften
Ebenfalls in der globalen Dokumentationsmethode werden die Eigenschaften der Klasse beschrieben. Diese Beschreibungen landen allerdings nicht im globalen Beschreibungsfeld der Klasse in Rational Rose sondern werden in Rational Rose den jeweiligen Eigenschaften der Klasse zugeordnet. Deshalb ist die Angabe eines Eigenschaftsnamen notwendig. Zusätzlich kann der Typ der Eigenschaft angegeben werden - dieser könnte allerdings auch aus der Namenskonvention der Eigenschaft extrahiert werden; die explizite Angabe überschreibt dann die Definition aus der Namenskonvention. Über eine weitere Klausel ist es möglich, eine in Visual FoxPro wegen der Zugriffsnotwendigkeit aus enthaltenen Klassen nicht als "Protected" markierte Eigenschaft innerhalb des Objektmodells dennoch zu schützen, wenn diese nicht zum offiziellen Interface der Klasse gehört. Der Defaultwert einer Eigenschaft wird direkt aus der Eigenschaft gelesen (unterstellt wird, daß der Initialisierungswert der Eigenschaft auch der Defaultwert ist). Das Format der Syntax lautet dabei wie folgt:
*##Eigenschaft <name> <typ> [Protected]
*## End
Die einzelnen Elemente der einleitenden Zeile des Kommentars haben dabei folgende Bedeutung:
Klausel |
Beschreibung |
Eigenschaft |
Kennung für Dokumentation einer Eigenschaft |
<Name> |
Name der Eigenschaft |
<Typ> |
Optional Typ der Eigenschaft gemäß Typenliste, also Numerisch/Logisch usw. |
Protected
| Optional Schutz von in VFP nicht als Protected markierten Eigenschaften |
Hierzu zwei Beispielkommentare, die sich in der allgemeinen Dokumentationsmethode finden:
*##Eigenschaft lInit Logical Protected
Die Eigenschaft lInit wird nur intern verwendet, kann aber wegen Zugriff durch enthaltenen Objekte nicht in VFP
"Protected" geschaltet werden, gehört aber nicht zum Interface.
*##End
*##Eigenschaft oEA
Diese Eigenschaft wird aufgrund der Namenskonvention als "Objektreferenz" erkannt
*## End
Dokumentation von Methoden
Innerhalb einer Methode selbst kann eine Beschreibung der Methode angelegt werden. Diese Beschreibungen landen nicht im globalen Beschreibungsfeld der Klasse in Rational Rose sondern werden in Rational Rose den jeweiligen Methoden der Klasse zugeordnet. Sofern der Entwickler die Dokumentation der Methode nicht in der jeweiligen Methode vornimmt sondern die Dokumentation in die globale Dokumentationsmethode der Klasse stellt, ist die Angabe der Klausel "Methode" sowie eines Methodensnamens notwendig. Anderfalls sind diese Angaben optional. Über eine weitere Klausel ist es möglich, eine in Visual FoxPro wegen der Zugriffsnotwendigkeit aus enthaltenen Klassen nicht als "Protected" markierte Methode innerhalb des Objektmodells dennoch zu schützen, wenn diese nicht zum offiziellen Interface der Klasse gehört. Das Format der Syntax lautet dabei wie folgt:
*## Beschreibung [Methodenname] [Protected]
*## End
Hierzu ein Beispielkommentar, der sich am Anfang der eigentlichen Methode befindet:
**##Beschreibung
Die Methode wird verwendet, um die eigentliche Initialisierung durchzuführen. Diese Angaben wäre in der globalen Dokumentationsmethode notwendig.
*## End
Es wird dabei allerdings empfohlen, innerhalb der jeweiligen Methode zu kommentieren und nicht in der globalen Dokumentationsmethode, da die weiteren Beschreibungsmöglichkeiten sowieso bei der jeweiligen Methode bleiben müssen.
Dokumentation der Parameter
Die Dokumentation der Parameter erfolgt mit einem Kommentarblock je Parameter in der jeweiligen Methode. Falls keine Parameter vorhanden sind, aber dennoch eine Parameterdokumentation erfolgen soll, wird ein Kommentarblock ohne Parameternamen angelegt. Dies kann auch erfolgen, wenn die Parameter nicht einzeln dokumentierbar sein sollten. Die Parameterdokumentation wird in Rational Rose den einzelnen Parametern zugeordnet. Die Parameterdokumentation kann keinesfalls in der globalen Dokumentationsmethode eine Klasse erfolgen. Die Parameter können in willkürlicher Reihenfolge dokumentiert sein. Zusätzlich kann ein Parameter als "Optional" und/oder als "Rückgabewert" gekennzeichnet werden. Das Format der Syntax lautet dabei wie folgt:
*## Parameter <name> <typ> [Optional] [Rückgabe]
*## End
Die einzelnen Elemente der einleitenden Zeile des Kommentars haben dabei folgende Bedeutung:
Klausel |
Beschreibung |
<Name> |
Name des Parameters |
<Typ> |
Datentyp des Parameters gemäß Typenliste |
Optional |
Optional Angabe eines optionalen Parameters |
Rückgabe |
Optional Angabe, der Parameter kann auch für Rückgabe verwendet werden |
Hierzu zwei Beispielkommentare, die sich in der Methode selbst befinden:
*##Parameter tcUserName Character
Enthalten ist der notwendige Benutzername eines Anwenders.
*## End
*## Parameter tcPasswort Character Optional Rückgabe
Enthalten ist das optionale Passwort, welches per Referenz übergeben werden kann, um einen zusätzlichen Rückgabewert zu erhalten.
*## End
Dokumentation des Rückgabewerts
Die Dokumentation der Parameter erfolgt mit einem speziellen Kommentarblock innerhalb der jeweiligen Methode. Es wird nur die erste Beschreibung eines Rückgabewertes ausgelesen und verarbeitet. Die Dokumentation des Rückgabewertes wird in Rational Rose der Funktionsrückgabe zugeordnet. Zusätlich kann der Typ des Rückgabewertes angegeben werden - dieser könnte allerdings auch aus der Namenskonvention der Rückgabewerte extrahiert werden, sofern es nur am Methodenende einmalig einen Return-Befehl gibt; die explizite Angabe überschreibt dann die Definition aus der Namenskonvention. Das Format der Syntax lautet dabei wie folgt:
*## Rückgabe <typ>
*## End
In <Typ> wird der Typ des Rückgabewerts gemäß Typenliste, also Numerisch/Logisch usw. Hierzu zwei Beispielkommentare, die sich in der Methode selbst befinden:
*## Rückgabewert Logical
Die Methode gibt .T. zurück, wenn alles funktioniert hat, andernfalls .F.
*## End
Hierzu ein Beispielkommentar, der sich in der eigentlichen Methode befindet:
*## Rückgabewert
Es kann auch nur eine allgemeine Beschreibung der Rückgabe erfolgen. Der Datentyp wird in diesem Fall als Logical angenommen.
*## End
Dokumentation von Beispielaufrufen
Die Dokumentation eines Beispielaufrufs erfolgt mit einem speziellen Kommentarblock innerhalb der jeweiligen Methode für diese Methode und/oder innerhalb der globalen Dokumentationsmethode für Beispiele betreffs der Einsatzmöglichkeiten der Klasse. Es werden alle Beschreibungsblöcke zu Beispielaufrufen ausgelesen und verarbeitet. Hinter dem Befehlswort Beispiel kann noch ein Titel angegeben werden, der ebenfalls übernommen wird - sinnvoll, wenn mehrere Beispielaufrufe angeboten werden. Das Format der Syntax lautet dabei wie folgt:
*## Beispiel
*## End
Hierzu ein Beispielkommentar, der sich in der eigentlichen Methode befindet:
*## Beispiel
Die Methode wird aufgerufen mit =this.Methode()
Sonderfall: Die Methode kann auch aufgerufen werden mit =this.parent.&thiscName.Methode()
*## End
Anhang Datentypen
Folgende Datentypen können für Parameter und Rückgabewerte verwendet werden:
Datentyp VFP |
Beschreibung |
Character |
Zeichenketten und Text |
Numeric |
Numerische Daten (auch Integer) |
Logical |
Bool'sche Werte |
Object |
Referenz auf ein Objekt |
Date |
Datumswerte |
DateTime |
Datum und Uhrzeit |
Memo |
Nicht verwendet |
General |
Nicht verwendet |
Currency" |
Währungsdaten |
Undefined |
Nicht definiert bzw. variante Daten |
Array |
Datenfeld |