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

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 

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

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