Rheinwerk Computing < openbook > Rheinwerk Computing - Professionelle Bücher. Auch für Einsteiger.
Professionelle Bücher. Auch für Einsteiger.

Inhaltsverzeichnis
Geleitwort
Vorwort
1 PEAR – Einführung
2 Authentication
3 Caching
4 Date and Time
5 File Formats
6 HTTP
7 Internationalization
8 Mail
9 Networking
10 PHP
11 Text
12 Web Services
13 Benchmarking
14 Configuration
15 Database
16 File System
17 HTML
18 Images
19 Logging
20 Math
21 Numbers
22 Tools and Utilities
23 XML
24 Selbst Pakete erstellen
25 PECL
Index
Ihre Meinung?

Spacer
 <<   zurück
PHP PEAR von Carsten Möhrke
Anwendung und Entwicklung – Erweiterungen für PHP schreiben
Buch: PHP PEAR

PHP PEAR
798 S., 39,90 Euro
Rheinwerk Computing
ISBN 3-89842-580-0
gp 22 Tools and Utilities
  gp 22.1 PHPUnit2
  gp 22.2 PHPDocumentor


Rheinwerk Computing

22.2 PHPDocumentor  toptop


Besprochene Version: 1.3.0RC3 Lizenz: PHP-Lizenz 3.0
Klassendatei(en): -

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.


Tabelle 22.2 Gültigkeit von DocBlocks
DocBlock Zulässige Tags
Allgemein @access, @author, @copyright, @deprecated, @example, @ignore, @internal, @link, @see, @since, @version
Inkludierungen Dürfen nur über die Standard-Tags dokumentiert werden
Konstanten-Definition @name
Deklaration von Funktionen @global, @param, @return, @staticvar
Globale Variablen @name
Klassen-Deklarationen @package, @subpackage, @static
Eigenschaften @var, @staticvar
Methoden @global, @param, @return, @static

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.


Tabelle 22.3 Formatierungsmöglichkeiten
Tag Erläuterung
<b> </b> Hervorhebung eines Textabschnitts
<br> Zeilenumbruch
<code> </code> Ein Abschnitt mit Quellcode
<i> </i> Textabschnitt, der als wichtig markiert werden soll
<kbd> </kbd> Ein Text, der als Tastatureingabe kenntlich gemacht werden soll
<ul> </ul> Unsortierte Liste; die einzelnen Elemente müssen von <li></li> eingeschlossen werden.
<ol> </ol> Sortierte Liste; die einzelnen Elemente müssen von <li></li> eingeschlossen werden.
<pre> </pre> Ein vorformatierter Abschnitt
<samp> </samp> Der eingeschlossene Text soll als Beispiel kenntlich gemacht werden.
<var> </var> Mithilfe dieses Tag-Paares können Sie einen Variablennamen verdeutlichen.

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.


Tabelle 22.4 Kommandozeilenparameter
Parameter Bedeutung
-f file1.php Legt fest, für welche Datei(en) die Dokumentation erstellt wird. Mehrere Namen sind durch Kommata zu trennen.
-d verzeichnis Name eines Verzeichnisses, in dem die Dateien liegen, die dokumentiert werden sollen.
-i file1.php Definiert einen oder mehrere Dateinamen (getrennt durch Kommata), die bei der Erstellung der Dokumentation ignoriert werden sollen.
-po paket Mit dieser Option legen Sie fest, für welches Paket bzw. für welche Pakete, deren Namen durch Kommata getrennt werden, eine Ausgabe generiert wird. Die Namen der Pakete beziehen sich hierbei auf die Namen, die mit @package vergeben wurden.
-ti titel Legt den Titel der Dokumentation fest.
-dh Versteckte Verzeichnisse, die normalerweise ignoriert werden, mit einlesen.
-dn name Definiert den Namen für das Paket, das in der Dokumentation als Erstes angezeigt werden soll.
-pp Schaltet die Dokumentation von privaten und internen Elementen ein.

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


Tabelle 22.5 Ausgabeformate
Option Ausgabe in
HTML:frames:default HTML mit Frames, einfacher Aufbau
HTML:frames:earthli HTML mit Frames, aufwändiger gestaltet
HTML:frames:10133t HTML mit Frames, moderne Gestaltung
HTML:frames:phpdoc.de HTML mit Frames, Gestaltung angelehnt an phpdoc.de
HTML:frames:phphtmllib HTML mit Frames in dezenten Farben
HTML:frames:phpedit HTML mit Frames und Aufklappmenüs
HTML:Smarty:default HTML mit iFrames
HTML:Smarty:PHP HTML ohne Frames, Formatierung angelehnt an php.net
PDF:default:default PDF-Datei
CHM:default:default Windows Hilfe-Datei

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

 <<   zurück
     
  Zum Rheinwerk-Shop
Zum Rheinwerk-Shop: PHP PEAR
PHP PEAR
Jetzt Buch bestellen!
 Ihre Meinung?
Wie hat Ihnen das Openbook gefallen?
Ihre Meinung

 Buchtipps
Zum Rheinwerk-Shop: PHP 5.6 und MySQL 5.7






 PHP 5.6 und
 MySQL 5.7


Zum Rheinwerk-Shop: Einstieg in PHP 5.6 und MySQL 5.6






 Einstieg in PHP 5.6
 und MySQL 5.6


Zum Rheinwerk-Shop: Responsive Webdesign






 Responsive Webdesign


Zum Rheinwerk-Shop: Moderne Websites entwickeln






 Moderne Websites
 entwickeln


Zum Rheinwerk-Shop: MySQL 5.6






 MySQL 5.6


 Lieferung
Versandkostenfrei bestellen in Deutschland, Österreich und der Schweiz
InfoInfo








Copyright © Rheinwerk Verlag GmbH 2007
Für Ihren privaten Gebrauch dürfen Sie die Online-Version natürlich ausdrucken. Ansonsten unterliegt das Openbook denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt.
Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Nutzungsbestimmungen | Datenschutz | Impressum

Rheinwerk Verlag GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, service@rheinwerk-verlag.de

Cookie-Einstellungen ändern