nicht angemeldet
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.
- 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";