Tool zum Überprüfen von Dokumentation von Methoden

[TheFrog]

Hallo zusammen,

ich bin auf der Suche nach einem Tool für Delphi (in meinem Fall XE2), welches mir die Dokumentation von Methoden-Header im Sourcecode überwacht.

Folgendes Beispiel:

Bei uns im Projekt werden Methoden mit folgendem Header versehen, welcher kurz die Funktionsweise, wie auch die Aufrufparameter beschreibt:

Delphi-Quellcode:

{-------------------------------------------------------------------------------
 Name   : MyFunction
 Info   : Diese Methode macht .......
 Input  : Param1 = der Parameter ist zuständig für ....
          Param2 = und dieser Parameter für jenes ...
 Output : None
 Result : None
-------------------------------------------------------------------------------}
procedure TForm1.MyFunction(Param1, Param2: Integer);
begin
  // do something
end;

Wenn jetzt nachträglich an der Methode etwas geändert wird (z.B. eine Parameter hinzukommt oder wegfällt), dann stimmt die Dokumentation nicht mehr mit der eigentliche Methode überein. Hier wäre es jetzt toll, wenn es irgendein Tool gibt, welches mich darauf aufmerksam macht. Ich habe von einem Kollegen gehört, dass in C# sowas mit dem Resharper möglich ist.

Meine Frage:
Gibt es sowas ähnliches auch für Delphi?

Ich möchte hier jetzt auf keinen Fall eine Diskussion anstossen, wie sinnvoll welche Arten von Dokumentationen sind. Oder ob man besser die neue Form der XML-Dokumentation verwendet oder nicht.
Ich möchte nur wissen, ob ich meine Kollegen hier dazu zwingen kann, ihre Dokumentation auf dem Laufenden zu halten, wenn sich am Code was ändert.

Vielen Dank schonmal, Hans.

[Dejan Vu]

Du kannst vielleicht mit viel Aufwand prüfen, ob die verwendeten Parameter auch im Kommentar auftauchen, aber ob die Beschreibung noch stimmt, kannst Du nicht prüfen.

Das ist das blöde an Kommentaren: Sie sind böse (aber für ne Doku z.B. notwendig). Aber keine Diskussion...

[TheFrog]

Danke für die Antwort!

Ich wollte eigentlich vermeiden, dass ich selber ein Tool schreibe, sondern vielmehr auf was bereits fertiges zurückgreifen. Aber soweit mir bekannt, kann weder GExperts, noch der CodeExplorer diese Aufgabe für mich erfüllen .

Es würde mir vorerst schon reichen, wenn das Tool nur die Parameter selber korrekt anmeckert (an den logischen Inhalt der Dokumentation wage ich gar nicht zu denken).

[Stevie]

Documentation Insight kanns nicht, das hab ich vorhin ausprobiert.

[TheFrog]

Schade, trotzdem Danke fürs Ausprobieren!

[mjustin]

Für Dokumentation benutze ich Doxygen (www.doxygen.org), das diverse Dokumentationsstile unterstützt. Es validiert die Dokumentation und schreibt Hinweise in eine Logdatei.

Code:

BTJMSConnection.pas:647: warning: argument 'Text' of command @param is not found in the argument list of TBTJMSSession::CreateTextMessage

Um es mit Delphi einzusetzen benutze ich den pas2dox Preprozessor. Beide Tools sind Free Open Source. Pas2dox wird anscheinend nicht mehr weiterentwickelt, kleinere Mängel die sich durch den pas2dox Preprozessor Schritt ergeben sind aber bisher noch im Rahmen geblieben.
Doxygen erzeugt ohne Einsatz von Zusatztools auch Vererbungsdiagramme, zu sehen zum Beispiel hier.

Documentation Insight enthält laut Feature Matrix eine Documentation Validation, leider konnte ich dazu keine nähere Beschreibung finden. Ich würde gerne auf Documentation Insight umstellen, muss dazu aber erst meine JavaDoc-Stil Kommentare auf XML Kommentare umstellen.

[Der schöne Günther]

Zitat von Stevie:

Documentation Insight kanns nicht, das hab ich vorhin ausprobiert.

Ich verstehe nicht- Das ist doch im RAD Studio alles schon eingebaut? Und grade das baut doch auf Documentation Insight auf.

• Warnungen wenn ich einen Parameter nicht dokumentiert habe
• Wenn ich einen Parameter dokumentiere den es nicht (mehr) gibt
• Und vieles mehr

Siehe Bilder.


Einen "Babysitter" mit "Hey, du hast an der Implementation etwas verändert. Hast du denn auch schön die Doku angepasst?" kenne ich allerdings auch nicht.

[Stevie]

Zitat von Der schöne Günther:

Zitat von Stevie:

Documentation Insight kanns nicht, das hab ich vorhin ausprobiert.

Ich verstehe nicht- Das ist doch im RAD Studio alles schon eingebaut? Und grade das baut doch auf Documentation Insight auf.

• Warnungen wenn ich einen Parameter nicht dokumentiert habe
• Wenn ich einen Parameter dokumentiere den es nicht (mehr) gibt
• Und vieles mehr

Siehe Bilder.


Einen "Babysitter" mit "Hey, du hast an der Implementation etwas verändert. Hast du denn auch schön die Doku angepasst?" kenne ich allerdings auch nicht.

Ich hab auf Validate Documentation geklickt und da hats mir nix ausgespuckt.
Wenn allerdings der Compiler solche Optionen hat, dann ist ja alles geritzt.

Edit: Gerade mal ausprobiert. Dazu muss man bei den Compiler Optionen "Generate XML documentation" anhaken. Leider bekommt man bei den Messages nicht die richtige Zeilennummer, was das ganze nahezu unbrauchbar macht.

[Uwe Raabe]

Zitat von Der schöne Günther:

Ich verstehe nicht- Das ist doch im RAD Studio alles schon eingebaut?

Das funktioniert halt nur mit der XML-Dokumentation, wobei ich das aber als "no option" verstanden hatte:

Zitat von TheFrog:

Ich möchte hier jetzt auf keinen Fall eine Diskussion anstossen, wie sinnvoll welche Arten von Dokumentationen sind. Oder ob man besser die neue Form der XML-Dokumentation verwendet oder nicht.

Wenn wir jetzt aber trotzdem diese Diskussion anstoßen wollen, dann: Ja, in diesem Fall wäre es besser die neue Form der XML-Dokumentation zu verwenden.

[Der schöne Günther]

Zitat von Stevie:

Leider bekommt man bei den Messages nicht die richtige Zeilennummer, was das ganze nahezu unbrauchbar macht.

Es geht- Man hat immerhin den Methodennamen. Besser als nichts.