22.2 PHPDocumentor 

PhpDocumentor ist ein phantastisches Tool, das Dokumentationen für Sie generiert, und es ist das Standardtool, das im PEAR-Projekt zum Generieren von Dokumentationen genutzt wird.

Daher ist PhpDocumentor auch nicht dazu gedacht, in Ihre Programme integriert zu werden, sondern stellt ein fertiges Programm dar, das eigenständig genutzt werden kann. Auch bei diesem Paket gilt, dass die Dokumentation auf der eigenen Homepage besser ist als die, die auf den PEAR-Seiten zu finden ist. Die Homepage finden Sie unter der URL http://www.phpdoc.org.

In der aktuellen Version kennt das Programm alle Sprachkonstrukte, die in PHP 5 neu hinzugekommen sind. Die Erkennung dieser Features setzt allerdings voraus, dass das Programm unter PHP 5 ausgeführt wird.

Grundsätzlich gilt, dass PhpDocumentor viele Dinge schon von allein erkennt. So werden beispielsweise Klassen, Methoden oder Eigenschaften erkannt, ohne dass Sie diese bei PhpDocumentor »anmelden« müssen oder Ähnliches.

Möchten Sie allerdings eine komplette, wirklich brauchbare Dokumentation generieren lassen, so ist es nötig, dass Sie so genannte DocBlocks einfügen. Dabei handelt es sich um Kommentare, in denen Sie eine Klasse, Methode oder Ähnliches erläutern.

Um Ihnen einen Eindruck von der Leistungsfähigkeit zu vermitteln, wurde im folgenden Beispiel eine Dokumentation für diese beiden Klassen generiert:

class person 
{ 
   protected $Vorname; 
   protected $Nachname; 
 
   public function __construct($v, $n) 
   { 
      $this->Vorname=$v; 
      $this->Nachname=$n; 
   } 
 
   public function getName() 
   { 
      echo "Name:_$ret_            $this->Vorname 
            $this->Nachname"; 
   } 
} 
 
class mitarbeiter extends person 
{ 
   private $persnr; 
 
   public function __construct ($v,$n,$p) 
   { 
      parent::__construct($v,$n); 
      $this->persnr=$p; 
   } 
}

Listing 22.3 Beispielklassen für die Dokumentation

Diese Klassen wurden in der Datei klassen.php abgelegt. Um nun eine Dokumentation erstellen zu lassen, rufen Sie das Script phpdoc über die Kommandozeile auf:

phpdoc -f klasse.php -t ./doku

Mit dem Parameter -f können Sie den Namen der Datei definieren, die dokumentiert werden soll. Möchten Sie alle Dateien in einem Unterverzeichnis automatisch dokumentieren lassen, nutzen Sie den Parameter -d und geben danach den Namen des Verzeichnisses an. -t bezeichnet den Namen des Verzeichnisses, in dem die neue Dokumentation abgelegt werden soll. Existiert das Verzeichnis nicht, so wird es automatisch angelegt. Bitte beachten Sie, dass Sie bzw. der Nutzer, unter dem Sie die Anwendung ausführen, Schreibrechte auf das Verzeichnis benötigen.

Einen Ausschnitt aus der generierten Dokumentation sehen Sie in Abbildung 22.1.

Abbildung 22.1 Generierte Dokumentation

In Abbildung 22.1 ist ein Teil der Dokumentation der Klasse mitarbeiter dargestellt. Wie Sie sehen können, wird der Konstruktor automatisch als solcher erkannt und auch die Tatsache, dass in dieser Klasse der Konstruktor der Elternklasse überschrieben wird.

Wie ich schon erwähnt habe, entfaltet das Programm seine volle Leistungsfähigkeit erst dann, wenn Sie DocBlocks einfügen. Diese Kommentare sehen beispielsweise aus wie dieser Abschnitt:

/** 
* Konstruktor der Klasse mitarbeiter 
* 
* Dieser Konstruktor ueberschreibt den Kunstruktor der 
* Elternklasse person. Die Methode nutzt aber den Konstruktor 
* der Elternklasse, um das Objekt korrekt zu initialisieren_$ret_* 
* @param string $v Vorname der Person 
* @param string $n Nachname der Person 
* @param integer $p Personalnummer des Mitarbeiters 
* @see person::__construct() 
*/

Die Dokumentation, die aus diesem DocBlock generiert wird, sehen Sie in Abbildung 22.2.

Abbildung 22.2 Dokumentation aus DocBlock

Der Block wird also mit /** eingeleitet, und jede einzelne Zeile beginnt mit einem weiteren Stern, bis der Block in der letzten Zeile dann mit */ abgeschlossen wird.

Die erste Zeile ist eine kurze Beschreibung zu dem, was die Funktion oder Klasse leistet. Es sollte wirklich nur eine kurze Zusammenfassung sein, da diese in Übersichten und Ähnlichem genutzt wird.

Danach können und sollten Sie eine ausführlichere Beschreibung erstellen, die den Sinn und Zweck des Konstrukts ausführlich erläutert. Diese Erläuterung sollten Sie immer mit einer Leerzeile von der Kurzbeschreibung abtrennen, da das System sonst nicht eindeutig erkennen kann, wie die Texte aufzuteilen sind.

Danach folgen einige Zeilen, die jeweils mit einem @ eingeleitet werden. Hierbei handelt es sich um Tags, die das System kennt. Ein Tag beginnt immer mit einem @ und hat eine spezielle Bedeutung innerhalb des DocBlocks. So beschreibt ein @param jeweils einen Parameter, wie Sie sehen können, und das Tag @see leitet einen Verweis auf eine andere Stelle in der Dokumentation ein.

Nachfolgend finden Sie die wichtigsten Tags:

• @abstract Dieses Tag markiert eine abstrakte Klasse und erfordert keine weiteren Parameter. Da in PHP 5 abstrakte Klassen definiert werden können, ist es nur für PHP 4-Code gültig.

• @access Definiert, welcher Zugriffsmodifikator für eine Methode oder Eigenschaft gilt, und erwartet einen der Parameter private, protected oder public. Elemente, die als private ausgewiesen sind, werden nicht in die Dokumentation aufgenommen, solange phpdoc nicht mit dem Parameter -pp aufgerufen wird. Auch dieses Tag sollte nur mit PHP 4-Code genutzt werden.

• @author Erwartet den Namen des Programmierers als Parameter und macht üblicherweise nur in Kombination mit einer Klassen- oder Methodenbeschreibung Sinn.

• @package  / @category Mit diesen beiden Tags können Sie die Quelltext-Dateien Ihrer Applikationen organisieren. Pakete stellen hierbei eine übergeordnete Organisationseinheit dar, die noch in Kategorien unterteilt werden kann.

/** 
* @package dbSchnittstellen 
* @category mySqlSchnittstelle 
*/

• • sorgt dafür, dass eine Datei zum Paket dbSchnittstelle und darin zur Kategorie mySqlSchnittstelle gehört.

• @copyright Bekommt als Parameter einen Namen übergeben, der definiert, bei wem das Copyright an dem folgenden Abschnitt liegt.

• @deprecated Dieses Tag wird genutzt, um Methoden oder Klassen zu markieren, die veraltet sind und nicht mehr genutzt werden sollten.

• @example Bekommt einen relativen oder absoluten Link zu einer Datei übergeben, die ein Beispiel zur Nutzung der Methode oder Klasse enthält. Nutzen Sie einen relativen Pfad, können Sie beim Aufruf von phpDoc mit dem Parameter -ed ein Basis-Verzeichnis angeben. Der Quelltext der Beispieldatei wird eingelesen und in die Dokumentation eingebunden.

• @final Dient dazu, eine Methode oder Klasse in der Dokumentation als final zu markieren. Sollte nur mit PHP 4 genutzt werden, da in PHP 5 das Schlüsselwort final deklariert ist.

• @filesource Dieses Tag kann nur auf Dateiebene genutzt werden und sorgt dafür, dass der Quelltext der Datei mit in die Dokumentation eingebunden wird.

• @global Mit Hilfe dieses Tags können Sie eine global definierte Variable bzw. einen Zugriff auf eine globale Variable aus einer Methode oder Funktion heraus dokumentieren.

• @name Dieses Tag dient dazu, eine globale Variable für die Dokumentation umzubenennen, um die Lesbarkeit der Dokumentation zu erhöhen. Das Tag wird in einem DocBlock genutzt, der die Deklaration einer globalen Variable erläutert.

/** 
* @name $foo 
* @global $GLOBALS['foo'] 
*/ 
$GLOBALS['foo'] = 'bar';

• • Wird in einer Funktion nun auf $foo zugegriffen, kann phpDocumentor den Bezug herstellen.

• @ignore Möchten Sie verhindern, dass ein Abschnitt dokumentiert wird, nutzen Sie einfach dieses Tag in dem dazugehörigen DocBlock. Das kann sehr hilfreich sein, wenn Sie eine Methode oder Eigenschaft, die als private bzw. protected deklariert ist, nicht in die Dokumentation aufnehmen wollen.

• @internal Der Text, der nach diesem Tag steht, wird nicht mit in die Dokumentation übernommen, solange phpdoc nicht mit dem Parameter -pp aufgerufen wird. So markierte Texte sind üblicherweise für eine interne Entwicklerdokumentation gedacht.

• @license Hiermit können Sie festlegen, unter welcher Lizenz (also PHP, Apache, BSD o. Ä.) ein Paket oder eine Klasse zur Verfügung gestellt wird.

• @link Nach diesem Tag können Sie eine komplette URL angeben, die dann als Link in das Dokument eingefügt wird.

• @param Mithilfe dieses Tags haben Sie die Möglichkeit, Parameter zu beschreiben, die für den Aufruf einer Funktion oder Methode übergeben werden müssen. Für jeden Parameter folgt nach dem Tag der erwartete Datentyp sowie der Name des Parameters. Ist der erwartete Datentyp nicht eindeutig festzulegen, weil beispielsweise sowohl ein Array als auch ein String akzeptiert wird, können Sie als Datentyp mixed angeben.

• @return Nach diesem Tag können Sie den Datentyp des Rückgabewerts einer Funktion oder Methode angeben. Zusätzlich ist es möglich, danach noch eine kurze Beschreibung anzugeben, die in die Dokumentation übernommen wird. Hat die Funktion bzw. Methode keinen Rückgabewert, so geben Sie void als Datentyp an.

• @see Hiermit wird ein Verweis auf einen anderen Abschnitt in der Dokumentation angelegt. Das ist immer dann hilfreich, wenn Sie beispielsweise eine Wrapper-Funktion angelegt haben, also eine Funktion, die nichts anderes macht, als eine andere Funktion aufzurufen.

• • Möchten Sie auf eine Funktion verweisen, geben Sie einfach den Namen der Funktion, gefolgt von einem Paar runder Klammern (  ), an. Der Name einer Variable bzw. Eigenschaft wird durch ein Dollarzeichen am Anfang verdeutlicht. Um Bezug auf eine Eigenschaft oder Methode in einer bestimmten Klasse zu nehmen, schreiben Sie den Namen der Klasse, gefolgt vom Scope-Operator ::, also z. B. @see myClass::myMethod().

• @since Das Tag @since soll genutzt werden, um zu deklarieren, seit welcher Version des Quelltextes das nachfolgende Konstrukt enthalten ist. Wenn Sie @since nutzen, sollten Sie nicht vergessen, die aktuelle Version mit @version zu deklarieren.

• @static Dieses Tag sagt aus, dass die Methode oder Eigenschaft, auf die sich der aktuelle DocBlock bezieht, statisch ist, also aufgerufen werden kann, ohne dass vorher ein Objekt instanziiert wurde. Da in PHP 5 ein entsprechendes Schlüsselwort vorhanden ist, sollte dieses Tag nur bei der Dokumentation von PHP 4-Code Verwendung finden.

• @staticvar Wie @static, nur dass sich dieses Tag auf eine Eigenschaft bezieht.

• @todo Hiermit können Sie Punkte auflisten, die noch implementiert oder nachgebessert werden sollen.

• @uses Mit diesem Tag können Sie ähnlich wie mit @see einen Link auf ein anderes Element anlegen. In diesem Fall besteht der logische Bezug darin, dass die aktuell dokumentierte Methode die Eigenschaft oder Methode nutzt, auf die verwiesen wird.

• @var Dieses Tag dient dazu, eine Eigenschaft zu beschreiben. Es wird in einem DocBlock direkt vor der Eigenschaft genutzt und bekommt den gewünschten bzw. erwarteten Datentyp der Eigenschaft als Variable übergeben. Zusätzlich können Sie danach noch eine Erläuterung angeben.

• @version Nach diesem Tag wird die Version des Pakets, der Klasse oder der Methode angegeben, in der sie vorliegt.

In Tabelle 22.2 finden Sie eine Zusammenfassung, welches Tag bei welcher Art DocBlock genutzt werden darf.

Darüber hinaus können Sie die Beschreibungen auch noch mit Tags formatieren, die an HTML angelehnt sind. Eine Liste dieser Tags finden Sie in Tabelle 22.3.

Nachdem Sie nun wissen, wie die Dokumentation im Quellcode aufgebaut werden kann, möchte ich noch kurz auf einige Kommandozeilenoptionen eingehen, die Sie in Tabelle 22.4 und Tabelle 22.5 finden.

Des Weiteren kenn das System den Parameter -o, mit dem Sie festlegen können, in welchem Format die Ausgabe erfolgen soll.

Möchten Sie einen Überblick darüber erhalten, wie diese Formatierungen dargestellt werden, finden Sie unter http://manual.phpdoc.org/ entsprechende Beispiele.