Together - Dokumentation generieren - Kommentare

[hirnstroem]

'loha Folks,

ich würde gerne eine Together-Dokumentation generieren, bei welcher all meine vielen Kommentare im Quellcode mitberücksichtigt werden. Leider finde ich nirgens Hinweise, wie denn die Annotationen zu formatieren sind, damit sie berücksichtigt werden.

Weiss zufälligerweise jemand, wie diese Kommentare auszusehen haben, oder zumindest wo nachgelesen werden kann, wie sie auszusehen haben?

Grüsse
hirnstroem

[hirnstroem]

Benutzt diese "Dokumentation generieren"-Funktion denn überhaupt jemand?

[markusl]

Hallo hirnstroem,

ich habe vor einer Weile die Quelltext-Dokumentationsfunktion von
dem im BDS2006 integrierten Together evaluiert und für nicht ausreichend befunden.

Die Syntax lehnt sich an den XMLDOC-Standard an, unterstützt allerdings
nicht alle dort definierten Tags und verhält sich etwas eigentümlich.

Sofern Du es dennoch ausprobieren möchtest, kannst du im Interface-Abschnitt Deiner
Klassen unmittelbar vor einer Methode/Property folgenden Kommentar setzen:

Delphi-Quellcode:

/// <author>Test Tester</author>
/// <remarks>This is a test function
/// description 2 
/// description 3
/// description 4</remarks>
function xyz : String;
....

Ich benutze im Moment JADD und bin sehr zufrieden damit.
Es ist sehr leistungsfähig, benutzt Javadoc-Syntax, kann direkt PDFs generieren und ist vielfältig konfigurierbar.


Gruss,

Markus

[hirnstroem]

Hallo Markus, vielen Dank für die Antwort.

Ich habe bereits versucht solche Konstrukte wie das folgende zu bilden, jedoch mit minder grossem Erfolg, sprich, in der Dokumentation wurden dies Kommentare nicht angezeigt.

Delphi-Quellcode:

/// <author>ava</author> // <- solche sachen sollten ja eigentlich greifen
/// <remarks>inde deus abest</remarks>
procedure TfrmLogin.btnloginClick(Sender: TObject);
var
  Password, DBPassword, Username, DBUsername: String;
  Q: TADOQuery;
begin
  // Usernae and Password are transformed into lower case characters
  // to avoid Caps Lock problems

Die Delphi-Hilfe bringt einen da auch nicht wirklich weiter.

Andere Dokumentationsgeneratoren werden mit dem vermerk angeboten, alles ab Delphi 2005 nicht mehr so wirklich oder noch nicht vollständig zu unterstützen.

Mal abwarten.

[markusl]

Du musst deine Kommentare über der Deklaration stehen haben, nicht bei der Definition der Methoden.
Dann sollte es eigentlich funktionieren.

Markus

[Motzi]

Ich bin heute auf dasselbe Problem gestoßen.
Ich füge im Interface-Abschnitt diverse Kommentare zu Interfaces bzw Methoden hinzu, diese tauchen in der generierten Dokumentation aber nirgends auf. Weiß jemand woran das liegen kann?

Gruß, Motzi

[markusl]

@Motzi: Poste doch mal einen Beispiel-Kommentar, der nicht funktioniert.

Ich sehe grade dass Du Delphi 2005 einsetzt. Eventuell funktioniert es dort nicht so,
kann es hier grade nicht testen.

Gruss,

Markus

[HeinzJ]

In Delphi 2007 scheint es das gleiche Problem mit den "/// ..." Komentaren zu geben.