Der PhpDocumentor durchsucht Dateien nach Klassen, Funktionen, Konstanten und Variablen und erstellt automatisch eine Dokumentation. Mit sog. DocBlocks kann man die einzelnen Programmelemente direkt im Quelltext beschreiben, der PhpDocumentor fügt die Informationen aus den DocBlocks dann in der Dokumentation zur entsprechenden Klasse, Funktion, o.Ä. hinzu.

Dadurch, dass die Dokumentation direkt im Quelltext geschieht, entstehen einige Vorteile. Die Dokumentation ist immer auf dem neusten Stand, was bei einer separaten Dokumentation nicht unbedingt der Fall ist. Außerdem ist sie immer vollständig, denn auch wenn man zu einem Element keine Beschreibung geschrieben hat, sind zumindest einige Informationen die PhpDocumentor aus dem Quelltext ausgelesen hat, in der Dokumentation enthalten.

Die wichtigsten Vorteile von PhpDocumentor:

• Die Dokumentation wird automatisch erstellt, PhpDocumentor nimmt einem viel Arbeit ab.
• Sie bleibt immer auf dem neusten Stand und ist immer vollständig.
• Dadurch das die Dokumentation direkt im Quelltext ist, sieht man auch beim Bearbeiten des Quelltextes sofort, was z.B. eine bestimmte Funktion macht.
• Es ist auch möglich auf Anleitungen zu verlinken oder Code in die Dokumentation einzubinden.
• Die Dokumentation kann in viele verschiedene Formate exportiert werden, z.B. als PDF oder CHM (Windows-Hilfedatei). Wenn man die Dokumentation im HTML-Format speichert, hat man die Wahl zwischen 15 verschiedenen Smarty-Vorlagen, und es ist auch möglich eigene Vorlagen oder Exporter zu schreiben.

Ein Beispiel einer komplett mit DocBlocks dokumentierten Datei findet sich hier.

Installation

Es gibt zwei Möglichkeiten PhpDocumentor zu installieren, entweder über PEAR, oder indem man es runterlädt und entpackt. Erstere ist einfacher. Wenn man kein PEAR hat, oder aus irgendeinem anderen Grund lieber die zweite Installationsvariante vorzieht: In der PhpDocumentor-Dokumentation findet sich eine Anleitung zur Installation ohne PEAR.

Installation mittels PEAR

Wenn man PhpDocumentor über die Kommandozeile verwenden möchte, genügt folgender Befehl zur Installation:

pear install --alldeps PhpDocumentor

Will man auch die Weboberfläche verwenden, muss vorher die Option data_dir der PEAR-Konfiguration verändert werden. Sie muss so angepasst werden, das sie den Pfad zum Dokumente-Verzeichnis des Webservers, das ist das Verzeichnis in dem die Webseiten/PHP-Skripte/etc. liegen, enthält.

pear config-set data_dir /pfad/zum/htdocs/verzeichnis/pear/

Anschließend installiert man PhpDocumentor mit obigem Befehl. Nun kann man auch die Weboberfläche verwenden, diese ist, wenn man obigen Befehl verwendet, unter http://localhost/pear/PhpDocumentor zu erreichen.

Die Benutzung von PhpDocumentor

Wenn PhpDocumentor angewiesen wird, ein Projekt zu dokumentieren, werden automatisch alle Elemente wie  Klassen, Funktionen, Variablen und Konstanten aus den Dateien ausgelesen und eine Übersicht erstellt. Eine solche Übersicht ist zwar hilfreich, sie ist aber noch viel nützlicher wenn die Funktion und die Eigenschaften der einzelnen Elemente noch näher erklärt werden.

Dazu verwendet man sog. DocBlocks, das sind spezielle Kommentare, die von PhpDocumentor ausgewertet werden. Ein DocBlock sieht aus wie ein mehrzeiliger Kommentar, wird aber mit /** anstatt von /* eingeleitet, und vor jeder Zeile steht ein Sternchen. Ein DocBlock bezieht sich immer auf das darauffolgende Element. Die erste Zeile ist eine kurze Beschreibung des Elements, durch eine Leerzeile getrennt kann auch noch eine längere Beschreibung geschrieben werden. Darauf können dann noch einige Parameter folgen die weitere Informationen geben.

  /**
   * Aendert den Namen des Films.
   * @param    string   $neuerName Der neue Name des Films.
   * @return   boolean  true bei Erfolg, false wenn ein Fehler aufgetreten ist.
   */
  public function aendereName($neuerName) {
    $this->name = $neuerName;
 
    // liefert true bei Erfolg, false bei Fehlern.
    $ergebnis = $datenbank->aendere($this->filmId, 'name', $neuerName);
 
    return $ergebnis;
  }

Im Beispiel folgen auf die Beschreibung der Funktion noch die beiden Parameter param und return, ersterer beschreibt einen Parameter der Funktion, letzterer den Rückgabewert. Ein Parameter beginnt immer mit einem @-Zeichen. Der entsprechende Teil der Dokumentation könnte dann zum Beispiel so aussehen:

PhpDocumentor erstellt eine Übersicht aller im Projekt vorkommenden Elemente und Dateien. Jedes Element lässt sich dabei auch noch in Kategorien, Pakete und Unterpakete einteilen, wodurch die Dokumentation etwas übersichtlicher wird. So könnte die Klasse Film beispielsweise Teil des Pakets Video sein, welches wiederum Teil von Medienbibliothek ist.

Es ist auch möglich den Autor eines Codes anzugeben, so weiß man, wen man ansprechen kann, wenn man eine Frage hat. Auch Informationen zum Urheberrecht lassen sich in den Quelltext einbauen.

/**
 * Stellt einen Film-Eintrag in der Bibliothek dar.
 *
 * Die Klasse Film bietet Funktionen für den Zugriff auf
 * die in der Bibliothek enthaltenen Informationen ueber
 * den Film.
 *
 * @author     Max Mustermann <maxmustermann@example.de>
 * @package    Medienbibliothek
 * @subpackage Video
 * @version    1.23
 * @copyright  Copyright (c) 2009 Max Mustermann
 * @todo       Die Funktion loeschen() funktioniert noch nicht richtig!
 */
class Film {
// ...

Sehr praktisch ist auch der Parameter todo, mit dem man Hinweise auf unfertige Funktionen, Fehler, oder andere Dinge die noch zu erledigen sind, geben kann.

Mit dem Parameter access ist es auch möglich festzulegen ob das Element in der Dokumentation vorkommen soll, so können zum Beispiel interne Funktionen einer Bibliothek ausgeblendet werden, die den Endanwender nicht interessieren. Für die Entwickler der Bibliothek kann dann eine separate Dokumentation generiert werden, welche diese Elemente dann auch enthält.

Eine Übersicht der wichtigsten Parameter

Eine Übersicht aller verfügbaren Parameter gibt es in der Dokumentation von PhpDocumentor.

Code einbinden

Manchmal möchte man eine Funktion oder Klasse direkt an einem Beispiel beschreiben, auch das ist kein Problem, denn mit dem <code>-Element lässt sich auch Quelltext direkt in die Beschreibung einbinden.

/**
   * Loescht den Film aus der Datenbank
   *
   * Diese Funktion wird wie folgt benutzt:
   * <code>
   * $ergebnis = $film->loeschen();
   * if (!$ergebnis) echo "Film konnte nicht geloescht werden!";
   * </code>
   * Und so weiter ...
   */

Externe Dokumentation

Bei sehr langen Beschreibungen ist es sinnvoll, diese auszulagern. Der Quelltext würde ziemlich unübersichtlich werden, wenn mittendrin umfassende Anleitungen zur Benutzung von bestimmten Funktionen oder Klassen stehen würden. Dazu können die Parameter @link und @tutorial verwendet werden. Wie das funktioniert wird im Handbuch vom PhpDocumentor erklärt.

Erstellen der Dokumentation

Die Dokumentation kann entweder über die Kommandozeile oder über die Weboberfläche erstellt werden.

Mit dem Kommandozeilen-Programm phpdoc

Die Bedienung von phpdoc ist im Grunde ganz einfach, ein Beispiel:

phpdoc -t dokumentation/ -d meinprojekt/

Der Befehl würde alle PHP-Dateien im Verzeichnis meinprojekt durchgehen, eine Dokumentation daraus erstellen, und diese im Verzeichnis dokumentation ablegen.

Mit dem Parameter -t <Verzeichnis> wird also angegeben, wo die Dokumentation gespeichert werden soll, -d <Verzeichnis> gibt ein Verzeichnis (oder mehrere, durch Kommas getrennt) an, das nach PHP-Dateien durchsucht werden soll. Mit -f <Datei>[,<Datei>, ...] kann man noch weitere Dateien angeben, die für die Dokumentation ausgewertet werden sollen.

Mittels -ti 'Titel der Dokumentation' lässt sich der Titel festlegen, mit -o <Format> lassen sich die Ausgabeformate bestimmen. Ein Beispiel:

phpdoc -ti 'Mein PHP-Projekt' -f beispiel.php -o html:smarty:hands,pdf:default:default -t docs/

Der Befehl würde eine Dokumentation für das Projekt mit dem Namen Mein PHP-Projekt erstellen. Es wird nur die Datei beispiel.php ausgewertet, die Dokumentation wird im PDF-Format und im HTML-Format, mit der Vorlage Smarty/HandS, erstellt.

Mit der Weboberfläche

Die Weboberfläche ist sogar noch einfacher zu bedienen, als die Kommandozeilen-Version. Unter Files gibt man die Dateien und Verzeichnisse an, die dokumentiert werden sollen. Unter Output wird bei Target eingetragen wo die Dokumentation gespeichert werden soll, mittels Output Format lässt sich festlegen in welchem Format (HTML, PDF, CHM, etc.) die Dokumentation erstellt werden soll, und welche Vorlage verwendet wird. Dabei ist es auch möglich gleich mehrere Ausgabeformate anzugeben. Unter Config lassen sich noch der Name des Projekts und ein paar andere Einstellungen konfigurieren. Mit einem Klick auf create (unten rechts) wird die Dokumentation erstellt.

/*
 * This function is cleaned from bugs with help from
 * the Metallica song “Seek and Destroy”
 * (IMHO the best song ever from Metallica)
 */

Mehr davon gibt es auf www.codecandies.com.