Photoshop
Cinema 4d
Fotografie
Weitere Grafiksoftware
HTML / CSS
JavaScript
Flash
PHP
Webserver
Sonstige
Einführung in phpdoc (PHP Tutorial)
Tutorial erstellt von mstrauss in 1.4.2, letzte Änderung am 18.11.2008
Dieses Tutorial erklärt die Verwendung von phpdocumentor.
phpdocumentor ist eine Bibliothek, um automatisiert eine technische Dokumentation (API) von phpbasierten Projekten zu erstellen.
Nach erfolgreicher Erstellung wird dem User eine API der kompletten Anwendung zur Verfügung gestellt. Dabei kann die Dokumentation in verschiedenen Formaten erzeugt werden (HTML, PDF, CHM, etc.).
Die phpdoc-API ist natürlich mit phpdoc selbst erstellt und zeigt somit ein gutes Beispiel, wie eine solche API aussehen kann. Siehe hierzu: http://manual.phpdoc.org/HTMLframesConverter/default/
Da die Erzeugung der Dokumentation einige Ressourcen bindet und weitreichende Schreibrechte benötigt, sollte phpdocumentor auf einem Entwicklungssystem installiert werden.
Die aktuellen Sourcen findet man unter: http://www.phpdoc.org/
Es gibt zwei Möglichkeiten, die Dokumenationen zu erzeugen.
Die hier vorgenommene Beschreibung bezieht sich auf das Web-Interface. Im WebInterface besteht die Möglichkeit, die Konfiguration manuell einzugeben oder aber, eine bereits definierte Konfigurationsdatei zu verwenden, um immer wiederkehrende Aktualisierungen der Dokumentation zu vereinfachen.
Am besten kopiert man sich eine bestehende Config-Datei (im Verzeichnis /user/default.ini) und passt die entsprechenden Zeilen nach seinen Bedürfnissen an. Folgende Zeilen habe ich für meine Dokumentation angepasst:
Code:
Unter der Einstellung ignore kann auch mit Wildcards gearbeitet werden, z.B. test*.php
Um die Dokumentation mithilfe der Konfigurationsdatei zu erstellen, geht man wie folgt vor:
Die erstellte Dokumentation kann unter http://deinedomain/deine-doku/ aufgerufen werden (siehe hierzu den Punkt "target" in der Konfigurationsdatei).
Um die Dokumentation durch phpdocumentor erstellen zu lassen, muss der Quellcode mit Kommentaren versehen werden.
Somit wird nicht nur eine Dokumentation erzeugt, sondern der Entwickler dokumentiert zugleich den Quellcode.
Es wird folgendermassen dokumentiert:
Zuerst wird die Datei als solche dokumentiert. Dort wird eine kurze Beschreibung abgegeben und Grundinformationen wie der Autor, Copyright, Version und Erstellungsdatum.
Beispiel:
Code:
Die @-Funktionen dienen der Formatierung für die Ausgabe der API.
Eine Funktion wird folgendermaßen dokumentiert. Direkt vor der Funktion sind die Kommentare einzutragen.
Beispiel:
Code:
Zur Erläuterung:
Zeile 2: Überschrift für Funktion
Zeile 4-5: Beschreibung der Funktion
Zeile 7-10: Erklärung der Paramter, die der Funktion mitgegeben werden. Syntax "@param Variablentyp Variable Beschreibung"
Zeile 12-14: @todo legt eine ToDo Liste an. Alle ToDo's innerhalb der gesamten Dokumentation werden zusätzlich gesammelt in einer TODO-Datei abgelegt. Eine nützliche Funktion, wenn man im Team arbeitet.
Beispiel für die Dokumentation des Konstruktors
Code:
Beispiel für Methode mit Return
Code:
Alle Möglichkeiten der Dokumentation sind in der beigefügten Hilfe sehr gut erklärt. Die Stärken von phpdoc kommen vor allem zum Vorschein, wenn man objektorientiert programmiert.
Viel Spass beim Ausprobieren.
>> Allgemeine Fragen oder Probleme mit dem Tutorial? Hier gehts zum Forum!
phpdocumentor ist eine Bibliothek, um automatisiert eine technische Dokumentation (API) von phpbasierten Projekten zu erstellen.
Nach erfolgreicher Erstellung wird dem User eine API der kompletten Anwendung zur Verfügung gestellt. Dabei kann die Dokumentation in verschiedenen Formaten erzeugt werden (HTML, PDF, CHM, etc.).
Die phpdoc-API ist natürlich mit phpdoc selbst erstellt und zeigt somit ein gutes Beispiel, wie eine solche API aussehen kann. Siehe hierzu: http://manual.phpdoc.org/HTMLframesConverter/default/
Installation
Da die Erzeugung der Dokumentation einige Ressourcen bindet und weitreichende Schreibrechte benötigt, sollte phpdocumentor auf einem Entwicklungssystem installiert werden.
Die aktuellen Sourcen findet man unter: http://www.phpdoc.org/
Erstellung Dokumentation
Es gibt zwei Möglichkeiten, die Dokumenationen zu erzeugen.
- Aufruf über Konsole
- Aufruf über Web-Interface
Die hier vorgenommene Beschreibung bezieht sich auf das Web-Interface. Im WebInterface besteht die Möglichkeit, die Konfiguration manuell einzugeben oder aber, eine bereits definierte Konfigurationsdatei zu verwenden, um immer wiederkehrende Aktualisierungen der Dokumentation zu vereinfachen.
Am besten kopiert man sich eine bestehende Config-Datei (im Verzeichnis /user/default.ini) und passt die entsprechenden Zeilen nach seinen Bedürfnissen an. Folgende Zeilen habe ich für meine Dokumentation angepasst:
Code:
title = Test-Titel
defaultpackagename = testpackage
target = /pfad/unter/der/die/doku/zu/erreichen/ist
directory = /pfad/des/codes/der/zu/dokumentieren/ist
ignore = Alle Verzeichnisse und Dateien, die nicht dokumentiert werden sollen (z.B. temp-Ordner, 2rd Party Libraries, etc)
output=HTML:frames:default
defaultpackagename = testpackage
target = /pfad/unter/der/die/doku/zu/erreichen/ist
directory = /pfad/des/codes/der/zu/dokumentieren/ist
ignore = Alle Verzeichnisse und Dateien, die nicht dokumentiert werden sollen (z.B. temp-Ordner, 2rd Party Libraries, etc)
output=HTML:frames:default
Unter der Einstellung ignore kann auch mit Wildcards gearbeitet werden, z.B. test*.php
Um die Dokumentation mithilfe der Konfigurationsdatei zu erstellen, geht man wie folgt vor:
- Aufruf von phpdocumentor über http://deine.url.com/deinpfad
- Auswahl Menüpunkt "Config"
- Die Konfigurationsdatei "deineconfig.ini" auswählen und mit GO bestätigen. Im unteren Teil des Browsers ist eine Art Monitor, der die aktuellen Stand der Dokumentationserstellung protokolliert. Ist die Dokumentation fertiggestellt, erscheint "COMPLETED".
Die erstellte Dokumentation kann unter http://deinedomain/deine-doku/ aufgerufen werden (siehe hierzu den Punkt "target" in der Konfigurationsdatei).
Syntax zur Erstellung der Dokumentation
Um die Dokumentation durch phpdocumentor erstellen zu lassen, muss der Quellcode mit Kommentaren versehen werden.
Somit wird nicht nur eine Dokumentation erzeugt, sondern der Entwickler dokumentiert zugleich den Quellcode.
Es wird folgendermassen dokumentiert:
1. Dateiheader
Zuerst wird die Datei als solche dokumentiert. Dort wird eine kurze Beschreibung abgegeben und Grundinformationen wie der Autor, Copyright, Version und Erstellungsdatum.
Beispiel:
Code:
/**
* Datei mit Funktionen rund um das Logging von PHP-Scripten
*
* Die Datei enthaelt Funktionen, die das Logging von Fehler und Warnungen
* in einer Log-Datei und als Benachrichtung per eMail moeglich machen.
* Dabei wird das bestehende Error-Handling von PHP benutzt und angepasst.
*
* @author Markus Strauss (markus.strauss@strauss-esolutions.de)
* @copyright Copyright 2007, strauss esolutions
* @version 1.0
* @since 10.11.2008
*
*/
* Datei mit Funktionen rund um das Logging von PHP-Scripten
*
* Die Datei enthaelt Funktionen, die das Logging von Fehler und Warnungen
* in einer Log-Datei und als Benachrichtung per eMail moeglich machen.
* Dabei wird das bestehende Error-Handling von PHP benutzt und angepasst.
*
* @author Markus Strauss (markus.strauss@strauss-esolutions.de)
* @copyright Copyright 2007, strauss esolutions
* @version 1.0
* @since 10.11.2008
*
*/
Die @-Funktionen dienen der Formatierung für die Ausgabe der API.
2. Funktionen
Eine Funktion wird folgendermaßen dokumentiert. Direkt vor der Funktion sind die Kommentare einzutragen.
Beispiel:
Code:
/**
* Funktion, die Fehlermeldung in Logfile schreibt
*
* Dies Funktion wird aufgerufen, wenn ein Fehler beim Ausfuehren eines Scripts auftritt.
* Dabei wird die Fehlermeldung in ein Logfile geschrieben und eine eMail mit der Fehlermeldung erzeugt
*
* @param integer $errno Nummer der PHP-Fehlermeldung
* @param string $errmsg Meldung, die von PHP erzeugt wird
* @param string $filename Dateiname, in der der Fehler aufgetreten ist
* @param integer $linenum Zeilennummer, in der der Fehler aufgetreten ist
*
* @todo Noch zu erledigen:
* - Auslagerung der eMail-Adresse in cfg.inc.php
* - Auslagerung der LogdateiVariablen in cfg.inc.php
*/
* Funktion, die Fehlermeldung in Logfile schreibt
*
* Dies Funktion wird aufgerufen, wenn ein Fehler beim Ausfuehren eines Scripts auftritt.
* Dabei wird die Fehlermeldung in ein Logfile geschrieben und eine eMail mit der Fehlermeldung erzeugt
*
* @param integer $errno Nummer der PHP-Fehlermeldung
* @param string $errmsg Meldung, die von PHP erzeugt wird
* @param string $filename Dateiname, in der der Fehler aufgetreten ist
* @param integer $linenum Zeilennummer, in der der Fehler aufgetreten ist
*
* @todo Noch zu erledigen:
* - Auslagerung der eMail-Adresse in cfg.inc.php
* - Auslagerung der LogdateiVariablen in cfg.inc.php
*/
Zur Erläuterung:
Zeile 2: Überschrift für Funktion
Zeile 4-5: Beschreibung der Funktion
Zeile 7-10: Erklärung der Paramter, die der Funktion mitgegeben werden. Syntax "@param Variablentyp Variable Beschreibung"
Zeile 12-14: @todo legt eine ToDo Liste an. Alle ToDo's innerhalb der gesamten Dokumentation werden zusätzlich gesammelt in einer TODO-Datei abgelegt. Eine nützliche Funktion, wenn man im Team arbeitet.
3. Klassen
Beispiel für die Dokumentation des Konstruktors
Code:
/**
* Konstruktor der Klasse
*
* Setzt die Anzahl der Tage, die zu pruefen sind.
*
* @param obj $tpl Zuweisen des Templates
* @param obj $conn Zuweisen der bestehenden Datenbankverbindung
* @param integer Anzahl der Tage, die ueberprueft werden
*/
* Konstruktor der Klasse
*
* Setzt die Anzahl der Tage, die zu pruefen sind.
*
* @param obj $tpl Zuweisen des Templates
* @param obj $conn Zuweisen der bestehenden Datenbankverbindung
* @param integer Anzahl der Tage, die ueberprueft werden
*/
Beispiel für Methode mit Return
Code:
/**
* Gibt die Anzahl an Gesamttagen anhand von Werktagen $days aus
* @param integer $days
* @return integer $anzahltage Gibt die Anzahl der Arbeitstage zurueck
*/
* Gibt die Anzahl an Gesamttagen anhand von Werktagen $days aus
* @param integer $days
* @return integer $anzahltage Gibt die Anzahl der Arbeitstage zurueck
*/
Alle Möglichkeiten der Dokumentation sind in der beigefügten Hilfe sehr gut erklärt. Die Stärken von phpdoc kommen vor allem zum Vorschein, wenn man objektorientiert programmiert.
Viel Spass beim Ausprobieren.
>> Allgemeine Fragen oder Probleme mit dem Tutorial? Hier gehts zum Forum!
