Delphi Quellcode Dokumentation

[Ajintaro]

Hi DP!

Wie dokumentiert ihr eure Quellcodes ? Nutzt ihr dafür tools wie Documentation Insight o.ä. ? Gibt es keine Delphi (XE6) keine eigene Dokumentationsfunktion ?

Gruß,

Ajin

[Bernhard Geyer]

Delphi hat da auch schon was eingebaut: http://docwiki.embarcadero.com/RADSt...ation_Comments
Selbst verwenden wir noch den Javadoc-Ansatz: http://en.wikipedia.org/wiki/Javadoc

[himitsu]

Das Help-Insight kann einige Basisinfos vom Docu-Insight/XMLDoc anzeigen und das bereits seit Delphi 2005. (vermutlich ... jedenfalls nur in der neuen IDE)
In den CodeTemplates liegen dafür auch einige Vorlagen, die du immernoch verwenden kannst ... nur halt nicht so "komfortabel", wie mit dem Documentation Insight.

Ich verwende immernoch das Documentation Insight, denn ich nurtze den Code selber als Dokumentation (die Funktions- und Klassenheader) und scheibe zusätzlich auch die Beschreibung via Docu-Insight dort rein, denn es ist unheimlich praktisch, da die das Help-Insight das beim Code-Schreiben mit anzeigt.

[Der schöne Günther]

Documentation Insight war in einer Express-Vatiante dabei, seit XE6 nicht mehr. Musst du jetzt zusätzlich kaufen.

[Stevie]

Dokumentation? Pff, son Mumpitz, braucht man nich!

Ok, Spaß beseite, wenn ich mal dokumentiere, dann mit Documentation Insight.
Ist um einiges einfacher, als in den xmldoc tags händisch rumzuhampeln.

P.S. Evtl gibts demnächst bei Spring4D mal nen DocInsight abzustauben, muss mir nur noch was fieses als Aufgabe ausdenken

[Dejan Vu]

Im Grunde genommen ist das aber auch nichts anderes als das mit den XML-Tags. Der eine tippt lieber, der andere klickt lieber (auf das DocInsight-Fenster).

Wichtig ist, *das* man es macht, und vor allen Dingen, *was* genau (mindestens) drin stehen sollte.

Schwierig wird es -generell- bei Kommentaren wie:

Delphi-Quellcode:

/// <summary> 
/// Removes all unsolved references
/// </summary>
Procedure TMyClass.RemoveAllUnresolvedReferences;
Begin
End;

Aber bevor man in den ToolTips gar nichts sieht und sich fragt "Was macht die denn nun genau, die Methode", schreibt man lieber solch redundantes Zeugs rein. Aber vielleicht kann man mit 1-2 Sätzen noch Details beschreiben, oder ein Beispiel geben. Dann sieht das nicht ganz so bescheuert aus.

Wohlgemerkt: Nur bei öffentlichen Methoden. Private Methoden sind ja eh selbsterklärend.

[himitsu]

Die Gratisversion, welche mal im Delphi dabei war, erlaubte es eh nur Public-Zeugs zu dokumentieren.
Private-Methoden und Kommentare in Implementation waren verboten und zusätzlich auch praktisch jede praktische Formatierung oder zusätzliche HTML-Tags (Bilder, Listen usw.) in den Kommentaren. (Der Editor bot es nicht an, aber wenn es in den Kommentaren schon drin stand, dann wurde es dennoch angezeigt)