13 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. PHPDOC-Pakete finden sich im Internet, wobei zwei Varianten zu unterscheiden sind:

Der phpDocumentor von http://phpdocu.sourceforge.net/ ist PHP-basiert und recht aktuell. Unter http://www.phpdoc.de/ gibt es zwar noch eine weitere Variante, diese wird aber offensichtlich schon lange nicht mehr weiterentwickelt; außerdem greift der phpDocumentor die wichtigsten Erweiterungen des Pioniers auf.
Unter http://www.callowayprints.com/phpdoc/ findet sich eine Java-basierte Lösung, die den Vorteil hat, daß sie auf das Original-JavaDoc zurückgreift und somit dessen umfangreiche Ausgabemöglichkeiten bietet.

Jede dieser Lösungen ist leider etwas anders und funktioniert auch unterschiedlich gut. Auf die Unterschiede gehe ich weiter unten noch näher ein.

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 Übersich 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 13.1 zu ersehen sind.

**Table:** 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.

1 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.

2 PHP-JavaDoc

Die meiner Meinung nach gelungenere Variante, die das JRE und damit auch das originale JavaDoc benutzt, ruft man im Installationsverzeichnis mit ./phpdoc.sh script1.inc script2.inc ... -d html -private auf (für Windows ./phpdoc.sh durch phpdoc ersetzen). Auch hier kann also ein neues Verzeichnis als Ziel bestimmt werden (das aber schon existieren muß). Der Parameter -private bewirkt übrigens, daß auch die Klassen- bzw. Instanzvariablen, die standardmäßig als private deklariert sind, berücksichtigt werden.

Da die Typisierung in PHP bekanntlich nicht so streng ist wie in Java, führt die in Java implementierte PHPDoc-Variante zwei Zusatz-Schlüsselworte ein, die dies kompensieren sollen -- dies ist übrigens auch der Hauptunterschied zwischen dem phpDocumentor, dessen eigene Syntax die Angabe des Typs direkt im @param-Schlüsselwort erlaubt, und PHP-JavaDoc. Für Klassen-/Instanzvariablen steht hier @type zur Verfügung. Bei Methoden bzw. Funktionen ist v.a. der Typ des Rückgabewerts interessant, weshalb auch @returns zusätzlich zum bereits bekannten @return definiert wurde. Während letzteres ja eine Angabe über den Inhalt des Rückgabewertes machen sollte, ist ersteres ausschließlich für den Typ verantwortlich. Da das Parsen des Codes letztendlich mittels JavaDoc geschieht, sollte man natürlich nicht String verwenden (was zu java.lang.String würde), sondern besser alles klein schreiben, was kein expliziter (selbstdefinierter) Objekttyp ist. In jedem Fall erwartet der JavaDoc-Parser als Rückgabetyp einen einfachen Identifier, so daß hier keine Angaben wie string/boolean für verschiedene Rückgabetyp-Möglichkeiten gemacht werden können.

Next: 5 Beispiele Up: 4 Einführung PHP Previous: 12 Fehlersuche

Christoph Reeg(http://reeg.net/)