nicht angemeldet
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ß,