PhpDocumentator
Dokumentierter Quellcode

Übersicht behalten

PhpDocumentator

Eine Dokumentation des Quelltextes lohnt sich umso mehr, je größer ein Projekt ist. Denn hat man erst einmal zehn oder zwanzig Dateien mit Klassen und Funktionen, wird es sehr schnell unübersichtlich. Möglicherweise wissen Sie zu einem späteren Zeitpunkt nicht einmal mehr, in welcher Datei eine Methode oder Variable überhaupt steckt.

Der PhpDocumentor hilft an dieser Stelle. Das als Open Source veröffentlichte Programmpaket durchsucht PHP-Dateien nach Klassen, Funktionen und Kommentaren. So entsteht im Handumdrehen eine Übersicht über das komplette Programmierprojekt.

Kommentare

PhpDocumentator

Noch besser wird das Ergebnis, wenn Sie ein paar Standards beim Kommentieren einhalten. Dabei ist das – bei Javadoc entlehnte – Prinzip recht einfach. Kommentare werden immer mit /** eingeleitet. Vor jeder Kommentarzeile steht ein *, den Abschluss bildet */. Ein Beispiel:


/**
* Ein Kommentartext
*/


Ein solcher Kommentar wird der nächstfolgenden Funktion oder Variablen zugerechnet und taucht in der Dokumentation als Beschreibung auf. Soll es ein wenig mehr Information sein? Dann brauchen Sie die speziellen Tags von PhpDocumentor. Ein Beispiel:


/**
* Überschrift anzeigen
* @author Max Muster
* @param string $strHead
* @param int $intGroesse Groesse der Schriftart
* @return string
*/
function showHeadline($strHead, $intGroesse) {
return "$strHead";
}


Die erste Zeile verwendet PhpDocumentor wie gehabt als Kurzbeschreibung. Darauf folgt der Name des Autors samt seiner E-Mail-Adresse in spitzen Klammern. Weiter geht es mit den Parametern. Mit @param deuten Sie an, welchen Datentyp die Parameter beinhalten und wie sie heißen. Zusätzlich können Sie wie in der zweiten @param-Zeile noch eine kurze Beschreibung des Parameters eingeben. @return gibt Aufschluss darüber, welchen Datentyp die Funktion zurückgibt.

Variablen

PhpDocumentator

Bei Variablen innerhalb von Klassen informiert PhpDocumentor auf Wunsch über den Typ von Variablen – zumindest über den Typ, den sich der Programmierer wünscht. Dazu allerdings ist ein spezielles Tag notwendig. Und das sieht folgendermaßen aus:


/**
* @var string Überschrift
*/
var $strHeadline


Den Namen der Variablen geben Sie im Kommentar nicht mit an. Allerdings wird es unübersichtlich, wenn man 20 Variablen deklariert – und dazu 80 Zeilen Quelltext braucht. Auf dieses Feature kann man zu Gunsten einer eindeutigen Schreibweise der Variablen notfalls verzichten.

Zusätzlich unterstützt PhpDocumentor Verknüpfungen und Querverweise zu anderen Seiten in der Dokumentation. Sie dürfen auch Versionsnummern oder Programmbeispiele mit in die Dokumentation aufnehmen. Weiterhin bindet das Programm Docbook-konforme Dateien als Tutorials ein. So können Sie zu Ihrer PHP-Applikation umfangreiche Tutorials erzeugen und anschließend als HTML-Seiten speichern.

Das Tool PhpDocumentor ist ein Muss für alle PHP-Profis. Sie können es kostenlos von der Seite www.phpdoc.org herunterladen.