Automatische Dokomentation aus Kommentaren bei ST

Sera · 5 Mai 2010

Hallo!

Ich Suche ein Tool zur automatischen Codedokumentation aus Kommentaren in ST (B&R).
Eigentlich muss dies nichteinmal speziell für ST sein, da der Quellcode als wie in einem textfile direkt vorliegt.
Was jedoch wichtig ist, dass für den Kommentar anderst als in vielen anderen Progra Sprachen (* *) als Komentarkennzeichnung verwendet wird. Dies sollte man natürlich einstellen können.
Noch besser wäre es wenn man im Kommentar ein Start und ein Endzeichen wie /$ od sonstiges setzen kann um nur diesen Teil des Kommentars in die Doku zu übernehmen.

Kennt jemand ein Tool das hiefür geeignet wäre?

Verpolt · 5 Mai 2010

Hallo,

Wie hast du dir das denn vorgestellt?

automatischen Codedokumentation aus Kommentaren in ST

Die Sprache und Formulierung der Kommentare hängt doch sehr mit "denglisch, Slang, usw... ab.

Der Kommentar soll doch deinen Code/Vorhaben beschreiben oder veranschaulichen. Zum besseren Verständnis.

Das Tool, das du möchtest, kann doch keine Rückschlüsse auf den Code führen wenn es den Kommentar auswertet. ?!?

Sera · 5 Mai 2010

Ok vieleicht etwas missverständlich ausgedrückt

Hier mal was was ich aus Wiki kopiert hab:

Oft werden mittlerweile Dienstprogramme wie z. B. Doxygen oder Javadoc verwendet, um die Dokumentation aus dem Quelltext heraus automatisch zu erstellen. Dies geschieht mittels Kommentaren im Code, die von den Dienstprogrammen herausgesucht und zu einer Referenz zusammengestellt werden.Links zu: hier

Suche also also sowas wie Doxygen oder Javadoc aber eben für ST, da diese ST nicht unterstützen.

Thomas_v2.1 · 5 Mai 2010

Sera schrieb:
Suche also also sowas wie Doxygen oder Javadoc aber eben für ST, da diese ST nicht unterstützen.

Kannst ja mal diesen "Pascal to Doxygen" Konverter testen. ST ist von der Syntax größtenteils Pascal.

Drutbluck · 5 Mai 2010

Ich glaube, dazu muss man einfach in Teilen der Kommentierung eine bestimmte Syntax einhalten. Dann werden diese Teile von selbst durch die Tools erkannt und übernommen.

Vielleicht brauchen manche dieser Tools keine bestimmte Sprachunterstützung. Dann werden in der Werbung einfach alle bekannten Sprachen aufgezählt. ST gehört nicht dazu.

Notfalls hilft auch jede beliebige Skriptsprache, um das Tool selbst zu erstellen. So ein Tool dürfte einfacher als jedes nichttriviale SPS-Programm sein.

Sera · 6 Mai 2010

Du täuscht dich Drutblut, diese tools geben nich einfach nur den gekennzeichneten Kommentar aus, sondern analysieren wirklich den Code, und geben so Schnittstellen von Funktionen aus, erstellen Diagramme usw.
also eine wirkliche Doku (zumindest eine grobe)
Die formatierung wird über den Kommentar im Code gesteuert.
Wenn ich nur den Kommentar (bzw text zwischen bestimmten Syntax) auslesen wollte könnte ich das sogar von SPS machen lassen. Dann muss ich die Doku aber doch wieder selbst schreiben, was ich gerade vermeiden will.

bits'bytes · 7 Mai 2010

Also geht es dir jetzt hauptsächlich darum, Library Funktionen bzw. lokale Funktionen / Funkionsblöcke zu dokumentieren ?

Mit Ausnahme von C werden ja sonst in einem z.B. ST File nur 2 Funktionen angeführt (_INIT, _CYCLE).

Die halbautomatischen Doku-Systeme erstellen aber wie schon erwähnt hauptsächliche Interface-Doku zu Funktionen usw.

Das würde also dann nicht so viel Sinn machen wenns nur 2 gibt.

Und soweit ich das verstanden habe, gehts dir auch nicht um Kommentar Auszüge welche innerhalb der tasks verstreut sind, richtig ?

Vielleicht könntest du ja mal ein Stückchen Code hier reinstellen damit man sieht worauf es hinaus läuft.

Habe z.b. phpDoc im Internet gefunden, sieht interessant aus...

Sera · 7 Mai 2010

Schnittstellen der Task sind natürlich weniger von Intresse, aber Schnittstellen von Bausteinen, die Hirachie der Bausteinaufrufe, also welcher Baustein ruft welchen Baustein auf. Daraus dann ein Diagramm. Bausteine entsprechen ja Quasi Funktionen/Unterprogrammen. Natürlich würde ein solches Tool dann keine Infos haben was diese Bausteine machen. Diese Infos sollten dann aus dem Kommentar stammen. Das i-Tüpfelchen wäre natürlich wenn die Beschreibung Schnittstellenvariablen direkt aus der Beschreibung in der Definition herausgezogen würde.
Kommentarauszüge sind schon von Intresse, wenn man für nichts extra schreiben muss um so besser. Kommentarauszüge selbst auszulesen ist ja nicht sonderlich schwer, das würde auch schnell selbst in einem kleinen Programm realisierbar sein.

mal ganz einfaches Programm:

PROGRAM _CYCLIC
(* Hier beschreibung der Baustein Funktion, die in Doku landen soll*)
AsIOAccRead.enable:=lese;
AsIOAccRead.pDeviseName:=AdrDevise;
AsIOAccRead.pChannelName:=AdrChannel;
AsIOAccRead();

END_PROGRAM

Rauskommen soll dann:

Die Beschreibung des Bausteins aus dem KOmmentar bei Aufruf

Eingangsvar:

enable Datentyp Beschreibung der Funktion aus Vardef.
... .... .....
pChannelName Datentyp ....

Ausgangsvar:

Status Datentyp Beschreibung aus Vardef.
... .... ....

Baustein wird aufgerufen in Task: Cylic xyz
Baustein wird aufgerufen durch folgenden Baustein: (falls nicht direkt im Task aufgerufen)
Folgede Bausteine ruft diesr Baustein auf: xyz, abc <-- die dann als Links auf die seiten dieser Bausteinbechreibungen

Sowas in der Art.
Mal beispiele, zwar nicht optimal aber die ich auf die schnelle gefunden hab:
hier
hier
Natürlich sind die nun nicht von ST aber damit ihr besser versteht was ich meine.
Hier eine Seite von einem Solchen Tool mit Links zu diveren solchen Tools, hab sogut wie alle mal angeschaut, nichts was sich ohne allzugroßen Aufwand für ST nutzen lassen würde, soweit ich gesehen habe:
hier

Ich schätze mal ich kann das Thema erst mal abhaken denk nicht das es ein "fertiges" Tool für ST gibt. Vieleicht schreib ich doch mal eins selber, wen ich mal Zeit für haben sollte

RobiHerb · 7 Mai 2010

Frage

Das ganze liesse sich machen, wenn man das Projekt als ascii File speichern könnte.

Ich weiss aber nicht, wie man das macht? Könnte das selber auch gut gebrauchen.

Hat da jemand eine Idee?

Thomas_v2.1 · 7 Mai 2010

RobiHerb schrieb:
Das ganze liesse sich machen, wenn man das Projekt als ascii File speichern könnte.

Ich weiss aber nicht, wie man das macht? Könnte das selber auch gut gebrauchen.

Hat da jemand eine Idee?

Bei Codesys kannst du z.B. dein Projekt exportieren (mit der Option für jeden Block eine Datei zu erzeugen).

Die reine Aufrufhierarchie kann Codesys auch schon ausgeben. Klick mit rechter Maustaste auf den Baustein -> Aufrufbaum ausgeben. Leider nur ein statisches Bild mit keinerlei weiteren Möglichkeiten zum Export o.Ä.

Das Problem bei ST, dass jeder Hersteller mal wieder sein eigenes Süppchen kocht. Es gibt so viele (freie) Dokumentations-Tools für C, weil die Sprache besser standardisiert ist.

Wenn man sich rein auf die Funktions- und Schnittstellenbeschreibung beschränken würde, könnte man zumindest Codesys ST und Siemens SCL noch unter einen Hut bekommen. Die B&R Software kenne ich nicht weiter.
Die Funktionsaufrufe von ST und SCL sehen schonmal anders aus, ein entsprechender Scanner müsste das entweder automatisch erkennen können, oder mit der entsprechenden Option gestartet werden.

Will man wie gewünscht auch Aufrufhierarchien generieren, wohlmöglich noch mit Funktions-Aufrufen von AWL/FUP/GRAPH Bausteinen, oder Aufrufen von Funktionen aus geschützten Bibliotheken auf die man mit externen Tools kein Zugriff hat, ist das von vorneherein zum Scheitern verurteilt. Zumindest wäre mir persönlich der Aufwand zu groß um mit dem Ergebnis nur eine Plattform abdecken zu können.

RobiHerb · 7 Mai 2010

Guter Hinweis

Hallo, das ist doch so etwas wie ein Lösungsweg.

Ich hatte bisher noch nie reingeschaut, wie die CoDeSys Export Files aussehen. Das ist genau das, was ich suchte bisher.

Da ich das brauche, versuche ich mich einmal an der Sache. Ich schreibe gerade eine Sicherheits Anwendung, die der TÜV abnehmen muss, es wird also so etwas ausführliches an Dokumentation nötig werden.

Problem sind natürlich die LIBS, die man nicht selber erstellt hat.

bits'bytes · 8 Mai 2010

So würde ich mir das wünschen ...

Ausgehend von der Physical View müssten die verwendeten Funktionen aufgelistet und beschrieben werden.

Dazu könnte der Kommentar vor der Funktionsdeklaration verwendet werden. Ob es sich jetzt um Funktionen oder FUB's handelt sollte dabei keine Rolle spielen.

D.h Jeder Task in der Physical View würde einen eigenen Strang an Funktionsaufrufen erzeugen.

Dieser könnte in den lokalen Libraries und globalen User Libraries beliebig tief gehen, jedoch würde sofort beim ersten Eintauchen in die B&R System Libraries stoppen.

Bleibt für mich die Frage, was mir das wirklich bringt ? Meine Hauptprogrammierung erfolgt ja im TASK, wobei natürlich wo es Sinn macht auf Funktionen zurückgegriffen wird.

Man müsste auf jeden Fall noch überlegen wie man beliebige Doku-Snippets aus dem Task in das Dokument reinbekommt. Dann könnte vielleicht ein zufriedenstellendes Ergebnis rauskommen ... ?

Sera · 10 Mai 2010

Also die Hirachie der Bausteinaufrufe soll ja nur ein Teil der Doku sein.
Die im Task ausprogramierten Dinge können ja über Kommentar einfach dokumentiert werden. In diesem könnten dann Schlüsselzeichen enthalten sein, die dem Tool sagen wie es den entsprechenden Kommentar interpretieren soll.
So könnte man bereits im Code die Struktur der Dokuteils des Tasks bestimmen.

Sprich für Überschriften, Unterüberschriften , einfachen Text, Diagramme... seperate Schlüsselworte, die das dem Dokutool mitteilen wie es die Infos zu Interpretieren hat.

Das sollte prizipiell nicht sooo schwierig sein. Hierzu ist nur (zumindest bei B&R) ein txt file zu analysieren ( auch wenn die endung anderst ist sind es textfiles). Das Tool müsste hier nur nach bestimmten Zeichen suchen und den daran anschließenden text entsprechend der Funktion behandeln, im einfachsten fall nur in die Doku kopieren.
Es gibt zwar ( nun ma nur auf B&R bezogen) noch Dinge zu klären wie: Welche Programme sind welchen Task zugeordnet, also wo kann ich diese Infos auslesen.
Aber diese Infos findet man sicher irgent wo, schließlich muss AS die auch haben.

Prizipiell ist das ganze schon realisierbar, nur realisiert werden müsste es wohl erst noch, weil geben tuts das nach meinem Kenntnissstand nicht. Der Thread war ja für gedacht herauszufinden ob jemand sowas schon mal geschrieben hat oder zumindest weiß wo es sowas gibt. Freut mich aber das dieses Thema nicht nur mich beschäftigt.

bits'bytes · 10 Mai 2010

Sera schrieb:
... Sprich für Überschriften, Unterüberschriften , einfachen Text, Diagramme... seperate Schlüsselworte, die das dem Dokutool mitteilen wie es die Infos zu Interpretieren hat.

Das könnte natürlich die Auswirkung haben dass der Code an sich unleserlich wird, wenn zu viele komische Doku-Abschnitte eingepflegt werden.

Sera schrieb:
Es gibt zwar ( nun ma nur auf B&R bezogen) noch Dinge zu klären wie: Welche Programme sind welchen Task zugeordnet, also wo kann ich diese Infos auslesen.
Aber diese Infos findet man sicher irgent wo, schließlich muss AS die auch haben.

Diese Infos sind sehr leicht zugänglich aus div. XML Dateien.

--
Ich gebe dir recht, realisierbar wäre es schon, aber als kleines Helpertool kann dass dann nicht mehr beschrieben werden.

Wäre schön wenn das AS hier einige Features implementieren würde.
- Callers Graph usw.... wie aus Visual Studio bekannt.
- Funktion Header Template, ähnlich div. Tabellen z.B. Variablen Liste,
wo eben nur mehr die Beschreibung zu den Parametern eingegeben werden muss
- ....

Ich muss allerdings gestehen dass ich die ganzen Doku-Möglichkeiten des AS auch nicht zu 100% kenne

Sera · 10 Mai 2010

Das könnte natürlich die Auswirkung haben dass der Code an sich unleserlich wird, wenn zu viele komische Doku-Abschnitte eingepflegt werden.

da würde sich ne möglichkeit finden lassen denk ich

Diese Infos sind sehr leicht zugänglich aus div. XML Dateien.

Kann gut sein, hab mich nicht mit beschäftigt

aber als kleines Helpertool kann dass dann nicht mehr beschrieben

Muss ja nicht alles auf einmal sein, man könnte ja mit einem Teil mal anfangen

Vieleicht ließt das ja ein gelangweilter Programierer und schreibt was zu

Gelangweilt kann ich im Moment nicht nennen

Wenn jemand damit anfängt, oder was zu schreibt, gerne bei mir melden, vlt find ich ja etwas zeit zwischen rein um mich zu beteiligen.

Wenn was bei rauskommt kann man das ja event an BR verkaufen

RobiHerb · 10 Juni 2010

Ein erster Prototyp

Wie ich bereits vor einigen Tagen hier gesagt habe, versuche ich mich einmal an so einem Tool.

Wie immer, wenn man so etwas macht, passt es zu den eigenen Sachen aber sonst eventuell nicht so gut. Ihr könnt mir Beispiel Programme als EXPORT Files senden, damit ich auch daran testen kann. Ich benutze hier CoDeSys 2.x, an Siemens wäre ich natürlich auch interessiert.

Kommentare und Wünsche willkommen.

Ich lege mal zum aktuellen Stand einen Screenshot bei.

bbking · 11 Januar 2012

@RobiHerb: wie sieht es mit Deinem Tool aus? Genau so etwas würde ich derzeit suchen...müsste ein kleines TwinCAT-Projekt in ST dokumentieren....

Danke

e6o5 · 6 Februar 2012

Robodoc (http://rfsber.home.xs4all.nl/Robo/) benutze ich für eine einfache Dokumentationsgenerierung mit Beckhoff TwinCat aus dem Quellcode. Das Tool unterstütz jede Sprache , die Kommentare erlaubt.

RobiHerb · 6 Februar 2012

bbking schrieb:
@RobiHerb: wie sieht es mit Deinem Tool aus? Genau so etwas würde ich derzeit suchen...müsste ein kleines TwinCAT-Projekt in ST dokumentieren....

Danke

Wer daran interessiert ist, sollte sich per eMail oder PN melden.

Automatische Dokomentation aus Kommentaren bei ST

Level-1

Level-1

Level-1

Level-1

Level-1

Level-1

Level-1

Level-1

Level-2

Level-1

Level-2

Level-1

Level-1

Level-1

Level-1

Level-2

Anhänge

Level-1

Level-1

Level-2

Similar threads

Wir schützen deine Privatsphäre