PHPDoc

aus Wikipedia, der freien Enzyklopädie
Wechseln zu: Navigation, Suche

PHPDoc ist ein Software-Dokumentationswerkzeug 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[Bearbeiten]

Gegeben ist eine fiktive Methode, deren Beschreibung, Parameter und Rückgabewert definiert werden sollen:

/**
 * Get all image nodes.
 *
 * @param \DOMDocument $document   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[Bearbeiten]

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[Bearbeiten]

Weblinks[Bearbeiten]

Einzelnachweise[Bearbeiten]

  1. phpdoc.de - About