Dokumentations-Helfer gesucht

[jwka61]

Ich würde gerne parallel zur Programmierung einer Objekt-Library eine Dokumentation führen, und dies "teil-manuell" machen (also ohne Dokumentor oder ähnlichen "automatischen" Werkzeugen (die nach meiner Erfahrung einiges einfach gar nicht erfassen, z.B. eval-Konstrukte oder variablen als assoziative indices).

Stelle mir folgendes vor und würde gerne wissen, ob jemand Tools kennt, die dazu brauchbar sind:

Doku von Methoden und Variablen (Properties)
Wunsch:
Während der Programmierung (manuelle) Eingabe der Variablennamen und Methodennamen in eine Liste (Name & Datei & Datei-Kurzbeschreibung, das mache ich im Moment mit einem Tabellenprogramm).

Später dann einerseits Ausgabe nach Elementen (wo wurde das Element genutzt?) und Dateien (Welche Elemente wurden in der Datei benutzt?)

Andereseits ein Check, ob die Liste noch stimmt (werden alle Elemente in der Liste auch in der notierten Datei genutzt?)

Ferner wäre es schön, wenn das Tool "Multi-User fähig" wäre, also von verschiedenen Clients aus Einträge gemacht werden können (wenn man z.B. mehrere Maschinen gleichzeitig nutzt, von allen Maschinen Einträge vornehmen).

Danke für Eure Hinweise

[Funfare]

du solltest dir mal phpDoc anschauen. Damit kannst du im PHP-Code dokumentieren und dir daraus eine Doku generieren lassen.

[tr0y]

Ich glaube bei deinem Entwicklungsverständnis brauchst du kein Tool sondern eine AI die den Code liest wie du ihn lesen würdest.

[ChristianK]

Variablennamen sollten erklären, was sie enthalten - somit selbsterklärend sein. Methodennamen sollten erklären, was sie tun - somit selbsterklärend sein. Im Code sollte man nicht dokumentieren, was man erreichen will, sondern wieso genau dieser Ansatz dazu gewählt wurde, das zu erreichen. Eine Methodendokumentation sollte beschreiben, was die Methode kann und welche Parameter wie wirken.

Ein Dokumentationstool für den Code ist somit nicht notwendig. PHPDoc kann (sollte?) man verwenden, um eine API zu dokumentieren (also theoretisch nur Interfaces).

Für eine Architekturdokumentation wählt man dann andere Formen - das ist ja ziemlich unabhängig des Codes.

[jwka61]

phpDOC setze ich schon ein, aber es liefert eben keine cross-refernces.

@tr0y: AI?

Nochmals zur Klarstellung:

Es MUSS kein auto-tool sein, es geht mir eher darum, ein System zu bekommen, mit dessen Hilfe man "auf einen Blick" feststellen kann, was wo definiert ist und was wo verwendet wird. Dass das mit einer Menge manueller Arbeit verbunden ist (sein kann), ist mir klar.

Di Auto-Funktion sehe ich eher als "Check-System", ob denbn die gepflegte Liste noch stimmt oder man z.B. etwas umbenannt (oder gelöscht) hat, ohne die Liste zu aktualisieren.

Wie gesagt, ich mache die manuelle Arbeit im Moment mit Excel, aber das scheint mir nicht das richtige Tool für sowas zu sein, zumal immer nur ein Client an einem Sheet arbeiten kann, die Zusammenführung recht aufwändig ist.

[monolith]

@tr0y: AI?

artificial intelligence, künstliche Intelligenz.

[tr0y]

phpDOC setze ich schon ein, aber es liefert eben keine cross-refernces.

@tr0y: AI?

Nochmals zur Klarstellung:

Es MUSS kein auto-tool sein, es geht mir eher darum, ein System zu bekommen, mit dessen Hilfe man "auf einen Blick" feststellen kann, was wo definiert ist und was wo verwendet wird. Dass das mit einer Menge manueller Arbeit verbunden ist (sein kann), ist mir klar.

So tief dokumentiert man nicht. Daten kapselt man nach aussen mit einem Interface ab.

Di Auto-Funktion sehe ich eher als "Check-System", ob denbn die gepflegte Liste noch stimmt oder man z.B. etwas umbenannt (oder gelöscht) hat, ohne die Liste zu aktualisieren.

Dann bau dir sowas selbst, Reflections und diverse Methoden zum Feststellen von definierten Klassen und/oder functions helfen dir dabei.

Wie gesagt, ich mache die manuelle Arbeit im Moment mit Excel, aber das scheint mir nicht das richtige Tool für sowas zu sein, zumal immer nur ein Client an einem Sheet arbeiten kann, die Zusammenführung recht aufwändig ist.

Das kann Office schon seit 2010: http://office.microsoft.com/de-de/ex...010342985.aspx