Dokumentationsgenerierung mit Delphi 2006

[Martin99]

Mit Delphi 2006 gibt es die Möglichkeit, auf der Modellseite eine HTML-Dokumentation zum aktuellen Projekt zu generieren - eine tolle Möglichkeit!

Standardmässig erscheinen in dieser Dokumentation alle Units (als Namespace), die Klassen in diesen Units mit den Properties und Methoden. Wie kann ich aber hier noch Kommentare in diese Dokumentation einfügen (z.B. Beschreibung der Methode oder der Parameter), damit die Leser dieser Dokumentation auch wissen, was die Methode macht und was sie erwartet und zurückgibt, was die Vorbedingungen für den Aufruf sind etc.?

Martin

[Martin99]

Habe eine Möglichkeit gefunden
Hier zur Dokumentation, falls jemand anderes dieses Problem auch hat:

• 1. Auf der Diagrammsicht mit der rechten Maustaste auf das Element klicken, dem eine Beschreibung hinzugefügt werden soll
• 2. Auswählen "Einschränkungen..." zur Definition von Bedingungen für den Aufruf oder "Benutzereigenschaften..." zur Definition von sonstigen Beschreibungen
• 3. Auf der erscheinenden Maske "Hinzufügen" klicken
• 4. Einen Namen für das zu beschreibende Element eingeben (z.B. "Description" oder "Parameter 1" oder "Returnwert").
• 5. Die Beschreibung eingeben. Über den Button mit den drei Punkten kann auch eine mehrzeilige Beschreibung eingegeben werden.

Die Punkte 3 bis 5 können mehrfach wiederholt werden. Bedingung: der gleiche Name darf nur einmal vorkommen. Man kann also nicht, wie z.B. in JavaDoc, mehrere "@param" Einträge hintereinander machen.

Die eingegebenen Beschreibungen werden vorerst einmal vor der Deklaration des ausgewählten Elements in den Code eingefügt. Beispiel:

Delphi-Quellcode:

    ///<desc>Einen Phrase erstellen
    ///Als Input wird die ID des Phrases benötigt. Der Phrase muss also schon einmal identifiziert worden sein.
    ///Vorgehen: 1. IdentifyWords
    ///2. (mit den identifizierten Wörtern) FindPhrases
    ///3. (mit dem ausgewähltem Phrase) CreatePhrase</desc>
    ///  <paramater1>PhrID = ID des neuen Phrases</paramater1>
    ///  <mod__constraintReferencedElement>design:node:::85ix7n07m_n</mod__constraintReferencedElement>
    ///  <returnwert>Phrase als Interface ITBLPhrase</returnwert>
    function CreatePhrase(PhrID: Integer): ITBLPhrase;

Das obige Beispiel erscheint dann so in der Dokumentation:
...
1:Einschränkung 1
PhrID > 0
Constraint language
OCL
...
desc
Einen Phrase erstellen
Als Input wird die ID des Phrases benötigt. Der Phrase muss also schon einmal identifiziert worden sein.
Vorgehen: 1. IdentifyWords
2. (mit den identifizierten Wörtern) FindPhrases
3. (mit dem ausgewähltem Phrase) CreatePhrase
parameter1
PhrID = ID des neuen Phrases
returnwert
Phrase als Interface ITBLPhrase

[Martin99]

Noch eine Ergänzung:

• Alle eingegebenen Namen für die Benutzereigenschaften werden auf Kleinschreibung umgewandelt.
• Die Namen für die Benutzereigenschaften dürfen keine Spaces enthalten.
• Als Namen für die Benutzereigenschaften sind gewisse Schlüsselwörter nicht zugelassen, z.B. "description" oder "author".
  
  Der Editor akzeptiert zwar die Eingabe, wenn diese Wörter gross geschrieben werden, die eingegebenen Werte werden dann, mit klein geschriebenem Namen, im Code eigefügt, werden dann aber nicht in die Dokumentation übernommen.

Diese Schlüsselwörter beziehen sich wohl, im Gegensatz zu den Benutzereigenschaften, auf irgend welche Standardeigenschaften. Wie ich diese definieren kann, habe ich aber noch nicht herausgefunden.

Martin

[Martin99]

Dies funktioniert auch umgekehrt:

Man kann die Kommentare im entsprechenden Format (drei Schrägstriche am Anfang der Zeile, Beginn und Ende des Kommentars in XML-Notation definiert) direkt in den Code schreiben:

Delphi-Quellcode:

///<param1>...</param1>
///<param2>...
///...</param2>

Sofern man dabei keinen Formatfehler macht und kein Schlüsselwort als Namen wählt, erscheint dieser Text dann als neuer Eintrag unter Benutzereigenschaften auf der Diagrammansicht und in der generierten Dokumentation.