PHPDocumentor ist die Standardlösung für die Erzeugung von Entwicklerdokumentation aus PHP-Quelltexten heraus. Hierbei werden Formatierungsanweisungen in den Quelltext-Kommentaren verwendet, um beispielsweise Typ und Anzahl der Parameter einer Methode sowie deren Aufgabe und Rückgabewert zu dokumentieren. Diese Informationen werden von phpDocumentor aus dem Quelltext extrahiert und in unterschiedlichen Formaten aufbereitet.
Dank des PEAR-Installers gestaltet sich die Installation von phpDocumentor gewohnt einfach (Abbildung 13.1).
phpDocumentor unterstützt die Dokumentation von
Inklusionsanweisungen, Konstanten, Funktionen und Klassen sowie
deren Instanzvariablen und Methoden. phpDocumentor erwartet die
Dokumentation eines Codeelementes in einem Kommentar, der direkt
vor dem Element in DocBlock-Notation
(Beispiel 13.1)
zu schreiben ist. Ein DocBlock ist ein erweiterter PHP-Kommentar
im C++-Stil. Er wird mit /** eingeleitet. Ferner
beginnt jede weitere Zeile mit einem *.
Tabelle 13.1 zeigt die wichtigsten Tags, die phpDocumentor unterstützt.
Tabelle 13.1. Die wichtigsten Tags von phpDocumentor
| Tag | Beschreibung |
|---|---|
@abstract, @final und @static | Dokumentation von Klassen oder Methoden als abstrakt, final oder statisch. |
@access {public|protected|private} | Sichtbarkeit des dokumentierten Codeelementes. |
@param Typ $name Beschreibung | Dokumentation eines Parameters einer Funktion oder Methode. |
@return Typ Beschreibung | Dokumentation des Rückgabewertes einer Funktion oder Methode. |
@author und @copyright | Dokumentation von Autor und Urheberrechtsinformation für das Codeelement. |
@see | Fügt einen Verweis auf die Dokumentation eines anderen Codeelementes ein. |
@version | Dokumentiert die Version des Codeelementes. |
@since | Dokumentiert, seit welcher Version das Codeelement existiert. |
@deprecated | Markiert das dokumentierte Codeelement als ausgemustert. |
Beispiel 13.2 zeigt den Quelltext einer Klasse ohne Codekommentare.
Beispiel 13.2: Eine Klasse ohne Dokumentationskommentare
<?php
class Klasse {
private $variable;
public function setzeVariable($parameter) {
$this->variable = $parameter;
return $this->variable;
}
}
?>
Abbildung 13.2 zeigt
den Aufruf von phpDocumentor von der Kommandozeile aus. Der
Parameter -t . setzt das Ausgabeverzeichnis auf das
aktuelle Verzeichnis, über -f Klasse.php legen wir
die Eingabedatei fest.
Abbildung 13.3
zeigt die von phpDocumentor generierte Dokumentation für unsere Klasse.
Obwohl diese noch keine Codekommentare enthält, hat phpDocumentor
bereits einige Informationen aus dem Code extrahieren können. So
erhalten wir beispielsweise die Information, dass die Methode
setzeVariable() als public deklariert ist
und keinen Rückgabewert liefert.
Wir fügen nun sukzessiv Codekommentare zum Quelltext der Klasse hinzu. In Beispiel 13.3 ist der Codekommentar-Block für die Klassendeklaration zu sehen. Hier geben wir eine Beschreibung zur Aufgabe der Klasse sowie ein Beispiel für ihre Verwendung an. Schließlich machen wir Angaben darüber, wer die Klasse programmiert hat und zu welchem Paket und Unterpaket sie gehört.
Beispiel 13.3: Dokumentationskommentar für eine Klasse
<?php
/**
* Eine Klasse für die Demonstration von phpDocumentor.
*
* <code>
* <?php
* require_once 'Klasse.php';
*
* $objekt = new Klasse;
* $objekt->setzeVariable('test');
* ?>
* </code>
*
* @author Sebastian Bergmann <sb@sebastian-bergmann.de>
* @package PSMP5
* @subpackage phpDocumentor
*/
class Klasse {
// ...
}
?>
Beispiel 13.4 zeigt
den Codekommentar für die Instanzvariable $variable.
Durch die Angabe von @var string dokumentieren wir
hierbei für phpDocumentor, dass die Instanzvariable vom Typ String ist.
Beispiel 13.4: Dokumentationskommentar für eine Instanzvariable
<?php
class Klasse {
/**
* Eine Instanzvariable.
*
* @var string
* @access private
*/
private $variable;
// ...
}
?>
Beispiel 13.5 zeigt
den Codekommentar für die Methode setzeVariable().
Mit @param string $parameter und @return string
dokumentieren wir Typ und Zweck des Parameters sowie des Rückgabewertes.
Beispiel 13.5: Dokumentationskommentar für eine Methode
<?php
class Klasse {
// ...
/**
* Setzt die Variable 'variable' auf den übergebenen
* Parameter.
*
* @param string $parameter Parameter, auf den die
* Variable 'variable' gesetzt werden
* soll.
* @return string Der Wert, auf den die Variable
* 'variable' gesetzt wurde.
* @access public
*/
public function setzeVariable($parameter) {
$this->variable = $parameter;
return $this->variable;
}
}
?>Dank der Codekommentare ist phpDocumentor nun in der Lage, ausführlichere Code-Dokumentation für unsere Klasse zu erzeugen (Abbildung 13.4).
