PHPDoc
PHPDoc ist ein Format für Kommentar in PHP-Code in Anlehnung an Javadoc. Es dient dazu, Variablen, Funktionen, Methoden und Klassen in PHP-Quelltexten zu dokumentieren, um anhand dieser Angaben eine Dokumentation, etwa auf HTML-Basis, zu erstellen. Erschaffen wurde der Ausdruck etwa im Jahr 2000, als im Rahmen einer Präsentation ein an Javadoc angelehntes Dokumentationswerkzeug vorgestellt wurde, welches unter der PHP-Lizenz steht.[1]
Beispiel
Gegeben ist eine fiktive Methode, deren Beschreibung, Parameter und Rückgabewert definiert werden sollen:
/**
* Get all image nodes.
*
* @param \DOMNode $node The \DOMDocument instance
* @param boolean $strict If the document has to be valid
*
* @return \DOMNode
*/
public function getImageNodes(\DOMNode $node, $strict = true)
{
// ...
}
Die in Asterisken eingefassten Angaben zur Beschreibung der Methodenparameter sind dabei typisch für PHPDoc-Kommentare und müssen in dieser Formatierung bestehen. Im Beispiel werden mit Hilfe von @param die beiden Funktionsparameter definiert (in der Reihenfolge Datentyp, Variablenname, Kurze Erläuterung), außerdem wird der Rückgabe-Datentyp angegeben.
Nutzen
Anhand der Beschreibungen, etwa für eine Methode, kann ein PHPDoc-Parser eine API-Dokumentation generieren, die etwa erforderte Funktionsparameter anschaulich erläutert. Ein weiterer Vorteil ist, dass Entwicklungsumgebungen diese Kommentare erfassen und somit Code-Vervollständigung leisten. Außerdem warnen sie davor, wenn etwa ein Objekttyp übergeben wird, der nicht mit der Angabe des PHPDoc-Kommentars übereinstimmt.
Siehe auch
- phpDocumentor benutzt das Format PHPDoc.