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:

Zitat von Stevie (Beitrag 1289678)

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:

Zitat von Der schöne Günther (Beitrag 1289745)

Zitat:

Zitat von Stevie (Beitrag 1289678)

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:

Zitat von Der schöne Günther (Beitrag 1289745)

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:

Zitat von TheFrog (Beitrag 1289638)

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:

Zitat von Stevie (Beitrag 1289749)

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.

[Stevie]

Zitat:

Zitat von Der schöne Günther (Beitrag 1289754)

Besser als nichts.

Deshalb schrieb ich auch "nahezu" unbrauchbar ;)

[Chemiker]

Hallo,

„Documentation Insight“ scheint es in der Prof.-Version von XE3 aber nicht zu geben. Von daher ist es für den Beitragsersteller irrelevant.

Bis bald
Chemiker

[Uwe Raabe]

Zitat:

Zitat von Chemiker (Beitrag 1289939)

„Documentation Insight“ scheint es in der Prof.-Version von XE3 aber nicht zu geben. Von daher ist es für den Beitragsersteller irrelevant.

In dem Fall kann er es aber immer noch käuflich erwerben.

[Der schöne Günther]

Zitat:

Zitat von Chemiker (Beitrag 1289939)

„Documentation Insight“ scheint es in der Prof.-Version von XE3 aber nicht zu geben.

Klar, von XE2-XE5 war es dabei.

[Chemiker]

Hallo,

Zitat:

Klar, von XE2-XE5 war es dabei.

Stimmt, aber in XE6 und XE7 ist es nicht mehr dabei, warum auch immer. Und es ist dann blöd, wenn man damit angefangen hat und es dann bei der nächsten Version wieder als Tool nicht zur Verfügung steht.


Bis bald
Chemiker

[Uwe Raabe]

Zitat:

Zitat von Chemiker (Beitrag 1289945)

Und es ist dann blöd, wenn man damit angefangen hat und es dann bei der nächsten Version wieder als Tool nicht zur Verfügung steht.

Aber es steht doch noch zur Verfügung - halt nicht mehr gratis. Das ist doch ein durchaus gängiges und legitimes Verfahren, ein neues Produkt erstmal durch Gratisabgabe schmackhaft machen und danach kostenpflichtig anzubieten. Dann kann ja jeder selbst entscheiden ob es einem den Preis wert ist. Selbst QuickReport (war als Standardversion gratis in D3 - D7 dabei) kann man heute noch für aktuelle Delphi-Versionen kaufen.

[Bernhard Geyer]

Zitat:

Zitat von Uwe Raabe (Beitrag 1289947)

Zitat:

Zitat von Chemiker (Beitrag 1289945)

Und es ist dann blöd, wenn man damit angefangen hat und es dann bei der nächsten Version wieder als Tool nicht zur Verfügung steht.

Aber es steht doch noch zur Verfügung - halt nicht mehr gratis. Das ist doch ein durchaus gängiges und legitimes Verfahren, ein neues Produkt erstmal durch Gratisabgabe schmackhaft machen und danach kostenpflichtig anzubieten. Dann kann ja jeder selbst entscheiden ob es einem den Preis wert ist. Selbst QuickReport (war als Standardversion gratis in D3 - D7 dabei) kann man heute noch für aktuelle Delphi-Versionen kaufen.

Man kann ja hoffen das Emba den Laden kauft und dann als integraler Bestandteil anbietet.
Leider wandert das oft dann nur in die Enterprise-Version. Siehe FireDac das nur sinnvoll aber der Enterprise verwendet werden kann.

[Jens01]

Zitat:

Stimmt, aber in XE6 und XE7 ist es nicht mehr dabei, warum auch immer.

Das ist doch das Spiel. Oder glaubt jemand, dass Emba was zu verschenken hat.
Wie bei nem Drogendealer. Erst abhängig machen und dann teuer verkaufen.:thumb:

[Stevie]

Zitat:

Zitat von Jens01 (Beitrag 1289954)

Das ist doch das Spiel. Oder glaubt jemand, dass Emba was zu verschenken hat.
Wie bei nem Drogendealer. Erst abhängig machen und dann teuer verkaufen.:thumb:

Documentation Insight ist nicht von Embarcadero sondern von DevJet Software.
Der Deal mit Embarcadero, die Express Version mit Delphi auszuliefern, wurde von DevJet vor ca einem Jahr beendet. Gründe dafür kenne ich nicht.

[Jens01]

Zitat:

Documentation Insight ist nicht von Embarcadero sondern von DevJet Software.

Ist bekannt. Es wird aber von Emba so suggeriert, als würden sie wertvolle Software mitgeben/ verschenken. Es sind -nach meiner Einschätzung- nur Testprogramme, was eigentlich okay ist, aber sie sind eben kein Mehrwert. Für mich ist die Werbung etwas irreführend.

[Uwe Raabe]

Zitat:

Zitat von Jens01 (Beitrag 1289980)

Es wird aber von Emba so suggeriert, als würden sie wertvolle Software mitgeben/ verschenken. Es sind -nach meiner Einschätzung- nur Testprogramme, was eigentlich okay ist, aber sie sind eben kein Mehrwert.

Im Fall von DocInsight war das aber wirklich ein Mehrwert - zumindest für den Anwender. Die Leistungsfähigkeit der gebundleten Version war immerhin so groß, daß kaum jemand die kostenpflichtigen Versionen gekauft hat. Das war wohl auch ein Grund für DevExpress dieses Angebot zu beenden.

Als Testprogramme würde ich das auch nicht unbedingt bezeichnen, denn es sind immerhin vollwertige (keine alten Versionen wie man sie manchmal bei Zeitschriften findet und somit auch wertvolle) Programme ohne Zeitbegrenzung, die immer noch produktiv genutzt werden können - vielleicht nicht mit der neuesten Version. Niemand kann erwarten, daß solche Beigaben in alle Ewigkeit mitgegeben werden. Wenn ich heute ein Auto aus dem Sonderangebot des Autoherstellers meines Vertrauens erwerbe, bei dem ein Dutzend normalerweise kostenpflichtige Extras für lau mitgeliefert werden, kann ich dann erwarten, daß ich diese auch bei meinem nächsten Autokauf gratis dazu bekomme?

Wenn solche zeitlich begrenzten Dreingaben den Verkauf dieser Programme ankurbeln, umso besser. Um nur einige aus der Liste zu nennen: ModelMaker Code Explorer, FinalBuilder, Documentation Insight, CodeSite (ist sogar noch dabei) sind alles Programme, die ich immer noch als Vollversion täglich verwende (die meisten sogar schon bevor sie mit Delphi gebundlet wurden) und auf gar keinen Fall missen möchte. Wir müssen ja (fast) alle von unserer Arbeit leben, oder? So natürlich auch die Hersteller dieser Tools. Wer ist nur auf diese irrsinnige Idee gekommen, daß Software nichts kostet. Jeder Entwickler müsste es doch eigentlich besser wissen.

Nebenbei: vermisst eigentlich niemand InstallAware?

[Jens01]

Zitat:

Im Fall von DocInsight war das aber wirklich ein Mehrwert - zumindest für den Anwender. Die Leistungsfähigkeit der gebundleten Version war immerhin so groß, daß kaum jemand die kostenpflichtigen Versionen gekauft hat. Das war wohl auch ein Grund für DevExpress dieses Angebot zu beenden.

Oder, es war genau so geplant. Weißt ja: Drogendealer/ Abhängigkeit

Zitat:

Wer ist nur auf diese irrsinnige Idee gekommen, daß Software nichts kostet. Jeder Entwickler müsste es doch eigentlich besser wissen.

Entwickelst du, damit Dir Kunden etwas zahlen? Hmm, ich mache das ganz selbstlos. Egal..
Das ist ja okay, aber die Werbung, die Emba damit betreibt, ist für mich irreführend.

[Bernhard Geyer]

Zitat:

Zitat von Jens01 (Beitrag 1289983)

Zitat:

Im Fall von DocInsight war das aber wirklich ein Mehrwert - zumindest für den Anwender. Die Leistungsfähigkeit der gebundleten Version war immerhin so groß, daß kaum jemand die kostenpflichtigen Versionen gekauft hat. Das war wohl auch ein Grund für DevExpress dieses Angebot zu beenden.

Oder, es war genau so geplant. Weißt ja: Drogendealer/ Abhängigkeit

Der Vergleicht hinkt gewaltig. Die einmal mit einer gebundelten Version geliefert Edition ist nicht laufzeitbegrenzt. Ein Drogendealer könnte nicht davon leben das man eine Dosis unbegrenzt verwenden könnte.

Zitat:

Zitat von Jens01 (Beitrag 1289983)

Das ist ja okay, aber die Werbung, die Emba damit betreibt, ist für mich irreführend.

Für dich ja. Die meisten Entwickler wissen das aber einzuschätzen und sind froh etwas zu haben das sie mit der einen gekauften Version unendlich lange verwenden können. Und wenn ein Versionsupdate ansteht (manche steigen nur alle paar Jahre um) kann man sich überlegen ob man auch dieses Tool wieder haben will und plant es im Invest mit ein.

[Stevie]

Zitat:

Zitat von Jens01 (Beitrag 1289983)

Werbung, ... irreführend.

Aber dass du z.B. durch den Konsum dieses Energydrinks in silber/blauen Dosen fliegen kannst, glaubst du nicht oder? :stupid:

[Jens01]

Verkauft eigentlich einer von euch wirklich Drogen!?
Bei Uwe könnte ich mir so'ne Plantage auf dem Dachboden vorstellen. Oder?:roteyes: :drunken:

[Dejan Vu]

Zitat:

Zitat von Stevie (Beitrag 1289990)

Zitat:

Zitat von Jens01 (Beitrag 1289983)

Werbung, ... irreführend.

Aber dass du z.B. durch den Konsum dieses Energydrinks in silber/blauen Dosen fliegen kannst, glaubst du nicht oder? :stupid:

Hüstel. Andere schon :mrgreen:
:wall:

Im Ernst: Werbung darf nicht in die Irre führen oder lügen. Bei uns nicht, und auch sonst nicht. In anderen Ländern muss man -eventuell bedingt durch generationenlang gepflegte ländliche Inzucht- die Messlatte für den gesunden Menschenverstand in einer Senke auf den Boden legen, aber bei uns Gott sei dank nicht. Ich kann also als Verbraucher erwarten, das das, was auf der Verpackung steht, auch stimmt.

Ich bezweifle jedoch, das in irgend einer Delphi-Werbung etwas irreführendes steht.

[TheFrog]

Hallo,

vielen Dank ersma für die rege Diskussion!

Um auf das Ursprungsthema zurückzukommen:

Ich habe mal den Vorschlag vom schönen Günther aufgenommen und Versuche gemacht, dass mir das RAD-Studio die Arbeit abnimmt.

Ich wollte eigentlich nicht auf die XML-Dokumentation umsteigen, aber wenn es hier irgendwie zielführend ist, dann muss ich wohl die Umstellung nach und nach machen.

Fazit:
Es sieht schon recht vielversprechend aus, will heißen, es kommen die von mir gewünschten Warnungen. Damit kann man sicher schon mal was anfangen.

Also, danke für die Tipps und Anregungen!

[Der schöne Günther]

Schön dass es was gebracht hat. Von Documentation Insight könnte ich mich auch nicht mehr trennen. Drogen oder nicht, ich brauche den Stoff.

Bei der Gelegenheit: Schaue mal hier wie man das in 5 Minuten noch mächtig aufpimpen kann:
http://www.delphipraxis.net/174891-d...p-insight.html

[TheFrog]

Ergebnis erster Test:

Das hat bei einer XML-Dokumentation meiner Methoden schon recht ordentlich funktioniert mit den Warnungen des Compilers.

Was mir noch nicht ganz klar ist:

a)
Wenn ich bei einer Methode gar keine Dokumentation erstellt habe, dann bringt mir der Compiler auch keine Meldung (so in der Art, hier fehlt die Dokumentation komplett). Kann man das noch irgendwo einstellen?

b)
Was bewirkt die Compiler-Option "generate xml documentation" noch, außer das der Compiler jetzt Warnungen auswirft? Wird hier irgendwo wirklich was erzeugt? ... und wenn ja, wo?

[Der schöne Günther]

a) Nicht dass ich wüsste. Habt ihr wirklich so einen Zwang dass JEDE (öffentliche) Methode dokumentiert sein muss? Ein Programm dass das prüft müsste ja durch die Oberklassen wandern und schauen, ob es da dokumentiert ist, also ganz schon aufwändig.

b) Dann musst du auch den "XML-Ausgabepfad" setzen ;-)

[TheFrog]

zu a)
Da hast Du Recht! Ich persönlich bin ja der Meinung, dass ein Methode selber schon mit ihrem Namen so aussagekräftig sein sollte, dass ein Dokumentation überflüssig wird, aber wie das manchmal in Projekten halt so ist :wink:

zu b)
Probiere ich aus!