[OT] PHP-Dokumentationstool

Liebe Newsreader und deren Besitzer!

Letztens gabs hier ne Diskusion zu Tools mit denen sich PHP-Dateien
automatisch dokumentieren lassen sollen.

Das Ganze hat mich angeregt mal über diese Problematik nachzudenken.

Irgendwo in einer IDE (ich glaub es war Netbeans) hab ich mal eine sehr
nette Umsetzung dieses Vorhabens für JAVA gesehen. Da wird die
Sourcedatei komplett analysiert und alle Klassen sowie Methoden +
Krimkrams lokalisiert, analysiert und mit Nutzerinteraktion dokumentiert.

Selbiges wär ein Superding wenn man das mal für PHP umsetzen könnte.

Da es sich hierbai aber nicht um ne Wochenendarbeit handelt und ich
allein da wohl nen Jahr brauchen würde um das respektabel umzusetzen
frag ich einfach hier mal in die Runde wer das Lust zu hätte das umzusetzen.

Bevorzugte Sprache waere eine beliebige aus dotNET (C# z.B.) oder C++
bloss java nicht unbedingt. Java hab ich zuletzt vor 4 Jahren genutzt
und müste wohl zu viel Neulernen.

Dank Mono waere das bei z.B. C# auch auf Unixen nutzbar.

Wer Interesse daran hat kann sich gern bei mir oder hier melden.
Tools für PHP-Programmierer gibt ja nun eh nicht wie Sand am Meer!

Vorweg! Es soll ein OS-Projekt werden.

Bei Mails bitte einfach das news-noreply am Anfang meiner Mailadresse
durch news-reply ersetzen

MfG, Ulf

Re: [OT] PHP-Dokumentationstool

Ulf Kadner wrote:

> Bevorzugte Sprache waere eine beliebige aus dotNET (C# z.B.) oder C++
> bloss java nicht unbedingt. Java hab ich zuletzt vor 4 Jahren genutzt
> und müste wohl zu viel Neulernen.

Oder halt Delphi, was mir wohl am allerliebsten wäre.

MfG, Ulf

Re: [OT] PHP-Dokumentationstool

Hallo Ulf,

Ulf Kadner schrieb:
> Letztens gabs hier ne Diskusion zu Tools mit denen sich PHP-Dateien
> automatisch dokumentieren lassen sollen.
>
> Das Ganze hat mich angeregt mal über diese Problematik nachzudenken.
>
> Irgendwo in einer IDE (ich glaub es war Netbeans) hab ich mal eine sehr
> nette Umsetzung dieses Vorhabens für JAVA gesehen. Da wird die
> Sourcedatei komplett analysiert und alle Klassen sowie Methoden +
> Krimkrams lokalisiert, analysiert und mit Nutzerinteraktion dokumentiert.
>
> Selbiges wär ein Superding wenn man das mal für PHP umsetzen könnte.

....

> Bevorzugte Sprache waere eine beliebige aus dotNET (C# z.B.) oder C++
> bloss java nicht unbedingt. Java hab ich zuletzt vor 4 Jahren genutzt
> und müste wohl zu viel Neulernen.

Interessante Idee. Eine Alternative wäre, sowas in PHP umzusetzen und
gleich in PhpDocumentor einzubauen. Der Vorteil wäre, dass alles rund
ums Parsen des Quellcodes schon gelöst wäre. Gibt's in PHP 5 nicht eine
Reflection-API?

Nutzerinteraktion wäre dann zwar weniger vorhanden, ich bezweifle aber,
ob sich der Aufwand für sowas lohnt. Ich denke, wichtiger wäre es, dass
so ein Werkzeug ein komplettes Projekt analysieren kann und die Stellen
ausspucken kann, an denen die Dokumentation nicht mehr aktuell ist, also
beispielsweise Parameter fehlen.

Grüße
Christian



--
-------------------------------------
http://www.netzologie.de
Email: vorname.nachname (bei) gmx.net

Re: [OT] PHP-Dokumentationstool

Ulf Kadner schrieb:

> Letztens gabs hier ne Diskusion zu Tools mit denen sich PHP-Dateien
> automatisch dokumentieren lassen sollen.
>
> Das Ganze hat mich angeregt mal über diese Problematik nachzudenken.
>
> Irgendwo in einer IDE (ich glaub es war Netbeans) hab ich mal eine sehr
> nette Umsetzung dieses Vorhabens für JAVA gesehen. Da wird die
> Sourcedatei komplett analysiert und alle Klassen sowie Methoden +
> Krimkrams lokalisiert, analysiert und mit Nutzerinteraktion dokumentiert.

Was bedeutet Nutzerinteraktion?

Ich habe gestern erst herausgefunden, dass man mit z.b. Doxygen ganz
wunderbare Dokumentationen auf Grund von Inline-Dokumentationen
erstellen kann. Das erspart mir viel Arbeit.

> Bevorzugte Sprache waere eine beliebige aus dotNET (C# z.B.) oder C++
> bloss java nicht unbedingt. Java hab ich zuletzt vor 4 Jahren genutzt
> und müste wohl zu viel Neulernen.

Ich kann es mir nicht verkneifen, dir von Java abzuraten... -.-

> Wer Interesse daran hat kann sich gern bei mir oder hier melden.
> Tools für PHP-Programmierer gibt ja nun eh nicht wie Sand am Meer!

Das ist allerdings wahr. Mir fallen da auf Schlag noch diverse Dinge
ein, die mir fehlen. Allerding gibt es auch viele Implementationen als
PHP-Script, die mir fehlen.

Im übrigen bastel ich gerade als Abschlußprojektprüfung an einem
PHP-Script, welches bestehende PHP-Projekte auf Funktionen, Klassen und
Methoden hin untersucht und durch einen einfache Beschreibungssprache
generisch testet. Was hälst du von dieser Idee? Da Unittest bei PHP ja
aus nicht nachvollziehbaren Gründen unbeliebt sind, wäre das eine
Möglichkeit, bestehende Projekte nachträglich in eine testgestütze
Entwicklung zu übertragen.

Gruß,
Torsten

Re: [OT] PHP-Dokumentationstool

Christian Smietana wrote:

> Interessante Idee.

Hallo Christian!

> Eine Alternative wäre, sowas in PHP umzusetzen und
> gleich in PhpDocumentor einzubauen.

Genau das wollte ich gern vermeiden! (es in PHP umzusetzen)

Da muss man erst wieder ein passendes Webinterface zusammenschrauben,
was ansich schon wesentlich mehr Zeit beansprucht als die Entwicklung
eines GUIs für normale Programme. Um nur annähernd die Möglichkeiten
eines normalen Programmes mit Bedienoberfläche und allen
Interaktions-Möglichkeiten die z.B. ein Windows-Form bieten in PHP resp.
JS umzusetzen ist schon ein ziemlich grosser Aufwand nötig. Im Endeffekt
wohl das was man neuerdings Web 2.0 nennt. Meine Auffassung mag hier
evtl. von der des Einen oder Anderen differieren.

Wieterhin würde ich PHP als zu langsam einstufen um gleich ganze
Projekte zu verarbeiten.

Mir fallen sicher nocht mehr Argumente gegen die PHP-Nutzung ein. ;-)

Aber um noch mal auf PHP-Documentor zurück zu kommen. Dessen Syntax
würde ich hier als die Basis allen Schaffens definieren.
Will heissen: Darauf sollte das Tool aufbauen.

> ums Parsen des Quellcodes schon gelöst wäre. Gibt's in PHP 5 nicht eine
> Reflection-API?

Ja. Die kann sogar PHP-Kommentare zu Klassen und Funktionen
erkennen/finden. Aber das ist halt nicht alles. Reflection hat auch
Nachteile. An Erster Stelle wohl wieder die Geschwindigkeit, die durch
Reflection noch mal um durchnittlich den Faktor 1.5 reduziert wird. (Hab
ich mal vor nem Jahr getestet)

> Nutzerinteraktion wäre dann zwar weniger vorhanden, ich bezweifle aber,
> ob sich der Aufwand für sowas lohnt.

Warum nicht? Genau das halte ich für einen sehr wichtigen Punkt! Schau
mal auf erfolgreiche Software-Projekte. Meist sind das (natürlich
abhängig vom Anliegen) Projekte, die dem Nutzer ein intuitives Interface
bereit stellen, welches ohne grosse Umschweife genau das macht was man
erwartet. Einem Arbeit abnehmen, Daten gut strukturiert darstellen,
leichte Bearbeitung, schnelles Handling usw.

> Ich denke, wichtiger wäre es, dass
> so ein Werkzeug ein komplettes Projekt analysieren kann und die Stellen

Logisch! Projekte und das Handling derer sind ein wichtiger Bestandteil
eines solchen Tools. Die Implementierung+Ähnliches sind dann halt
Details über die man sich noch im klaren werden muss.

> ausspucken kann, an denen die Dokumentation nicht mehr aktuell ist,

Wie meinst Du das? Woran erkennt man, das ein Dokumentationsblock nicht
mehr aktuell ist? Na der Spezifikation von PHP-Doc ist sowas nicht
möglich. Da muste entweder spezielle Tags nutzen oder alles über CVS
o.ä. laufen lassen.

> beispielsweise Parameter fehlen.

Das hat aber nicht mit aktualität sondern eher mit unvollständigkeit zu
tun? Derartige Prüfungen sind natürlich Pflichtimplementierungen.

Die Signatur einer Funktion sollte sich niemals ändern.

MfG und Danke für das Du Dir darüber Gedanken machst, Ulf

Re: [OT] PHP-Dokumentationstool

Ulf Kadner schrieb:

> Die Signatur einer Funktion sollte sich niemals ändern.

Hmm... Und wie implementierts du in PHP nachträglich eine Überladung
einer Methode? Ich mach das meist so, dass ich den Parameter als
optionalen hinzufüge.

gruss, heli

Re: [OT] PHP-Dokumentationstool

Torsten Zühlsdorff wrote:

> Was bedeutet Nutzerinteraktion?

Ich stelle mir das im Umrissen etwa so vor:

- Nutzer wählt ein Projekt oder eine PHP-Datei aus die er
ver/bearbeiten will
- Programm zeigt eine Liste aller Dateien mit den darin enthaltenen
Funktionen, Klassen, Methoden usw. usf an.
- Aus der Anzeige dieser wird ersichtlich welche noch undokumentiert,
unvollständig oder falsch dokumentiert sind.
- Klickt der Nutzer jetzt z.B. auf eine Methode wird ein Formular
angezeigt, das dem Nutzer alle notwendigen Kommentardaten ohne
spezielle Formatierungsansprüche eingeben läst und auch, soweit
es möglich ist, bereits verschiede Daten selbst ermittelt.
(z.B. Ausnahmen, Rückgabewerte, Parameter etc.)
- Wenn alles fertig kommentiert ist kann die Dokumentation über
PHP-Dokumentor o.ä., über ein einfaches Interface generiert werden.

> Ich habe gestern erst herausgefunden, dass man mit z.b. Doxygen ganz
> wunderbare Dokumentationen auf Grund von Inline-Dokumentationen
> erstellen kann. Das erspart mir viel Arbeit.

Ja Doxygen kenn ich auch. Aber das ist mir zu wenig.

> Ich kann es mir nicht verkneifen, dir von Java abzuraten... -.-

:-x

> Im übrigen bastel ich gerade als Abschlußprojektprüfung an einem
> PHP-Script, welches bestehende PHP-Projekte auf Funktionen, Klassen und
> Methoden hin untersucht und durch einen einfache Beschreibungssprache
> generisch testet.

Warum in PHP? Du beherschst doch auch einige andere Sprachen. Ich finde
man sollte sich da irgendwo Grenzen setzen wo man besser PHP mal PHP
sein läst und auf andere Sprachen wechselt. OK Leute die nur PHP
beherrschen können das nicht. Aber wenns sichs vermeiden läst! ;-)

> Was hälst du von dieser Idee? Da Unittest bei PHP ja
> aus nicht nachvollziehbaren Gründen unbeliebt sind,

Ich mag die auch nicht. Ich empfinde den Aufwand, den man zum erstellen
der Tests betreiben muss als unangemessen. Das Tool wird sicherlich
Erfolg haben wenn es denn alles komfortabel beschleunigen kann.

MfG, Ulf

Danke für Deine grauen Zellen! ;-)

Re: [OT] PHP-Dokumentationstool

Helmut Chang schrieb:
> Ulf Kadner schrieb:
>
>> Die Signatur einer Funktion sollte sich niemals ändern.
>
> Hmm... Und wie implementierts du in PHP nachträglich eine Überladung
> einer Methode? Ich mach das meist so, dass ich den Parameter als
> optionalen hinzufüge.

Eine Überladung würde aber bedeuten, dass du eine Methode mit bereits
vorhandenen Methodennamen, aber anderen Parametern verwendest.

Muß ich gleich mal ausprobieren, ob das überhaupt geht ^^

Gruß,
Torsten

Re: [OT] PHP-Dokumentationstool

Ulf Kadner schrieb:

>> Was bedeutet Nutzerinteraktion?
>
> Ich stelle mir das im Umrissen etwa so vor:
>
> - Nutzer wählt ein Projekt oder eine PHP-Datei aus die er
> ver/bearbeiten will
> - Programm zeigt eine Liste aller Dateien mit den darin enthaltenen
> Funktionen, Klassen, Methoden usw. usf an.

Soweit klar ;)

> - Aus der Anzeige dieser wird ersichtlich welche noch undokumentiert,
> unvollständig oder falsch dokumentiert sind.

Woran wird das erkannt? Inline-Dokumentation? Meta-Daten?

> - Klickt der Nutzer jetzt z.B. auf eine Methode wird ein Formular
> angezeigt, das dem Nutzer alle notwendigen Kommentardaten ohne
> spezielle Formatierungsansprüche eingeben läst und auch, soweit
> es möglich ist, bereits verschiede Daten selbst ermittelt.
> (z.B. Ausnahmen, Rückgabewerte, Parameter etc.)

Also Zielgruppe: Entwickler?

> - Wenn alles fertig kommentiert ist kann die Dokumentation über
> PHP-Dokumentor o.ä., über ein einfaches Interface generiert werden.

Was passiert mit den Daten, die eingegeben wurden? Werden diese dem Code
hinzugefügt? Existieren sie nur in der Dokumentation? Werden sie als
Meta-Daten persistiert?

>> Im übrigen bastel ich gerade als Abschlußprojektprüfung an einem
>> PHP-Script, welches bestehende PHP-Projekte auf Funktionen, Klassen und
>> Methoden hin untersucht und durch einen einfache Beschreibungssprache
>> generisch testet.
>
> Warum in PHP?

Das hat einen relativ pragmatischen Grund: In letzter Zeit sind einige
A-Kunden auf die Idee gekommen, dass man durch wildes oder gar
ungewolltetes Updaten von Applikationen und Scripten durchaus Schaden
anrichten kann.
Daher wollen sie eine Möglichkeit, nach jedem Update diverse Testläufe
über ein Script ihrer Wahl laufen lassen, um zu sehen, ob noch alles
funktioniert.
Da ich keine Lust hatte, mich um diverse Portierungen zu kümmern und
schon gar keine Lust hatte, mich mit der rudimentären Java-Syntax
herumzuschlagen, habe ich mich kurzerhand für PHP entschieden.
Vereinfacht desweiteren die generische Abarbeitung ungemein.

> Du beherschst doch auch einige andere Sprachen. Ich finde
> man sollte sich da irgendwo Grenzen setzen wo man besser PHP mal PHP
> sein läst und auf andere Sprachen wechselt. OK Leute die nur PHP
> beherrschen können das nicht. Aber wenns sichs vermeiden läst! ;-)

Als Programmierer sollte einem die Sprache doch total egal sein ;) In
letzter Zeit habe ich PHP (größer 5.1 ;) ) aber irgendwie lieb gewonnen,
da man erstaunlich viele Konzepte aus vielen verschiedenen Sprachen
problemlos übernehmen kann. Diese Programmierfreiheit wird nur noch
durch LISP getoppt. Aber das mag niemand in der Firma sehen und daher
bleibt mir auch nur wenig Zeit, mich damit zu beschäftigen. PHP ist
quasi mein Trost durch den Arbeitstag :P

Aber da ich es gerade erwähne: Mir fehlt ein richtig guter PHP-Editor ;)
Die Debugging-Methoden in z.b. SLIME ist bisher unerreicht. Wer soetwas
kennt: Bitte melden. Ich zahle auch ;)

>> Was hälst du von dieser Idee? Da Unittest bei PHP ja
>> aus nicht nachvollziehbaren Gründen unbeliebt sind,
>
> Ich mag die auch nicht. Ich empfinde den Aufwand, den man zum erstellen
> der Tests betreiben muss als unangemessen. Das Tool wird sicherlich
> Erfolg haben wenn es denn alles komfortabel beschleunigen kann.

Dabei sollte man nicht vergessen, dass auch das nachträgliche Anpassen
oder gar das Debuggen der Tests enorme Mengen an Zeit verschleudert.
Wenn ich sicher sein könnte, dass niemand dieses Posting jemals liest,
würde ich UnitTests als "totale Verschwendung und Unfug" bezeichnen ;)

> Danke für Deine grauen Zellen! ;-)

Dafür nicht. Dinge zu erfinden gehört zu meinen liebsten
Beschäftigungen. Falls du mal wieder was zu besprechen und erfinden
hast, kannst du dich auch direkt an thorny@meisterderspiele.de wenden.

Gruß,
Torsten

Re: [OT] PHP-Dokumentationstool

Torsten Zühlsdorff schrieb:

>> Hmm... Und wie implementierts du in PHP nachträglich eine Überladung
>> einer Methode? Ich mach das meist so, dass ich den Parameter als
>> optionalen hinzufüge.
>
> Eine Überladung würde aber bedeuten, dass du eine Methode mit bereits
> vorhandenen Methodennamen, aber anderen Parametern verwendest.
>
> Muß ich gleich mal ausprobieren, ob das überhaupt geht ^^

Nein. Geht in PHP nicht. Deshalb schrieb ich obiges. Es ist quasi eine
Simulation einer Überladung.

gruss, heli

Re: [OT] PHP-Dokumentationstool

Helmut Chang schrieb:
> Torsten Zühlsdorff schrieb:
>
>>> Hmm... Und wie implementierts du in PHP nachträglich eine Überladung
>>> einer Methode? Ich mach das meist so, dass ich den Parameter als
>>> optionalen hinzufüge.
>>
>> Eine Überladung würde aber bedeuten, dass du eine Methode mit bereits
>> vorhandenen Methodennamen, aber anderen Parametern verwendest.
>>
>> Muß ich gleich mal ausprobieren, ob das überhaupt geht ^^
>
> Nein. Geht in PHP nicht. Deshalb schrieb ich obiges. Es ist quasi eine
> Simulation einer Überladung.

Beim herumprobieren habe ich nur die Funktion overload gefunden:
http://www.php.net/overload

Allerdings überzeugt sie mich jetzt nicht wirklich. Anderseits ist
Überladung leicht zu umgehen.

Gruß,
Torsten

Re: [OT] PHP-Dokumentationstool

Torsten Zühlsdorff wrote:

> Ulf Kadner schrieb:
>>- Aus der Anzeige dieser wird ersichtlich welche noch undokumentiert,
>> unvollständig oder falsch dokumentiert sind.
>
> Woran wird das erkannt? Inline-Dokumentation? Meta-Daten?

Naja laut PHP-Dokumentor existieren verschiedene Elemente die
dokumentierbar sind. Diese (die Kommentare zu den Elementen) werden
durch ihre Position, Ihr Format und Ihren Inhalt definiert. Das sollte
bereits ausreichen.

> Also Zielgruppe: Entwickler?

Auf jeden Fall! ja

>>- Wenn alles fertig kommentiert ist kann die Dokumentation über
>> PHP-Dokumentor o.ä., über ein einfaches Interface generiert werden.
>
> Was passiert mit den Daten, die eingegeben wurden? Werden diese dem Code
> hinzugefügt? Existieren sie nur in der Dokumentation? Werden sie als
> Meta-Daten persistiert?

Das weiss ich auch noch nicht so hundert-prozentig.

Eine Möglich keit wäre wohl sicherlich einfach alles in den PHP-Source
so einzufügen das daraus einfachst eine Dokumentation wahlweise in HTML,
PDF oder CHM generiert werden kann.

Sinnvoll könnte auch sein diese Daten z.B. in XML zwischenzuspeichern,
so wies z.B. Visual-Studio macht und die Codedatei(en) komplett
undokumentiert zu belassen. Aber dann wäre das schon wieder proprietär
was wohl eher suboptimal ist.

> Das hat einen relativ pragmatischen Grund: In letzter Zeit sind einige
> A-Kunden auf die Idee gekommen, dass man durch wildes oder gar
> ungewolltetes Updaten von Applikationen und Scripten durchaus Schaden
> anrichten kann.

Naja die Gefahr besteht immer. Test decken ja für gewöhnlich nur
bekannte Problembereiche ab.

> Daher wollen sie eine Möglichkeit, nach jedem Update diverse Testläufe
> über ein Script ihrer Wahl laufen lassen, um zu sehen, ob noch alles
> funktioniert.

Also kein Entwickler-Tool... Da würde ich noch vielmehr auf PHP
verzichten wollen. YMMV

> Da ich keine Lust hatte, mich um diverse Portierungen zu kümmern und
> schon gar keine Lust hatte, mich mit der rudimentären Java-Syntax
> herumzuschlagen, habe ich mich kurzerhand für PHP entschieden.

Die frage ist halt nur ob der Einfachere Weg auch des Bessere ist.

> Als Programmierer sollte einem die Sprache doch total egal sein ;)

hehe :-) soooo isses ja nun auch nicht ;-)

> letzter Zeit habe ich PHP (größer 5.1 ;) ) aber irgendwie lieb gewonnen,
> da man erstaunlich viele Konzepte aus vielen verschiedenen Sprachen
> problemlos übernehmen kann.

Keine Frage! PHP mit seinen neuen Features ist schon ein guter
Fortschritt. Was mich nen bischen ärgert ist, das PHP beim Sprung zu
Version 6 kaum nennenswerte neue Features bietet. Aber andererseits hab
ich kein Recht dazu mir sowas anzumaßen, da ich noch nie zur
PHP-Entwicklung direkt beigetragen habe. Aber ich wollts nur mal gesagt
haben ;-)

> Diese Programmierfreiheit wird nur noch
> durch LISP getoppt.

Ich hab zwar auch schon (ge)LISP(elt) aber da ziehe ich wiederum PHP
vor. LISP erfordert immer 100% Aufmerksamkeit. Aber manchmal will man
das 60% auch ausreichen. Ich hoffe das ist verständlich ausgedrückt.

> Aber das mag niemand in der Firma sehen und daher
> bleibt mir auch nur wenig Zeit, mich damit zu beschäftigen. PHP ist
> quasi mein Trost durch den Arbeitstag :P

:-)

Das ist bei mir Delphi. Ich liebe Delphi! platonisch natürlich ;-)

> Aber da ich es gerade erwähne: Mir fehlt ein richtig guter PHP-Editor ;)

Das hatte ich auch mal vor so nen Teil zu coden. Da mir keiner geholfen
hat hab ich irgendwann aufgegeben. Das klingt zwar jetzt wie "Keiner
spielt mit mir" aber so isses nicht gemeint! :-x

> Dabei sollte man nicht vergessen, dass auch das nachträgliche Anpassen
> oder gar das Debuggen der Tests enorme Mengen an Zeit verschleudert.
> Wenn ich sicher sein könnte, dass niemand dieses Posting jemals liest,
> würde ich UnitTests als "totale Verschwendung und Unfug" bezeichnen ;)

"Notwendiger Unfug" würde ich da sagen.

> Dafür nicht. Dinge zu erfinden gehört zu meinen liebsten
> Beschäftigungen. Falls du mal wieder was zu besprechen und erfinden
> hast, kannst du dich auch direkt an thorny@meisterderspiele.de wenden.

OK! :-)

MfG, Ulf

Re: [OT] PHP-Dokumentationstool

Helmut Chang wrote:

> Ulf Kadner schrieb:
>> Die Signatur einer Funktion sollte sich niemals ändern.
>
> Hmm... Und wie implementierts du in PHP nachträglich eine Überladung
> einer Methode?

Was ich damit ausdrücken wollte ist, das Änderungen in der Signatur
einer Methode/Funktion kein guter Stil sind.

Der Nutzer der Methode wirds Dir danken wenn diese konstant bleibt. Jede
Änderung kann tiefgreifende Anwendungsübergreifende Änderungen bewirken.

Hier nehmen wohl Überladungen eine Sonderstellung ein. Eine Signatur
ändert sich ja in PHP nicht zwangsmässig direkt, wenn man Überladung
nutzt. Damit wird diese nur erweitert und kann immernoch wie vorher
genutzt werden, solange Zusätze optional bleiben.

Wenn wirklich die notwendigkeit besteht eine Methode mit anderen
Parametern zu definieren, so sollte man diese auch anders nennen.

MfG, Ulf

Re: [OT] PHP-Dokumentationstool

Ulf Kadner schrieb:

>> Ulf Kadner schrieb:
>>
>>> - Aus der Anzeige dieser wird ersichtlich welche noch undokumentiert,
>>> unvollständig oder falsch dokumentiert sind.
>>
>> Woran wird das erkannt? Inline-Dokumentation? Meta-Daten?
>
> Naja laut PHP-Dokumentor existieren verschiedene Elemente die
> dokumentierbar sind. Diese (die Kommentare zu den Elementen) werden
> durch ihre Position, Ihr Format und Ihren Inhalt definiert. Das sollte
> bereits ausreichen.

Das würde aber auch zu dem Problem führen, dass Elemente, die in
unbekannten Formen dokumentiert sind, nicht als dokumentiert erkannt
werden. Aber ich befürchte, dass es als Konsens notwendig ist.

>>> - Wenn alles fertig kommentiert ist kann die Dokumentation über
>>> PHP-Dokumentor o.ä., über ein einfaches Interface generiert werden.
>>
>> Was passiert mit den Daten, die eingegeben wurden? Werden diese dem Code
>> hinzugefügt? Existieren sie nur in der Dokumentation? Werden sie als
>> Meta-Daten persistiert?
>
> Das weiss ich auch noch nicht so hundert-prozentig.
>
> Eine Möglichkeit wäre wohl sicherlich einfach alles in den PHP-Source
> so einzufügen das daraus einfachst eine Dokumentation wahlweise in HTML,
> PDF oder CHM generiert werden kann.

Was allerdings die Manipulation der Source-Dateien verlangt und
dementsprechende Sicherheitsmaßnahmen notwendig macht.

(Was mir gerade in den Sinn kommt: Gibt es eigentlich ein Programm, dass
PAPs an Hand von Inline-Dokumentationen erstellt? :P :P :P)

> Sinnvoll könnte auch sein diese Daten z.B. in XML zwischenzuspeichern,
> so wies z.B. Visual-Studio macht und die Codedatei(en) komplett
> undokumentiert zu belassen. Aber dann wäre das schon wieder proprietär
> was wohl eher suboptimal ist.

Was wäre so schlimm daran, ein Format zu wählen, das dem Programm
zugehörig ist? Da es offen gelegt ist, sollte es doch leicht nutzbar sein.
Natürlich würde das eine Spezialisierung schaffen, aber das wäre besser
(meiner Meinung nach) besser, als die Source-Dateien zu manipulieren.

>> Das hat einen relativ pragmatischen Grund: In letzter Zeit sind einige
>> A-Kunden auf die Idee gekommen, dass man durch wildes oder gar
>> ungewolltetes Updaten von Applikationen und Scripten durchaus Schaden
>> anrichten kann.
>
> Naja die Gefahr besteht immer. Test decken ja für gewöhnlich nur
> bekannte Problembereiche ab.

Kommt auf die Tests an. Ich halte mich hier an das Sprichwort: "Es
funktioniert genau das, was getestet wurde".
Das Problem ist ja auch, dass viele Fehler über lange Zeit unentdeckt
bleiben. Das beliebteste Beispiel sind fehlerhaft implementierte
Binärsuchen, die vergaßen, dass man auch mehr als 2^39 Datensätze
durchsuchen kann. Damals wurde Integer als Standarddatenwert verwenden -
es war undenkbar, dass es so viel zu suchen gibt.

>> Daher wollen sie eine Möglichkeit, nach jedem Update diverse Testläufe
>> über ein Script ihrer Wahl laufen lassen, um zu sehen, ob noch alles
>> funktioniert.
>
> Also kein Entwickler-Tool... Da würde ich noch vielmehr auf PHP
> verzichten wollen. YMMV

Jein. Es wird von Entwicklern benutzt werden und
Administratoren/PMs/Betreiber/$VIPs lassen sich durch das Ergebnis
be(un)ruhigen.

Entwicklern soll es eine stabilere Entwicklung und schnellere Wartung
ermöglichen, da man für jedes Projekt verschiedene Testprofile erstellen
und persistieren kann. Durch die stark vereinfachte Beschreibungssprache
verschwendet man keine Zeit in die Entwicklung und Wartung von Testcodes.

Administratoren können ein solches Testprofil vom Tool automatisiert
aufrufen lassen und so zu jedem beliebigen Zeitpunkt die Korrektheit des
Systems überprüfen. Müßte man bei Unittests unterschiedlichste Testfälle
und Unmengen an Testdateien verwalten, updaten usw. reicht es, eine
XML-Datei zu erneuern und sich das Ergebnis anzuschauen.

PMs und anderen VIPs sollte bei Gelegenheit mal eine HTML-Seite erzeugt
werden können, welche sie über die korrekte Funktionsweise der
Applikation informiert.

Natürlich besteht die Gefahr, dass die Ergebnisse von
Entwicklungsmaschine und Live-Betrieb abweichen. Aber wenn man intensiv
PHP programmiert, berücksichtigt man irgendwo sogar noch die größe des
Festplatten Caches und das Dateisystem bei der Benutzung von Sessions.
Als mir aufgefallen ist, dass ich soetwas beachte, habe ich erstmal
Urlaub genommen :P

>> Da ich keine Lust hatte, mich um diverse Portierungen zu kümmern und
>> schon gar keine Lust hatte, mich mit der rudimentären Java-Syntax
>> herumzuschlagen, habe ich mich kurzerhand für PHP entschieden.
>
> Die frage ist halt nur ob der Einfachere Weg auch des Bessere ist.

In dem Fall der Konsens zwischen einfach und besser. Die
"Portierbarkeit" von Java ist eine nette Marketingstrategie, aber wenn
die Anzahl der Unterstützen OSes gegen die derzeitigen ca. 470
bestehenden Betriebssysteme hält, wird schnell klar, warum es Unsinn ist.
Außerdem frustriert mich Java mit seinen vielen Einschränkungen und der
viel zu geringen Möglichkeit dem generischen Paradigma zu fröhnen.
Ruby oder Python oder andere neure Sprachen wären noch gute Alternativen
gewesen, aber leider sind sie zu wenig verbreitet und es ist schwer den
Kunden zu überreden, mal benötige Software zu installieren.

>> Als Programmierer sollte einem die Sprache doch total egal sein ;)
>
> hehe :-) soooo isses ja nun auch nicht ;-)

Nicht ganz, aber fast. Letztlich sollten doch nur die Konzepte im
Vordergrund stehen. Aber natürlich darf man Sprachen mehr mögen als
andere, wenn sie Konzepte besser umsetzen :P

>> letzter Zeit habe ich PHP (größer 5.1 ;) ) aber irgendwie lieb gewonnen,
>> da man erstaunlich viele Konzepte aus vielen verschiedenen Sprachen
>> problemlos übernehmen kann.
>
> Keine Frage! PHP mit seinen neuen Features ist schon ein guter
> Fortschritt. Was mich nen bischen ärgert ist, das PHP beim Sprung zu
> Version 6 kaum nennenswerte neue Features bietet. Aber andererseits hab
> ich kein Recht dazu mir sowas anzumaßen, da ich noch nie zur
> PHP-Entwicklung direkt beigetragen habe. Aber ich wollts nur mal gesagt
> haben ;-)

Dann lasse uns doch mal eine neue Sprache entwickeln ;) Habe ich sowieso
schon länger vor. Steht nur ein paar Punkte über einem eigenen
Betriebssystem. Allerdings ist mein 10 Jahres Plan völlig überfüllt und
ich benötige wohl mehr als ein Leben, um alles abzuarbeiten.

>> Diese Programmierfreiheit wird nur noch
>> durch LISP getoppt.
>
> Ich hab zwar auch schon (ge)LISP(elt) aber da ziehe ich wiederum PHP
> vor. LISP erfordert immer 100% Aufmerksamkeit. Aber manchmal will man
> das 60% auch ausreichen. Ich hoffe das ist verständlich ausgedrückt.

Ich weiß was du meinst ;)
Was ich besonders gut an LISP finde ist die extrem vereinfachte Syntax,
die starke Erweiterbarkeit und die hohe Wiederverwendbarkeit. Anderseits
ist es ein ziemlicher Krampf, es ans laufen zu bekommen und man brauch
viel Zeit, um hinter das Prinzip zu kommen, wenn man nur "den
neumodischen Krams" kennt ^^

>> Aber das mag niemand in der Firma sehen und daher
>> bleibt mir auch nur wenig Zeit, mich damit zu beschäftigen. PHP ist
>> quasi mein Trost durch den Arbeitstag :P
>
> :-)
>
> Das ist bei mir Delphi. Ich liebe Delphi! platonisch natürlich ;-)

Ein paar der Oracel aus Delphi sollen ja ganz Ansehnlich gewesen sein ;)
Delphi ist ziemlich lange her, dass ich das gemacht habe. *in Erinnerung
schwelg*

>> Aber da ich es gerade erwähne: Mir fehlt ein richtig guter PHP-Editor ;)
>
> Das hatte ich auch mal vor so nen Teil zu coden. Da mir keiner geholfen
> hat hab ich irgendwann aufgegeben. Das klingt zwar jetzt wie "Keiner
> spielt mit mir" aber so isses nicht gemeint! :-x

Warum nicht? Ich sage das auch immer, weil es stimmt. Und entweder sind
alle anderen faul und wir sind Größenwahnsinnig. Aber zweiteres ist
quasi unmöglich ;)

>> Dabei sollte man nicht vergessen, dass auch das nachträgliche Anpassen
>> oder gar das Debuggen der Tests enorme Mengen an Zeit verschleudert.
>> Wenn ich sicher sein könnte, dass niemand dieses Posting jemals liest,
>> würde ich UnitTests als "totale Verschwendung und Unfug" bezeichnen ;)
>
> "Notwendiger Unfug" würde ich da sagen.

Das bringt es auf den Punkt.

Gruß,
Torsten

Re: [OT] PHP-Dokumentationstool

Ulf Kadner schrieb:

> Was ich damit ausdrücken wollte ist, das Änderungen in der Signatur
> einer Methode/Funktion kein guter Stil sind.

Damit hast du natürlich recht.

> Der Nutzer der Methode wirds Dir danken wenn diese konstant bleibt. Jede
> Änderung kann tiefgreifende Anwendungsübergreifende Änderungen bewirken.

Damit ebenfalls. Ich entferne bspw. auch public Methoden, von denen ich
weiß, dass ich persönlich nicht mehr nutze, nicht, sondern dokumentiere
sie als @unused, um das API nicht zu "ändern".

> Hier nehmen wohl Überladungen eine Sonderstellung ein. Eine Signatur
> ändert sich ja in PHP nicht zwangsmässig direkt, wenn man Überladung
> nutzt. Damit wird diese nur erweitert und kann immernoch wie vorher
> genutzt werden, solange Zusätze optional bleiben.

Das wollte ich damit ausdrücken ;-). Ich komme immer wieder in exakt
diese Situation, dass ich bei einer Erweiterung im Prinzip die selbe
Methode verwenden sollte, diese aber in den erweiterten Fällen mehr
Informationen benötigt. Dann gehe ich exakt wie beschrieben vor.

gruss, heli

Re: [OT] PHP-Dokumentationstool

Torsten Zühlsdorff wrote:

> Beim herumprobieren habe ich nur die Funktion overload gefunden:
> http://www.php.net/overload

Zwischen den von Dir geposteten Link und der *Funktion* overload besteht
aber ein Unterschied!

Die Funktion selbst wurde nur von PHP4 unterstützt.
Genauer (PHP4 >= 4.2.0)

Siehe:
http://de2.php.net/manual/en/function.overload.php

MfG, Ulf

Re: [OT] PHP-Dokumentationstool

Hallo Ulf,

Ulf Kadner schrieb:
> Genau das wollte ich gern vermeiden! (es in PHP umzusetzen)
>
> Da muss man erst wieder ein passendes Webinterface zusammenschrauben,
> was ansich schon wesentlich mehr Zeit beansprucht als die Entwicklung
> eines GUIs für normale Programme.

Schon mal an PHP-GTK gedacht? Da hast Du "normale" GUI-Technologie.

> Wieterhin würde ich PHP als zu langsam einstufen um gleich ganze
> Projekte zu verarbeiten.

PhpDocumentor verarbeitet auch ein ganzes Projekt. Sowas lässt man ja
nicht ständig durchlaufen, sondern in regelmäßigen Abständen, um zu
überprüfen, ob die Dokumentation aktuell ist.

>> Nutzerinteraktion wäre dann zwar weniger vorhanden, ich bezweifle
>> aber, ob sich der Aufwand für sowas lohnt.
>
>
> Warum nicht? Genau das halte ich für einen sehr wichtigen Punkt! Schau
> mal auf erfolgreiche Software-Projekte. Meist sind das (natürlich
> abhängig vom Anliegen) Projekte, die dem Nutzer ein intuitives Interface
> bereit stellen, welches ohne grosse Umschweife genau das macht was man
> erwartet. Einem Arbeit abnehmen, Daten gut strukturiert darstellen,
> leichte Bearbeitung, schnelles Handling usw.

Das Problem ist, dass ein zusätzliches GUI-Tool eingeführt wird, und das
bringt zusätzliche Komplexität und einen methodischen Bruch. Du musst
dann Deinen Quelltext in einem anderen GUI öffnen, um die Dokumentation
zu bearbeiten. Das halte ich für keine gute Idee.
Man könnte dann fragen, warum man nicht auch gleich erlaubt, eine neue
Funktion mit Signatur und Funktionsrumpf anzulegen, wenn Du schon einen
Dialog für die Dokublöcke vorsiehst. Und ruckzuck bist Du schon bei
einer Entwicklungsumgebung, und die muss man ja nicht neu erfinden.

Das Ziel wäre für mich daher eher, die Anwendung eines solchen Tools
möglichst reibungslos und integriert in den Entwicklungsablauf zu
gestalten. Also einfach ein Kommando aufrufen, welches das Projekt
analysiert, Dokublöcke generiert und einen Bericht zurückgibt.

Aber vielleicht gibt's da auch einen Kompromiss: eine grafische
Anwendung, welche auf einem Kommandozeilentool aufsetzt. Das hat sich ja
vielfach bewährt.

> Wie meinst Du das? Woran erkennt man, das ein Dokumentationsblock nicht
> mehr aktuell ist?

Es sind
- Parameter zu einer Funktion hinzugekommen (siehe Helmuts Beschreibung)
- es haben sich Parameter geändert (Namen, Datentyp (siehe Type-Hinting)
- es sind Funktionen hinzugekommen
- Funktionen sind von private auf public geändert worden

halt alles, was so beim Entwickeln passiert.

Grüße
Christian


--
-------------------------------------
http://www.netzologie.de
Email: vorname.nachname (bei) gmx.net

Re: [OT] PHP-Dokumentationstool

Christian Smietana wrote:

> Schon mal an PHP-GTK gedacht? Da hast Du "normale" GUI-Technologie.

Nicht freiwillig! :-) PHP-GTK ist in meinen Augen nur dan eine mögliche
Alternative, wenn man halt nur PHP beherrscht.

>> Wieterhin würde ich PHP als zu langsam einstufen um gleich ganze
>> Projekte zu verarbeiten.
> PhpDocumentor verarbeitet auch ein ganzes Projekt.

Der macht aber auch was anderes als das Tool was ich bauen will. Das ist
wie wenn man Äpfel mit Bananen vergleicht.

> Das Problem ist, dass ein zusätzliches GUI-Tool eingeführt wird, und das
> bringt zusätzliche Komplexität und einen methodischen Bruch.

Dann unterscheiden sich hier unsere Geschmäcker stark.

> dann Deinen Quelltext in einem anderen GUI öffnen, um die Dokumentation
> zu bearbeiten. Das halte ich für keine gute Idee.

Das, was das Tool können soll läßt sich nunmal nur über ein komplexes
Interface umsetzen. Sowas in der Kommandozeile zu machen ist wohl eher
ein Ding der Unmöglichkeit. Da kann ichs auch gleich ganz sein lassen.

> Man könnte dann fragen, warum man nicht auch gleich erlaubt, eine neue
> Funktion mit Signatur und Funktionsrumpf anzulegen

Editor-Funktionalität? Neeee ;-)

> Das Ziel wäre für mich daher eher, die Anwendung eines solchen Tools
> möglichst reibungslos und integriert in den Entwicklungsablauf zu
> gestalten. Also einfach ein Kommando aufrufen, welches das Projekt
> analysiert, Dokublöcke generiert und einen Bericht zurückgibt.

Sowas gibts mit Doxygen z.B. da breucht man nix erfinden.

> Aber vielleicht gibt's da auch einen Kompromiss: eine grafische
> Anwendung, welche auf einem Kommandozeilentool aufsetzt.

Die Einbindung in die IDE deiner Wahl sollte schon sinnvolle Parameter
entgegen nehmen können. Das Interface muss aber grafisch sein.

> - Parameter zu einer Funktion hinzugekommen (siehe Helmuts Beschreibung)

OK

> - es haben sich Parameter geändert (Namen, Datentyp (siehe Type-Hinting)

Parameter ändert man nicht! (Siehe kurze Diskusion mit Helmut)

> - es sind Funktionen hinzugekommen

OK

> - Funktionen sind von private auf public geändert worden

OK

> halt alles, was so beim Entwickeln passiert.

ACK

MfG, Ulf

Re: [OT] PHP-Dokumentationstool

Ulf Kadner schrieb:

>> Beim herumprobieren habe ich nur die Funktion overload gefunden:
>> http://www.php.net/overload
>
> Zwischen den von Dir geposteten Link und der *Funktion* overload besteht
> aber ein Unterschied!
>
> [..]
>
> Siehe:
> http://de2.php.net/manual/en/function.overload.php

Welcher?

Der Link von mir verweist auf die Modulebeschreibung "Overload". Bereits
der zweite Satz besagt: "Only one function is defined in this extension,
overload() which takes the name of the class that should have this
functionality enabled." und verweist auf die etwas seltsame
Interpreation einer Überladen-Implementation hin ;)

Oder meinst du etwas anderes?

Gruß,
Torsten