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.

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.

Weblinks

• Erläuterungen für einen PHP-Kongress 2000