phpDocumentor

PHPDOC

Beim Programmieren, unabhängig von der verwendeten Sprache, ist nicht nur die Funktionalität und Effizienz (Qualität) des Codes wichtig, sondern meist auch die Verständlichkeit und Wiederverwendbarkeit. Das liegt darin begründet, daß teilweise mehrere Programmierer an einem Projekt arbeiten, zu dem der jeweilige Quelltext gehört; auch wird oft der Code stetig erweitert und verbessert oder es müssen Fehler gefunden und behoben werden.

In jedem Fall ist es also notwendig, daß der Code übersichtlich ist. Darüber hinaus ist es jedoch unerläßlich, den Quelltext ausführlich zu kommentieren. I.A. ist es hier dem jeweiligen Programmierer überlassen, wie er dies anstellt. Es hat sich allerdings gezeigt, daß eine standardisierte Vorgehensweise beim Kommentieren von Vorteil sein kann: Jeder Programmierer braucht die Syntax dieses Standards nur einmal erlernen und kann ihn dann sowohl selbst anwenden als auch schnell wiedererkennen, wenn es gilt, Quelltexte anderer zu verstehen.

Mit der Programmiersprache Java wurde ein solcher Standard eingeführt und JavaDoc getauft. Dem JDK liegt ein gleichnamiges Programm bei, das beliebige Klassen - Java ist eine durch und durch objektorientierte Sprache - durchparst und die enthaltenen standardisierten Kommentare so aufbereitet, daß eine HTML-Übersicht entsteht, die ebenfalls eine einheitliche Form aufweist: Die offizielle Java-Dokumentation wird ebenfalls mit JavaDoc erstellt.

Einige PHP-Programmierer haben diese Idee aufgegriffen und für die Scriptsprache angepaßt. Dabei herausgekommen ist PHPDOC - eine standardisierte Methode, PHP-Funktionen und Klassen zu kommentieren. Mit dem PHPDOC-Programm lassen sich dafür, ganz ähnlich wie mit JavaDoc, HTML-Übersichten erzeugen. Doch auch ohne das PHPDOC-Programm einzusetzen, wird der Code bei sachgemäßer Anwendung von PHPDOC sehr viel übersichtlicher. Es finden sich im Internet verschiedene PHPDOC-Pakete, wobei folgende Varianten zu unterscheiden sind:

Der phpDocumentor von http://www.phpdoc.org/ ist PHP-basiert und recht aktuell. Er scheint der einzige zu sein, der noch weitergepflegt wird.
Unter http://www.phpdoc.de/, http://sourceforge.net/projects/phpdoc/ und http://wwpakis.free.fr/php3/phpdoc/index_en.html gibt es noch eine weitere Varianten, diese werden aber offensichtlich schon lange nicht mehr weiterentwickelt.
Es gibt von Christian Calloway eine Java-basierte Lösung, die den Vorteil hat, daß sie auf das Original-JavaDoc zurückgreift und somit dessen umfangreiche Ausgabemöglichkeiten bietet. Allerdings gibt es die Webseite nicht mehr und Google findet keine neue.
In den neueren Versionen unterstützt auch Doxygen (http://www.doxygen.org/) PHP.

Jede dieser Lösungen ist leider etwas anders und funktioniert auch unterschiedlich gut. Auf die Unterschiede gehe ich weiter unten noch näher ein, wobei ich nur den phpDocumentor im folgenden betrachten werde.

Doch nun zur Vorgehensweise. Grundsätzlich stehen alle PHPDOC-Kommentare in C-Kommentarzeichen (/* C-Kommentar */); an das einleitende Zeichen wird jedoch in leichter Abwandlung ein zusätzlicher Stern angehängt: /** PHPDOC-Kommentar */

Das folgende, etwas komplexere Beispiel zeigt einen typischen PHPDOC-Kommentar für die ebenfalls exemplarische Funktion foo.

/**
  * foo: liefert -$bar zurück.
  *
  * @author     Jens Hatlak
  * @version    1.0
  * @param      $bar     Ein beliebiger Wert
  * @return     Der negative Eingabewert
  */
  function foo($bar) {
    return -$bar;
  }

Da erst */ den mit /** begonnen Kommentar wieder beendet, kann dazwischen alles andere stehen, auch einzelne Sterne * wie am Anfang jeder Folgezeile; sie dienen der besseren Abgrenzung des Kommentars vom Code. Üblicherweise beginnt der Kommentar dann auch in der zweiten Zeile mit der Beschreibung der Funktion/Klasse/Methode. Der erste Satz wird auch in der Übersicht genutzt und der Rest erscheint dann bei der eigentlichen Beschreibung. Diese kann sich über mehrere Zeilen hinziehen und sollte die Funktionalität des zu kommentierenden Folgecodes im Kern dokumentieren.

Nach einer zusätzlichen ,,Leerzeile`` folgen dann die einzelnen Angaben zur Codebeschreibung. Hierzu werden Schlüsselworte benutzt, die grundsätzlich mit einem @ eingeleitet werden und ansonsten aus der Tabelle 14.1 zu ersehen sind.

**Tabelle 14.1:** PHPDOC-Schlüsselworte
Schlüsselwort	Bedeutung
@author	Autor des Codeabschnitts
@version	Version des Codeabschnitts
@since	eine Version oder ein Datum
@access	Zugriffsrechte: private oder public
@copyright	z.B. Name und Datum
@see	zu verlinkendes, ebenfalls dokumentierbares Element
@link	eine weiterführende URL
@param	Parameter (Wert und Typ, ggf. auch Angabe von ,,optional``) der Funktion bzw. Methode in der Reihenfolge der An- bzw. Übergabe
@return	Typ des Rückgabewerts der Funktion bzw. Methode

In JavaDoc gibt es übrigens noch die Schlüsselworte @deprecated, @exception und @throws sowie @package und @subpackage, die allerdings in PHPDOC in Ermangelung entsprechender Konstrukte in PHP nicht benötigt werden. Da PHP (zumindest in der aktuellen Version 4.x) keine Zugriffsrechte kennt, macht auch die Verwendung des @access-Schlüsselwortes entsprechend wenig Sinn.

phpDocumentor

Ein Aufruf des phpDocumentors, der derzeit nur unter Linux/Unix lauffähig ist, erfolgt z.B. mit phpdoc -f script.php -d html - das würde die Datei script.php im aktuellen Verzeichnis parsen und die HTML-Übersicht im (ggf. neu zu erstellenden) Unterverzeichnis html erzeugen.

Christoph Reeg