Dokumentation, PHPDocumentor, Erfahrungen, Redundanzen mit Code

[frankx]

Hellihello

ausgelöst durch diesen Hineweis http://forum.de.selfhtml.org/archiv/2008/2/t166564/#m1086385 kam ich auf Doxygen und PHPDocumentor. PHPDocumentor schien mir nach ersten Recherchen die Wahl für PHP Code.

Wenn ich es recht kapiere, ist das an einer Syntax orientiert, die es beim Dokumnentieren von Java-Code gibt (JavaDoc).

1. ist festegelegt, in welchen Delimiteren der Kommentar zu stehen hat.
2. können "tags" benutzt werden, beginnend mit dem Klammeraffen.

Aufgefallen ist mir beim einem ersten Testlauf, dass im Kommentar viel Redundanz zum folgenden Code auftaucht. D.h., es wird nicht "nur" beschrieben, was da im folgenden zu geschehen hat und welchen Zweck man damit verfolgt, sondern Teile des Codes (Parameter, Klassenzugehörigkeit etc.) werden im Grunde im Kommentar wiederholt.

Das ist ja sicherlich auch logisch, weil der Documentor sich ja nur am Kommentar orientieren kann. Anderseits fragte ich mich, ob es da auch andere Ansätze einer Art "slim" Dokumentation gibt, bzw. auf welche Teile man beim Dokumentieren verzichten kann und auf welche besser nicht. Einleuchtend ist mir, dass insbesondere das in die Dokumentation gehört, was _nicht_ im Code steht.
Hat denn jemand hier Erfahrung mit dem PHPDocumentor gesammelt, oder folgt ihr in Kommentaren einer (anderen,gängigen) Konvention?

In der Forumssuche fand ich bezüglich PHPDocumentor in 2008/2007 nur einen unbeantworteten Post.

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

ausgelöst durch diesen Hineweis http://forum.de.selfhtml.org/archiv/2008/2/t166564/#m1086385 kam ich auf Doxygen und PHPDocumentor. PHPDocumentor schien mir nach ersten Recherchen die Wahl für PHP Code.
Wenn ich es recht kapiere, ist das an einer Syntax orientiert, die es beim Dokumnentieren von Java-Code gibt (JavaDoc).

Ja.

1. ist festegelegt, in welchen Delimiteren der Kommentar zu stehen hat.

Ja. /** und */. Also zwei Sternchen (und ein Whitespace-Zeichen) am Anfang. Das Ende ist beliebig, sprich: da kann vor dem */ stehen was will. Es gibt IDEs, die einen beim Erstellen solcher Blöcke behilflich sind, indem sie bereits alle @param vorausfüllen, oder beim Einfügen neuer Zeilen die Einrückung und das Zeilenstart-Sternchen gleich richtig setzen.

Aufgefallen ist mir beim einem ersten Testlauf, dass im Kommentar viel Redundanz zum folgenden Code auftaucht. D.h., es wird nicht "nur" beschrieben, was da im folgenden zu geschehen hat und welchen Zweck man damit verfolgt, sondern Teile des Codes (Parameter, Klassenzugehörigkeit etc.) werden im Grunde im Kommentar wiederholt.

Es gibt, aufgrund der eingeschränkten OOP-Möglichkeiten unter PHP4 einige für PHP5 nicht mehr benötigte Tags, wie @access und @static. Das waren unter PHP4 Hinweise, wie der Autor die Funktion hätte modifizieren wollen, wenn es diese Zugriffsmodifzierer bereits gegeben hätte. Für PHP5 gibt es sie nun und brauchen nicht nochmal extra dokumentiert zu werden.

Das ist ja sicherlich auch logisch, weil der Documentor sich ja nur am Kommentar orientieren kann.

Nein, er wertet auch die Signaturen der Funktionen/Methoden und Namen der Klassen und Eigenschaften direkt aus dem Code aus.

Anderseits fragte ich mich, ob es da auch andere Ansätze einer Art "slim" Dokumentation gibt, bzw. auf welche Teile man beim Dokumentieren verzichten kann und auf welche besser nicht. Einleuchtend ist mir, dass insbesondere das in die Dokumentation gehört, was _nicht_ im Code steht.
Hat denn jemand hier Erfahrung mit dem PHPDocumentor gesammelt, oder folgt ihr in Kommentaren einer (anderen,gängigen) Konvention?

Beispiele finden sich in vielen gängigen (besseren) Softwareprojekten, besonders wenn sie als Bibliotheken daherkommen. Aus eigener Erfahrung kann ich da nur das Zend Framework anführen. Das hat am Ende der Coding-Style-Dokumentation etwas über die Inline-Dokumentation geschrieben. Sicher braucht man nicht wirklich alle diese Tags. Wesentlich für IDEs mit Codevervollständigung, die dafür auch die PHPDoc-Kommentare heranziehen, sind im Grunde genommen nur @param und @return für die Funktionen/Methoden und @var für Klasseneigenschaften. Es gibt auch noch speziell für das Zend Studio einen extra Inline-Kommentar, der bei Unklarheiten des Typs einer Variablen verwendet werden kann:

$variable = funktion_mit_mehreren_möglichen_rückgabewerten();

if ($variable == ...)
    /* @var $variable type */
    $variable-> // hier kann dann die Codevervollständigung gezielter die beim Vervollständigen zu verwendenden Klassenmitglieder anbieten
  else
    /* @var $variable anderer_type */
    $variable->...

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

merci.

1a. ist festegelegt, in welchen Delimiteren der Kommentar zu stehen hat.

Ja. /** und */. Also zwei Sternchen (und ein Whitespace-Zeichen) am Anfang. Das Ende ist beliebig, sprich: da kann vor dem */ stehen was will. Es gibt IDEs, die einen beim Erstellen solcher Blöcke behilflich sind, indem sie bereits alle @param vorausfüllen, oder beim Einfügen neuer Zeilen die Einrückung und das Zeilenstart-Sternchen gleich richtig setzen.

Welche IDE nutzt Du denn? Ich nutze bisher SciTE und hatte einmal Eclipse (light oder so für PHP) kurz angefasst. In der aktuellen ct las ich irgendwas davon, dass Zend für 400,- was anbietet zusammen mit Eclipse. Ich dachte bisher immer, das wäre frei.

Aufgefallen ist mir beim einem ersten Testlauf, dass im Kommentar viel Redundanz zum folgenden Code auftaucht. D.h., es wird nicht "nur" beschrieben, was da im folgenden zu geschehen hat und welchen Zweck man damit verfolgt, sondern Teile des Codes (Parameter, Klassenzugehörigkeit etc.) werden im Grunde im Kommentar wiederholt.

Es gibt, aufgrund der eingeschränkten OOP-Möglichkeiten unter PHP4 einige für PHP5 nicht mehr benötigte Tags, wie @access und @static. Das waren unter PHP4 Hinweise, wie der Autor die Funktion hätte modifizieren wollen, wenn es diese Zugriffsmodifzierer bereits gegeben hätte. Für PHP5 gibt es sie nun und brauchen nicht nochmal extra dokumentiert zu werden.

gut zu wissen.

Das ist ja sicherlich auch logisch, weil der Documentor sich ja nur am Kommentar orientieren kann.

Nein, er wertet auch die Signaturen der Funktionen/Methoden und Namen der Klassen und Eigenschaften direkt aus dem Code aus.

auch gut zu wissen (;-).

Anderseits fragte ich mich, ob es da auch andere Ansätze einer Art "slim" Dokumentation gibt, bzw. auf welche Teile man beim Dokumentieren verzichten kann und auf welche besser nicht. Einleuchtend ist mir, dass insbesondere das in die Dokumentation gehört, was _nicht_ im Code steht.
Hat denn jemand hier Erfahrung mit dem PHPDocumentor gesammelt, oder folgt ihr in Kommentaren einer (anderen,gängigen) Konvention?

Beispiele finden sich in vielen gängigen (besseren) Softwareprojekten, besonders wenn sie als Bibliotheken daherkommen. Aus eigener Erfahrung kann ich da nur das Zend Framework anführen. Das hat am Ende der Coding-Style-Dokumentation etwas über die Inline-Dokumentation geschrieben. Sicher braucht man nicht wirklich alle diese Tags.

Fein. Gleich ausgedruckt.

Wesentlich für IDEs mit Codevervollständigung,...

was gibts denn noch, außer Eclipse. Gibts was gnuiges/freies?
 die dafür auch die PHPDoc-Kommentare heranziehen, sind im Grunde genommen nur @param und @return für die Funktionen/Methoden und @var für Klasseneigenschaften.

Es gibt auch noch speziell für das Zend Studio einen extra Inline-Kommentar, der bei Unklarheiten des Typs einer Variablen verwendet werden kann:

$variable = funktion_mit_mehreren_möglichen_rückgabewerten();

if ($variable == ...)
    /* @var $variable type */
    $variable-> // hier kann dann die Codevervollständigung gezielter die beim Vervollständigen zu verwendenden Klassenmitglieder anbieten
  else
    /* @var $variable anderer_type */
    $variable->...

Zend Studio ist dann die IDE zum ZendFramework? Hab jetzt nicht yahoot, schaff ich aber noch.

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Welche IDE nutzt Du denn?

Für das was ich noch in PHP mache verwende ich hauptsächlich das Zend Studio, weil es die beste mir bisher bekannte Codevervollständigung für PHP bietet und auf Linux, Windows und MacOSX läuft. Außerdem nehm ich noch Eclipse mit PHPEclipse und PDT.

Ich nutze bisher SciTE ...

Das ist keine IDE sondern "nur ein Editor". :-)

... und hatte einmal Eclipse (light oder so für PHP) kurz angefasst. In der aktuellen ct las ich irgendwas davon, dass Zend für 400,- was anbietet zusammen mit Eclipse. Ich dachte bisher immer, das wäre frei.

Eclipse an sich ist frei erhältlich und diverse Plugins auch. Es gibt aber auch kommerziell angebotene Plugins und vermutlich auch Pakete, die zum kommerziellen Plugin gleich noch Eclipse mitliefern.

Wesentlich für IDEs mit Codevervollständigung,...
was gibts denn noch, außer Eclipse. Gibts was gnuiges/freies?

PHPEdit unter Windows hatte ich mal eine Weile, damals als er noch recht instabil war. Vom Rest kenne ich nichts weiter als einige Namen oder sie als allgemeine Editoren.

Zend Studio ist dann die IDE zum ZendFramework?

Nein, nicht wirklich. Das Zend Studio ist ein Produkt der Firma Zend. Das Zend Framework wird unter Aufsicht/Leitung von Zend als offenes PHP-Framework entwickelt. Es war wohl mal die Rede von einer Unterstützung des Zend Framworks durch das Zend Studio, doch wenn es das in irgend einer Studio Version größer als 5.2.0 geben sollte, dann wird es wohl auch nicht viel mehr bringen als das Einbinden jedes beliebigen anderen PHPDoc-kommentierten PHP-Codes.

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

Welche IDE nutzt Du denn?

Für das was ich noch in PHP mache verwende ich hauptsächlich das Zend Studio, weil es die beste mir bisher bekannte Codevervollständigung für PHP bietet und auf Linux, Windows und MacOSX läuft.

Genau, das gibts jetzt ab 400,- in Kombination mit Eclipse (zB.: http://www.golem.de/0801/57168.html.

Außerdem nehm ich noch Eclipse mit PHPEclipse und PDT.

Ich nutze bisher SciTE ...

Das ist keine IDE sondern "nur ein Editor". :-)

Ja, das dachte ich auch und hatte das dazuschreiben wollen. Nach dem Anblick von EclipsePDT (und vorher mal Eclipse-light) schau ich nochmal beim Wikepedialink und lese:

"Eine integrierte Entwicklungsumgebung (Abkürzung IDE, von engl. integrated development environment, auch integrated design environment) ist ein Anwendungsprogramm zur Entwicklung von Software.

Integrierte Entwicklungsumgebungen können funktional zu einer Gruppe zusammengefasst werden und verfügen in der Regel über folgende Komponenten:

* Texteditor
    * Compiler bzw. Interpreter
    * Linker
    * Debugger
    * Quelltextformatierungsfunktion"

Texteditor ist SciTE.

Interpreterfenster gibt es auch (command.go kann für diverse sogar File-Types auch unterschiedlich definiert werden -  ich erhalte dann die PHP-Rückgabe im Ausgabefenster)

Linker hab ich nicht kapiert. Brauch ich das nur bei C? Das Includen übernimmt ja PHP selbst.

Debugger: Da hilft bei SciTE nur die PHP-Rückgabe. Mit "F4" springt es aber die Scriptzeile an, in der der Fehler auftrat. Auch, wenn es in einer includierten Datei war, springt er die an. Was macht den Eclipse da noch. Ich musste eine viertelstunde rumfummeln, weil es den Interpreter nicht zu akzeptieren schien, bis ich dann die Debuggerfunktion deaktivert habe. Dann liefs erstmal.

Quelltextformatierungsfunktion gibts keine, nur einfach konfigurierbare Abkürzungen in eine Abkürzungsdatei. Da steht dann zB php=<?php\n\t|\n?> als Kurzformdeinition, was ja einen Teil der Formatierung schon mit sich bringt.

Ich schreib das deshalb nochmal so ausführlich, weil ich mich halt schon zum zweiten mal fragte, ob mir diese IDE gegeüber SciTE Vorteile bringen würde. Und ich tendiere zu SciTE. Immerhin gibts eben keine Übersicht der Klassen und Funktionen. Aber ein direktes Anspringen der Hilfe in einer chm zB. schafft Scite auch mit "currentWord" und Angabe einer URL oder eben einer chm.

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Linker hab ich nicht kapiert. Brauch ich das nur bei C? Das Includen übernimmt ja PHP selbst.

Ja, das braucht man bei PHP nicht. Man erzeugt ja keine ausführbare Datei, die gegen irgendwelche Bibliotheken gebunden werden muss.

Debugger: Da hilft bei SciTE nur die PHP-Rückgabe. Mit "F4" springt es aber die Scriptzeile an, in der der Fehler auftrat. Auch, wenn es in einer includierten Datei war, springt er die an. Was macht den Eclipse da noch.

Mal abgesehen davon, dass ich den Debugger für PHPEclipse nicht zum Laufen bekommen habe, und der mir bei Webseiten nur bedingt hilft, debugge ich mit Kontrollausgaben, erweitert um einen eigenen Fehlerhandler, der mir auch Backtrace-Daten liefert.
Normalerweise ist es aber so, dass man schrittweise jede Zeile einzeln abarbeiten kann, und sich dabei die Variableninhalte zu Gemüte führen kann.

[...] ob mir diese IDE gegeüber SciTE Vorteile bringen würde. Und ich tendiere zu SciTE.

Missionieren ist nicht meine Aufgabe. Ich beschränke mich bei Themen, bei denen Vorlieben eine große Rolle spielen, gern auf die reine Nennung/Beschreibung von Eigenschaften. Die IDE ist speziell auf die Programmiersprache und deren Werzeuge abgestimmt. Ein Editor hat die Aufgabe universell zu sein, und bringt manchmal mehr oder weniger Unterstützung für bestimmte Sprachen mit. Codevervollständigung geht beim Editor oft nur für die bekannten, zum Lieferumfang gehörenden Elemente einer Sprache. Eine IDE hingegen parst ständig im Hintergrund den Quelltext, weiß ihn zu interpretieren, und kann dann beispielsweise auch für die eben erst selbst definierte Variable schon Codevervollständigung anbieten. Mir hilft das, den ich will und kann mir nicht immer die Signaturen aller meiner selbst erstellten Funktionen merken. Hinspringen und nachschauen wäre möglich aber aufwendig.

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

Debugger: Da hilft bei SciTE nur die PHP-Rückgabe. Mit "F4" springt es aber die Scriptzeile an, in der der Fehler auftrat. Auch, wenn es in einer includierten Datei war, springt er die an. Was macht den Eclipse da noch.

Mal abgesehen davon, dass ich den Debugger für PHPEclipse nicht zum Laufen bekommen habe, und der mir bei Webseiten nur bedingt hilft, debugge ich mit Kontrollausgaben, erweitert um einen eigenen Fehlerhandler, der mir auch Backtrace-Daten liefert.

Ingerierst Du den Fehlerhandler ins error_reporting() bzw. geht das? Arbeitest Du da u.a. auch mit __LINE__? Und Backtrace heißt, dass man die Wurzel des Fehlers besser findet?

Normalerweise ist es aber so, dass man schrittweise jede Zeile einzeln abarbeiten kann, und sich dabei die Variableninhalte zu Gemüte führen kann.

[...] ob mir diese IDE gegeüber SciTE Vorteile bringen würde. Und ich tendiere zu SciTE.

Missionieren ist nicht meine Aufgabe. Ich beschränke mich bei Themen, bei denen Vorlieben eine große Rolle spielen, gern auf die reine Nennung/Beschreibung von Eigenschaften.

Ja, so wärs auch nicht gemeint gewesen.

Die IDE ist speziell auf die Programmiersprache und deren Werzeuge abgestimmt. Ein Editor hat die Aufgabe universell zu sein, und bringt manchmal mehr oder weniger Unterstützung für bestimmte Sprachen mit. Codevervollständigung geht beim Editor oft nur für die bekannten, zum Lieferumfang gehörenden Elemente einer Sprache.

Na SciTE kennt alle Worte im Dokument. Mit strg_return kann ich jederzeit die Möglichkeiten abrufen, wenn es nicht eindeutig ist. Ansonsten kommt das Angebot von allein. Allerdings kennt es (vielleicht ist es ja konfigurierba) nicht Worte, die noch nicht im Text vorkommen (abgesehen von den Shortcuts).

Eine IDE hingegen parst ständig im Hintergrund den Quelltext, weiß ihn zu interpretieren,

Den Vorteil sehe ich, und das ist auch nicht uninteressant. Das kann Scite irgendwie nicht (zumindest kenn ich es nicht), dass fehlerhafte Schreibweisen und Zeilen sofort am Rand bzw. als Unterstich markiert werden, eine Rechtschreibprüfung eben. Da es alle Worte kennt, kriegst Du bei Verschreibern halt immerhin das implizit mit, da sie nicht zur Autovervollständigung angeboten werden. Bzw. umgekehrt, wenn man diese konsequent nutzt, kann mich sich eben nicht verschreiben.

und kann dann beispielsweise auch für die eben erst selbst definierte Variable schon Codevervollständigung anbieten. Mir hilft das, den ich will und kann mir nicht immer die Signaturen aller meiner selbst erstellten Funktionen merken. Hinspringen und nachschauen wäre möglich aber aufwendig.

S.o.

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Ingerierst Du den Fehlerhandler ins error_reporting() bzw. geht das? Arbeitest Du da u.a. auch mit __LINE__? Und Backtrace heißt, dass man die Wurzel des Fehlers besser findet?

Ich nehme mir von den Error Handling and Logging Functions das set_error_handler(), und übergebe dem eine eigene Funktion. Diese bekommt alle Daten des Fehlers übergeben, inklusive Stelle des Auftretens, sowie der dort lokal vorhandenen Variablen und ihrer Werte.
Mit debug_backtrace() bekommt man außerdem noch eine Struktur, die sämtliche Funktionsaufrufe enthält, die zur aktuellen Stelle geführt haben, inklusive der jeweils übergebenen Parameterwerte.

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

Ingerierst Du den Fehlerhandler ins error_reporting() bzw. geht das? Arbeitest Du da u.a. auch mit __LINE__? Und Backtrace heißt, dass man die Wurzel des Fehlers besser findet?

Ich nehme mir von den Error Handling and Logging Functions das set_error_handler(), und übergebe dem eine eigene Funktion. Diese bekommt alle Daten des Fehlers übergeben, inklusive Stelle des Auftretens, sowie der dort lokal vorhandenen Variablen und ihrer Werte.

Hört sich nicht ganz so trivial an, nach erstem Anlesen. Du schaltest damit das komplette Errorhandling ab, wenn ich das recht kapiere. STRICT, NOTICE, WARNING existieren dann erstmal nicht mehr, oder? Gibt es dazu Vorlagen im Netz, konnte das bei php.net nicht so recht einordnen.

Mit debug_backtrace() bekommt man außerdem noch eine Struktur,

Struktur==Array?

die sämtliche Funktionsaufrufe enthält, die zur aktuellen Stelle geführt haben, inklusive der jeweils übergebenen Parameterwerte.

function   string    The current function name. See also __FUNCTION__.
line  integer  The current line number. See also __LINE__.
file  string  The current file name. See also __FILE__.
class  string  The current class name. See also __CLASS__
object  object  The current object.
type  string  The current call type. If a method call, "->" is returned. If a static method call, "::" is returned. If a function call, nothing is returned.
args  array  If inside a function, this lists the functions arguments. If inside an included file, this lists the included file name(s).

Oder?

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Du schaltest damit das komplette Errorhandling ab, wenn ich das recht kapiere. STRICT, NOTICE, WARNING existieren dann erstmal nicht mehr, oder?

Doch, erzeugt werden alle Meldungen. Nur werden sie nicht mehr gleich ausgegeben sondern an den registrierten Error-Handler übergeben. Selbst bei ge-@-ten Dingen wird der Error-Handler aufgerufen. PHP gibt ja nur eine kurze Meldung ab. Der Error-Handler bekommt ja mit der aktuellen Variablenliste deutlich mehr Informationen weitergereicht. Das spart einge Kontrollausgaben-Runden.

Gibt es dazu Vorlagen im Netz, konnte das bei php.net nicht so recht einordnen.

Im verlinkten Handbuch-Kapitel ist ja schon mal ein Beispiel zu sehen. Noch mehr gibt es bei den einzelnen Funktionen.

Mit debug_backtrace() bekommt man außerdem noch eine Struktur,
Struktur==Array?

Einfach mal Ausprobieren :-) Ja, ein Array. Zur Sofort-Ausgabe gibt es noch die Funktion debug_print_backtrace().

[...]
Oder?

So sagt das Handbuch, und es hat, wie so oft, Recht.

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

Doch, erzeugt werden alle Meldungen. Nur werden sie nicht mehr gleich ausgegeben sondern an den registrierten Error-Handler übergeben. Selbst bei ge-@-ten Dingen wird der Error-Handler aufgerufen. PHP gibt ja nur eine kurze Meldung ab. Der Error-Handler bekommt ja mit der aktuellen Variablenliste deutlich mehr Informationen weitergereicht. Das spart einge Kontrollausgaben-Runden.

"Kontrollausgaben-Runden" sind "echos" oder "var_dumps" um den aktuellen Zustand von Variablen zB. in Funktionen zu testen?

Gibt es dazu Vorlagen im Netz, konnte das bei php.net nicht so recht einordnen.

Im verlinkten Handbuch-Kapitel ist ja schon mal ein Beispiel zu sehen. Noch mehr gibt es bei den einzelnen Funktionen.

dort:

"$old_error_handler = set_error_handler("userErrorHandler");"

wieso "_alter_" Fehlerbehandler. Ist doch der neue, oder?

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

"Kontrollausgaben-Runden" sind "echos" oder "var_dumps" um den aktuellen Zustand von Variablen zB. in Funktionen zu testen?

Ja. Man hat einen Fehler erkannt und muss nun, um ihm auf die Spurr zu kommen, den Request ein bis mehrmals wiederholen, mit ein paar Ausaben der verdächtigten Variablen.

"$old_error_handler = set_error_handler("userErrorHandler");"
wieso "_alter_" Fehlerbehandler. Ist doch der neue, oder?

Der neue wird gesetzt. Der alte wird dafür zurückgegeben, damit man ihn bei Bedarf sich irgendwo merken und wiederherstellen kann.

echo "$verabschiedung $name";

[frankx]

Hellihello

"Kontrollausgaben-Runden" sind "echos" oder "var_dumps" um den aktuellen Zustand von Variablen zB. in Funktionen zu testen?

Ja. Man hat einen Fehler erkannt und muss nun, um ihm auf die Spurr zu kommen, den Request ein bis mehrmals wiederholen, mit ein paar Ausaben der verdächtigten Variablen.

Nun verfügt er userErrorHandler ja über 5 vars, wobei die ersten vier von PHP standardmäßig ja ausgegeben werden (Code/Message/Filename/Line). Der fünfte Paramter "ist eine optionale Ergänzung zu der Fehlerinformation, die myHandler() automatisch erhält, und enthält einen Schnappschuss des aktuellen Status der Variablen. Mit dieser Zusatzinformation kann der Administrator sich ein Bild vom Kontext des Fehlers machen, was die Debuggingzeit deutlich reduziert.". Das ist ein Array was wiederum Arrays enthält mit insgesamt über 250 Schlüssel/Wert-Paaren. Mmh.

Bei "debug_backtrace()" scheints mir, dass da Werte vom fünften Paramter wieder auftauchen. Irgendwie krieg ich die rekursiv grad nicht gezählt. Immerhing finde ich im Array debug_backtrace() an Stelle 3 den Key "function", der noch einen Hinweis auf die Funktion gibt.

"$old_error_handler = set_error_handler("userErrorHandler");"
wieso "_alter_" Fehlerbehandler. Ist doch der neue, oder?

Der neue wird gesetzt. Der alte wird dafür zurückgegeben, damit man ihn bei Bedarf sich irgendwo merken und wiederherstellen kann.

var_dump($old_error_hanlder) bringt aber NULL, oder?

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Nun verfügt er userErrorHandler ja über 5 vars, wobei die ersten vier von PHP standardmäßig ja ausgegeben werden (Code/Message/Filename/Line). Der fünfte Paramter "ist eine optionale Ergänzung zu der Fehlerinformation, die myHandler() automatisch erhält, und enthält einen Schnappschuss des aktuellen Status der Variablen. Mit dieser Zusatzinformation kann der Administrator sich ein Bild vom Kontext des Fehlers machen, was die Debuggingzeit deutlich reduziert.". Das ist ein Array was wiederum Arrays enthält mit insgesamt über 250 Schlüssel/Wert-Paaren. Mmh.

Das liegt dann aber daran, dass in dem aktuellen Scope so viele Variablen rumliegen. Im globalen Scope kann das aufgrund der bekannten globalen Variablen zuzüglich $GLOBALS schon recht viel werden. Erstell mal eine Funktion mit einigen wenigen lokalen Variablen und ruf darin trigger_error() auf. Dann hält sich der Inhalt des 5. Parameteres in Grenzen.

Bei "debug_backtrace()" scheints mir, dass da Werte vom fünften Paramter wieder auftauchen. Irgendwie krieg ich die rekursiv grad nicht gezählt. Immerhing finde ich im Array debug_backtrace() an Stelle 3 den Key "function", der noch einen Hinweis auf die Funktion gibt.

debug_backtrace() enthält nur die Werte der Funktionsparameter. Andere lokale Variablen sind darin nicht enthalten.

var_dump($old_error_hanlder) bringt aber NULL, oder?

Wenn du der erste bist, der den ErrorHandler setzt, dann ja. Wenn du außerdem der einzige bist, kannst du den Rückgabewert komplett ignorieren.

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

Das liegt dann aber daran, dass in dem aktuellen Scope so viele Variablen rumliegen. Im globalen Scope kann das aufgrund der bekannten globalen Variablen zuzüglich $GLOBALS schon recht viel werden.

0: GLOBALS
1: _ENV
2: HTTP_ENV_VARS
3: argv
4: argc
5: _POST
6: HTTP_POST_VARS
7: _GET
8: HTTP_GET_VARS
9: _COOKIE
10: HTTP_COOKIE_VARS
11: _SERVER
12: HTTP_SERVER_VARS
13: _FILES
14: HTTP_POST_FILES
15: _REQUEST

Erstell mal eine Funktion mit einigen wenigen lokalen Variablen und ruf darin trigger_error() auf. Dann hält sich der Inhalt des 5. Parameteres in Grenzen.

Jap:

  
  
class My  
{  
 public static $total = 0;  
 public static function trigger_error_test($param)  
 {  
  $var1=$param;  
  $var2=2;  
  $var3=array(1, 2, 3);  
  trigger_error();  
 }  
}  
My::trigger_error_test("testparam");  
  
  

bringt als context:

array(4) {
  ["param"]=>
  string(9) "testparam"
  ["var1"]=>
  string(9) "testparam"
  ["var2"]=>
  int(2)
  ["var3"]=>
  array(3) {
    [0]=>
    int(1)
    [1]=>
    int(2)
    [2]=>
    int(3)
  }
}

Bei "debug_backtrace()" scheints mir, dass da Werte vom fünften Paramter wieder auftauchen. Irgendwie krieg ich die rekursiv grad nicht gezählt. Immerhing finde ich im Array debug_backtrace() an Stelle 3 den Key "function", der noch einen Hinweis auf die Funktion gibt.

debug_backtrace() enthält nur die Werte der Funktionsparameter. Andere lokale Variablen sind darin nicht enthalten.

--- START var_dump debug_backtrace() ---:
array(3) {
  [0]=>
  array(2) {
    ["function"]=>
    string(18) "my_error_handler_2"
    ["args"]=>
    array(5) {
      [0]=>
      &int(2)
      [1]=>
      &string(41) "Wrong parameter count for trigger_error()"
      [2]=>
      &string(44) "D:\xampp\htdocs\PHP_Tests\Error_Handling.php"
      [3]=>
      &int(70)
      [4]=>
      &array(4) {
        ["param"]=>
        string(9) "testparam"
        ["var1"]=>
        string(9) "testparam"
        ["var2"]=>
        int(2)
        ["var3"]=>
        array(3) {
          [0]=>
          int(1)
          [1]=>
          int(2)
          [2]=>
          int(3)
        }
      }
    }
  }
  [1]=>
  array(4) {
    ["file"]=>
    string(44) "D:\xampp\htdocs\PHP_Tests\Error_Handling.php"
    ["line"]=>
    int(70)
    ["function"]=>
    string(13) "trigger_error"
    ["args"]=>
    array(0) {
    }
  }
  [2]=>
  array(6) {
    ["file"]=>
    string(44) "D:\xampp\htdocs\PHP_Tests\Error_Handling.php"
    ["line"]=>
    int(87)
    ["function"]=>
    string(18) "trigger_error_test"
    ["class"]=>
    string(2) "My"
    ["type"]=>
    string(2) "::"
    ["args"]=>
    array(1) {
      [0]=>
      &string(9) "testparam"
    }
  }
}

--- END var_dump debug_backtrace() ---:

debug_backtrace()[2] bringt dann in "function" und "class" Funktion und Klasse. "type" bringt ein Paaym-Nekudotaym. Aha. Warum aber die ganzen Referenzen "&"?

var_dump($old_error_hanlder) bringt aber NULL, oder?

Wenn du der erste bist, der den ErrorHandler setzt, dann ja. Wenn du außerdem der einzige bist, kannst du den Rückgabewert komplett ignorieren.

Aha, die ersten werden die letzten sein. Wer sollte denn sonst noch am Werk sein?

Dank und Gruß,

frankx

[frankx]

Hellihello dedlfix,

Bei "debug_backtrace()" scheints mir, dass da Werte vom fünften Paramter wieder auftauchen. Irgendwie krieg ich die rekursiv grad nicht gezählt. Immerhing finde ich im Array debug_backtrace() an Stelle 3 den Key "function", der noch einen Hinweis auf die Funktion gibt.

debug_backtrace() enthält nur die Werte der Funktionsparameter. Andere lokale Variablen sind darin nicht enthalten.

--- START var_dump debug_backtrace() ---:
array(3) {
  [0]=>
  array(2) {
    ["function"]=>
    string(18) "my_error_handler_2"
    ["args"]=>
    array(5) {
      [0]=>
      &int(2)
      [1]=>
      &string(41) "Wrong parameter count for trigger_error()"
      [2]=>
      &string(44) "D:\xampp\htdocs\PHP_Tests\Error_Handling.php"
      [3]=>
      &int(70)
      [4]=>
      &array(4) {
        ["param"]=>
        string(9) "testparam"
        ["var1"]=>
        string(9) "testparam"
        ["var2"]=>
        int(2)
        ["var3"]=>
        array(3) {
          [0]=>
          int(1)
          [1]=>
          int(2)
          [2]=>
          int(3)
        }
      }
    }
  }
  [1]=>
  array(4) {
    ["file"]=>
    string(44) "D:\xampp\htdocs\PHP_Tests\Error_Handling.php"
    ["line"]=>
    int(70)
    ["function"]=>
    string(13) "trigger_error"
    ["args"]=>
    array(0) {
    }
  }
  [2]=>
  array(6) {
    ["file"]=>
    string(44) "D:\xampp\htdocs\PHP_Tests\Error_Handling.php"
    ["line"]=>
    int(87)
    ["function"]=>
    string(18) "trigger_error_test"
    ["class"]=>
    string(2) "My"
    ["type"]=>
    string(2) "::"
    ["args"]=>
    array(1) {
      [0]=>
      &string(9) "testparam"
    }
  }
}

--- END var_dump debug_backtrace() ---:

debug_backtrace()[2] bringt dann in "function" und "class" Funktion und Klasse. "type" bringt ein Paaym-Nekudotaym. Aha. Warum aber die ganzen Referenzen "&"?

Paamayim Nekudotayim.

type  string  The current call type. If a method call, "->" is returned. If a static method call, "::" is returned. If a function call, nothing is returned.

Und drei davon gibts, weil drei Funktionen gerade aufgerufen sind: 1. der eigene ErrorHandler, 2. der trigger_Error 3. die den Error triggernde Funktion.

Kann ich sicher sein, dass die den Error triggernde Funktion immer auf Platz drei rangiert?

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Und drei davon gibts, weil drei Funktionen gerade aufgerufen sind: 1. der eigene ErrorHandler, 2. der trigger_Error 3. die den Error triggernde Funktion.
Kann ich sicher sein, dass die den Error triggernde Funktion immer auf Platz drei rangiert?

Nein, denn du hast ja hier trigger_error() aufgerufen, was bei einer "normalen" PHP-Fehlermeldung nicht der Fall ist.

echo "$verabschiedung $name";

[frankx]

Hellihello dedlfix,

Und drei davon gibts, weil drei Funktionen gerade aufgerufen sind: 1. der eigene ErrorHandler, 2. der trigger_Error 3. die den Error triggernde Funktion.
Kann ich sicher sein, dass die den Error triggernde Funktion immer auf Platz drei rangiert?

Nein, denn du hast ja hier trigger_error() aufgerufen, was bei einer "normalen" PHP-Fehlermeldung nicht der Fall ist.

Logisch (;-).

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

debug_backtrace()[2] bringt dann in "function" und "class" Funktion und Klasse. "type" bringt ein Paaym-Nekudotaym. Aha.

Klar, du rufst das ja auch statisch auf.

Warum aber die ganzen Referenzen "&"?

Die Alternative wäre, dass debug_backtrace() eine Kopie der Werte anlegt. Die kann unter Umständen recht groß werden und muss über die gesamte Verschachtlungstiefe der Daten gehen. Eine Referenz zeigt einfach auf die Struktur. Fertig. Kein Kopieren oder dergleichen.

var_dump($old_error_hanlder) bringt aber NULL, oder?
Wenn du der erste bist, der den ErrorHandler setzt, dann ja. Wenn du außerdem der einzige bist, kannst du den Rückgabewert komplett ignorieren.
Aha, die ersten werden die letzten sein. Wer sollte denn sonst noch am Werk sein?

Vielleicht eine Script-Bibliothek eines Drittherstellers. Oder ein größeres Projekt mit mehreren beteiligten Programmierern. Jeder baut zwar an seinem abgegrenzten Teil, aber beim Verwenden gemeinsamer Ressourcen muss man schon mal berücksichtigen, dass andere auch noch darauf zugreifen können.

echo "$verabschiedung $name";

[Multi]

Ingerierst Du den Fehlerhandler ins error_reporting() bzw. geht das? Arbeitest Du da u.a. auch mit __LINE__? Und Backtrace heißt, dass man die Wurzel des Fehlers besser findet?

Um Backtraces und definierte Fehlerausgaben zu erzeugen, nutze ich xdebug. Wird als PHP-Modul eingebunden und läuft Problemlos. Zusätzlich gibt es einen Profiler und einen Debugger für gängige Umgebungen die DBGp unterstützen. Quanta+ bringt z.B. diese Unterstützung  bereits mit, für Eclipse gibt es ein Plugin.

[frankx]

Hellihello

Ingerierst Du den Fehlerhandler ins error_reporting() bzw. geht das? Arbeitest Du da u.a. auch mit __LINE__? Und Backtrace heißt, dass man die Wurzel des Fehlers besser findet?

Um Backtraces und definierte Fehlerausgaben zu erzeugen, nutze ich xdebug. Wird als PHP-Modul eingebunden und läuft Problemlos.

Fein http://devzone.zend.com/article/2803-Introducing-xdebug. Ist noch recht "jung"? Wie kamst Du darauf? Nutzt Du das dann in der Entwicklungsumgebung oder auch in der Produktiv(?)umgebung?

Zusätzlich gibt es einen Profiler und einen Debugger für gängige Umgebungen die DBGp unterstützen. Quanta+ bringt z.B. diese Unterstützung  bereits mit, für Eclipse gibt es ein Plugin.

DBGp (warum "p"?)

"DBG is an open source debugger and profiler for the PHP programming language. It supports a GUI interface as well as a command-line interface. It is the debugger used in NuSphere's PhpED (a commercial IDE for PHP). It was created by Dmitri Dmitrienko."

Profiler (ist wohl mehr als bzw. nicht nur fürs debuggen)

"In software engineering, performance analysis, more commonly profiling, is the investigation of a program's behavior using information gathered as the program runs (i.e. it is a form of dynamic program analysis, as opposed to static code analysis). The usual goal of performance analysis is to determine which parts of a program to optimize for speed or memory usage."

Dank und Gruß,

frankx

[Multi]

Fein http://devzone.zend.com/article/2803-Introducing-xdebug. Ist noch recht "jung"? Wie kamst Du darauf? Nutzt Du das dann in der Entwicklungsumgebung oder auch in der Produktiv(?)umgebung?

Draufgekommen bin ich beim Stöbern nach Debuggern. Ich nutze das jetzt seit ca. 4 Monaten. Allerdings nur in der Entwicklungsumgebungumgebung. Auf dem Testserver und den Produktivservern lasse ich das originale error_handling. Ich denke, xdebug frisst etwas Performance.

DBGp (warum "p"?)

Es ist das Protokoll, mit dem DBG und andere Debugger arbeiten. Und somit kann die IDE, wenn sie das Protokoll unterstützt, mit jedem Debugger kommunizieren, wenn dieser auch dieses Protokoll nutzt.
Wie erwähnt, Quanta+ (nutze ich fast ausschliesslich, aiuch für C/C++) kann das schon, Eclipse kann man das nur per Plugin beibringen (ich mag aber Eclipse sowieso nicht. Ich halte die Bedienung für umständlich und wenig inuitiv. Allerdings kenne ich einige Programmierer, die drauf schwören. Die mangelnde dcop-Unterstützung und das fehlende Drag&Drop sind für mich aber klare NoGos für eine IDE, vom Speicherverbrauch mal ganz abgesehen. Aber das muss jeder für sich entscheiden ;))

Profiler (ist wohl mehr als bzw. nicht nur fürs debuggen)

Stimmt. Gut um Bottlenecks zu finden und die Zusammenhänge zwischen Dateien zu analysieren. Grad zur Performanceoptimierung sehr gut zu gebrauchen. Allerdings muss ich sagen, dass ich damit erst sehr wenig gearbeitet hab und mein Wissen rein Theoretisch ist. Ich weiss also, das es geht, wie aber genau, muss ich mir erst noch anlesen.
In jedem Fall gibt es Programme, die diese Profile dann grafisch darstellen.

[frankx]

Hellihello dedlfix,

Aus eigener Erfahrung kann ich da nur das Zend Framework anführen. Das hat am Ende der Coding-Style-Dokumentation etwas über die Inline-Dokumentation geschrieben. Sicher braucht man nicht wirklich alle diese Tags. Wesentlich für IDEs mit Codevervollständigung, die dafür auch die PHPDoc-Kommentare heranziehen, sind im Grunde genommen nur @param und @return für die Funktionen/Methoden und @var für Klasseneigenschaften.

gemäß dem würde es dann in etwa so aussehen?

  
  
<?php  
/**  
 * Short description for file  
 * Using an XSLTprocessor  
 * Long description for file (if any)...  
 *  
 * LICENSE: Some license information  
 *  
 * @copyright  GNU GPL  
 * @license    GNU GPL  
 * @version   My_XSLT 1.0  
 * @link       http://spinneimnetz.de  
 * @since      My_XSLT 1.0  
*/  
  
/**  
 * Short description for class  
 * Process XSLT  
 * Long description for class (if any)...  
 *  
 * @copyright  GNU GPL  
 * @license    GNU GPL  
 * @version    1.0  
 * @link       http://spinneimnetz.de  
 * @since      My_XSLT 1.0  
**/  
  
class My_XSLT  
{  
 /**  
 * @var  string xml-string  
 */  
 private $xml="";  
  
 /**  
 * @var  string xsl-string  
 */  
 private $xsl="";  
  
 /**  
 * @var  string output-string  
 */  
 private $output="";  
  
 /**  
 * description of the function:  
 * reads xml_file and xsl_file and calls {@link process()}  
 * @param  string $file_path_xml file_path_xml  
 * @param  string $file_path_xsl file_path_xsl  
 * @return  boolean success of operation  
 */  
 public function __construct($file_path_xml,$file_path_xsl)  
 {  
   $this->xsl = new DOMDocument();  
  $this->xml = new DOMDocument();  
  if ($this->xml->load($file_path_xml) && $this->xsl->load($file_path_xsl)) {  
   $this->process();  
   return true;  
  } else {  
   return false;  
  }  
 }  
  
 /**  
 * description of the function:  
 *  applies xsl stylesheet to xml-data  
 * @param  string $file_path_xml file_path_xml  
 * @param  string $file_path_xsl file_path_xsl  
 * @return  boolean success of operation  
 */  
 private function process()  
 {  
 $proc = new XSLTprocessor;  
  if ($proc->importStyleSheet($this->xsl) // attach the xsl rules  
   && $this->output = $proc->transformToXML($this->xml)) {  // actual transformation  
   return true;  
  } else {  
   return false;  
  }  
 }  
 /**  
 * description of the function  
 * getter vor transformed xml-string  
 * @return  string transformed xml-string  
 */  
 public function putout()  
 {  
  return $this->output;  
 }  
  
 /**  
 * write transformed xml-string to file  
 * @param  string $file_path_xsl file_path_xsl  
 * @return  boolean success of writing not empty file  
 */  
  
 public function write($file_path_output)  
 {  
  if (file_put_contents($file_path_output,$this->putout())) {  
   return true;  
  } else {  
   return false;  
  }  
 }  
}  
  

?

Dank und Gruß,

frankx

[Vinzenz Mai]

Hallo Robert,

gemäß dem würde es dann in etwa so aussehen?

<?php
/**

• Short description for file
• Using an XSLTprocessor
• Long description for file (if any)...

// äh ja, hier kommt der meiner Meinung nach wichtigste Beitrag für eine gute
Dokumentation

// [...]

• Short description for class
• Process XSLT
• Long description for class (if any)...

// und hier.

  
was Du da schreibst ist die formale Erfüllung irgendwelcher Vorschriften.  
Gute, richtig gute Kommentare fangen dann erst an.  
Beschränkung auf rein formale Erfüllung ist meiner Meinung nach in aller Regel schlechte Praxis, Kritik an der unbrauchbaren Dokumentation wird vom Autor damit erschlagen, dass die formalen Anforderungen doch erfüllt seien. Es sei doch Dokumentation vorhanden.  
  
Der Benutzer, für den die Dokumentation gedacht sein sollte (denk an den Blogbeitrag), hat nichts (oder bestenfalls wenig) davon. Was da steht, ist das was Du in Deinem Titel bereits angesprochen hast: "Redundanzen mit Code". Für die IDE ist das gut. Der Benutzer von fremdem Code benötigt aber mehr, um den Code zu verstehen, richtig anzuwenden und gegebenenfalls modifizieren oder korrigieren zu können.  
  
Richtige und sinnvolle Dokumentation fängt meiner Meinung nach dort erst an.  
Leicht ist das übrigens nicht.  
  
  
Freundliche Grüße  
  
Vinzenz

[frankx]

Hellihello Vinzenz,

gemäß dem würde es dann in etwa so aussehen?

<?php
/**

• Short description for file
• Using an XSLTprocessor
• Long description for file (if any)...

// äh ja, hier kommt der meiner Meinung nach wichtigste Beitrag für eine gute
Dokumentation

Nun, in dem File jetzt steht ja nur die eine Klasse, was ja nicht selten der Fall ist, oder? Der Unterschied zwischen File-Desc. und Class-Desc. erschließt sich mit nicht unbedingt.

Meine Intention wäre zB so zu formulieren.

evtl File-Description:

With this Example File I try to demonstrate in HTML-AG
a) how to write a class in php
b) how to code correctly (s.a. Anmerkungen von dedlfix)
c) how to comment/document correctly (formally and reasonably)

evtl Class-Description:

Creating for demonstration and practical purspose a class, which transforms an xml-Dokument into an xhtml-Dokument using an xsl-stylesheet parsed by phps xslt-processor. The class reads xml and xsl from file and can either return the transformed xml as string or write it to a file.

// [...]

• Short description for class
• Process XSLT
• Long description for class (if any)...

// und hier.

>   
> was Du da schreibst ist die formale Erfüllung irgendwelcher Vorschriften.  
  
Jau, das war Anatz Teil 1.  
  

> Gute, richtig gute Kommentare fangen dann erst an.  
  
Jau, das kommt dann jetz, Inhalt in die Form packen.  
  

> Beschränkung auf rein formale Erfüllung ist meiner Meinung nach in aller Regel schlechte Praxis, Kritik an der unbrauchbaren Dokumentation wird vom Autor damit erschlagen, dass die formalen Anforderungen doch erfüllt seien. Es sei doch Dokumentation vorhanden.  
  
Schon klar.  

>   
> Der Benutzer, für den die Dokumentation gedacht sein sollte (denk an den Blogbeitrag), hat nichts (oder bestenfalls wenig) davon. Was da steht, ist das was Du in Deinem Titel bereits angesprochen hast: "Redundanzen mit Code". Für die IDE ist das gut. Der Benutzer von fremdem Code benötigt aber mehr, um den Code zu verstehen, richtig anzuwenden und gegebenenfalls modifizieren oder korrigieren zu können.  
>   
> Richtige und sinnvolle Dokumentation fängt meiner Meinung nach dort erst an.  
> Leicht ist das übrigens nicht.  
  
Wie aber unterscheidet sich die long-Description für den File von der long-description für die Klasse. Das o.g. ist ja eher die Beschreibung der Klasse.  
  
Dank und Gruß,  
  
Robert aka  
  
[frankx](http://community.de.selfhtml.org/visitenkarten/view.php?key=82)

-- 
[tryin to](http://sauer-ernst.de) [multitain](http://multitain.de)  - Globus = Planet != Welt 

[dedlfix]

echo $begrüßung;

gemäß dem würde es dann in etwa so aussehen?

* @copyright  GNU GPL
* @license    GNU GPL
* @version   My_XSLT 1.0
* @link       http://spinneimnetz.de
* @since      My_XSLT 1.0

Ob du diesen Kladderadatsch brauchst oder haben möchtest, musst du selbst entscheiden.

/**
* Short description for class
* Process XSLT
* Long description for class (if any)...

In der ersten Zeile steht eine Kurzbeschreibung. Dann folgt eine Leerzeile gefolgt von einer optionalen Langbeschreibung. Die Kurzbeschreibung wird in Übersichten angezeigt. Da sollte also was Aussagekräftiges drinstehen.

* @param  string $file_path_xml file_path_xml
* @param  string $file_path_xsl file_path_xsl
private function process()

Die Dokumentation passt nicht zur Signatur der Methode. Es ist auch kein func_*_args()-Aufruf in der Funktion zu sehen.

Hier noch ein Nicht-PHPDoc-Hinweis:

public function write($file_path_output)
{
  if (file_put_contents($file_path_output,$this->putout())) {
   return true;
  } else {
   return false;
  }
}
}

Wenn die Bedingung im if zutrifft, wird die Funktion aufgrund des return verlassen. Das return false; kann außerhalb des else notiert werden, da es ja in jedem Fall nur beim Nichtzutreffen ausgeführt wird. Obendrein ist hier gar kein if-else notwendig. return file_put_contents(...), zur Not nach boolean gecastet, ergibt das gleiche Ergebnis. Allerdings ist das im Spezialfall "alles i.O. es wurden aber nur 0 Bytes geschrieben" in keinem Fall richtig. return false !== file_put_contents(...); wäre dann genauer.

echo "$verabschiedung $name";

[frankx]

Hellihello

echo $begrüßung;

gemäß dem würde es dann in etwa so aussehen?

* @copyright  GNU GPL
* @license    GNU GPL
* @version   My_XSLT 1.0
* @link       http://spinneimnetz.de
* @since      My_XSLT 1.0

Ob du diesen Kladderadatsch brauchst oder haben möchtest, musst du selbst entscheiden.

Naja, wollt mal schauen, wies so geht und was passiert, wenn mans so macht, wie Zend es als obligatorisch angibt. GNU GPL finde ich für die Ergebnisse einer Schul-HTML-Ag zB garnicht so falsch. Wissen die Kinder auch gleich mal, dass es sowas gibt (die, dies noch nicht wissen).

/**
* Short description for class
* Process XSLT
* Long description for class (if any)...

In der ersten Zeile steht eine Kurzbeschreibung.

Statt "Short description for class"

Dann folgt eine Leerzeile gefolgt von einer optionalen Langbeschreibung. Die Kurzbeschreibung wird in Übersichten angezeigt. Da sollte also was Aussagekräftiges drinstehen.

  
  
/**  
* Process XSLT to create xthml from xml using xsl  
*  
* For demonstration purposeses ... and so on and so on  
* see answer to Vinzenz  
  
  

* @param  string $file_path_xml file_path_xml
* @param  string $file_path_xsl file_path_xsl
private function process()

Die Dokumentation passt nicht zur Signatur der Methode. Es ist auch kein func_*_args()-Aufruf in der Funktion zu sehen.

Yes, ein Copy-Paste-Fehler.

  
/**  
* ...  
* nix params  
*/  
  
private function process()  
  
  

Hier noch ein Nicht-PHPDoc-Hinweis:

public function write($file_path_output)
{
  if (file_put_contents($file_path_output,$this->putout())) {
   return true;
  } else {
   return false;
  }
}
}

Wenn die Bedingung im if zutrifft, wird die Funktion aufgrund des return verlassen. Das return false; kann außerhalb des else notiert werden, da es ja in jedem Fall nur beim Nichtzutreffen ausgeführt wird. Obendrein ist hier gar kein if-else notwendig. return file_put_contents(...), zur Not nach boolean gecastet, ergibt das gleiche Ergebnis. Allerdings ist das im Spezialfall "alles i.O. es wurden aber nur 0 Bytes geschrieben" in keinem Fall richtig. return false !== file_put_contents(...); wäre dann genauer.

  
  
public function write($file_path_output)  
{  
  return (false !== file_put_contents($file_path_output,$this->putout());  
}  
  
  

merci und
Dank und Gruß,

frankx

[frankx]

Hellihello dedlfix,

gemäß dem würde es dann in etwa so aussehen?

* @copyright  GNU GPL
* @license    GNU GPL
* @version   My_XSLT 1.0
* @link       http://spinneimnetz.de
* @since      My_XSLT 1.0

Ob du diesen Kladderadatsch brauchst oder haben möchtest, musst du selbst entscheiden.

Und was ist mit @package?

"Packages are used to help you logically group related elements. You write classes to group related functions and data together, and phpDocumentor represents the contents of files (functions, defines, and includes) as "Procedural Pages." A package is used to group classes and procedural pages together in the same manner that a directory groups related files together."

Hast Du damit Erfahrungen? Gibt es da Leit- Richtlinien?

Dank und Gruß,

frankx

[dedlfix]

echo $begrüßung;

Und was ist mit @package?

Zu einem Package gruppiere ich alles, was eine eine logische Einheit bildet und grundlegende Funktionalität kapselt.

Hast Du damit Erfahrungen? Gibt es da Leit- Richtlinien?

Das ZFW wird zwar nur als ein Downloadpaket geliefert, doch kann man die einzelnen Funktionalitäten auch einzeln nutzen und damit als Packages deklarieren.

Besonders PEAR ist ein System, das in Packages daherkommt. Es ist ja auch eher als Pakete-Sammlung denn als Framework zu sehen. Hier spiegelt sich die "Paketizität" ja auch beim Download wider.

echo "$verabschiedung $name";