Profil | Mitglieder | Registrieren | Start | Suche


PHP-Support.de » Programmierung » Sonstige Sprachen » [pear] phpDocumentor - Dokumentation erstellen    » Hallo Gast [Login | Registrieren]

Neues Thema | Antworten   

Autor Beitrag
Htaccess
Mitglied
Sehr guter User


Dabei seit: 22.08.2010
Herkunft: Deutschland
Posts: 693
     [pear] phpDocumentor - Dokumentation erstellen Zitat | Bearbeiten

PhpDocumentor, jeder Programmierer ist es lästig eine Dokumentation anzufertigen und diese dem Kunden mitzugeben, für welche er nicht bezahlen möchte. Aber es ist für die eigene Benutzung auch sehr wichtig, sich seinen Quellcode zu dokumentieren, da ein Programmierer sich nach Wochen sagen wird, was ist das denn für ein scheiß? Ist doch alles voll unlogisch und somit kommt der ganze Code einem sehr unlogisch vor. Nun da wir jedoch um eine Quellcode Dokumentation nicht herum kommen werden, müssen wir als erstes unseren Quellcode dokumentieren. Hierbei verwenden jedoch DocBlocks. DocBlocks sind Dokumentarblöcke die mit einem /** anstatt mit einem /* eingeleitet werden. Man bezeichnet diese Art der Dokumentation unter Fachidioten einfach nur als eine mehrzeilige Dokumentation für den Programmierer selbst. Jedoch aber entspricht dies dem nicht so, denn mit den sogenannten DocBlocks erkennt der phpDocumentor diese Blöcke und schreibt Sie mit in seine Dokumentation.

Eine Übersicht der wichtigsten Parameter
@access - Legt fest ob das Element in der Dokumentation vorkommen soll, standardmäßig public (wird angezeigt). Die Option private sorgt dafür, dass es nicht angezeigt wird.
@author - Der Autor des Codes.
@category, @package, @subpackage - Die @Package Medienbibliothek teilt das Projekt in mehrere Pakete ein, wodurch die Dokumentation übersichtlicher wird.
@copyright - Informationen zum Urheberrecht.
@deprecated - Bitte neue_funktion() benutzen. Kennzeichnet das Element als veraltet.
@param - Beschreibt einen Parameter, die erste Option gibt den erwarteten Typ an, die zweite den Namen des Parameters, der Rest ist die Beschreibung. Beispiel: @param integer $zahl Gibt eine Zahl zurück.
@var - Beschreibt den Datentyp einer Variable

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

Externe Dokumentation
Es ist durchaus Sinnvoll, bei sehr langen Beschreibungen diese auszulagern. Man stelle sich vor, wenn mittendrin umfassende Anleitungen zur Benutzung von bestimmten Klassen oder Funktionen stehen würden. Das würde den Code ziemlich unübersichtlich machen und Es wäre überhaupt nicht mehr mit schön anzusehen. Um dagegen vorzubeugen kann man eine externe Dokumentation definieren, die man mit den Parametern @link oder @tutorial definieren kann. Wie das funktioniert wird im Handbuch vom PhpDocumentor erklärt.

Der eigentliche Sinn dieses Tutorials
Nun nach vielem googlen hier und da ist es doch ein bisschen lästig, wenn man nichts sinnvolles findet. Ich beschränke mich hier auf die Erstellung der Dokumentation mit XAMPP Pear auf Windows.

Wir öffnen unser cmd Fenster als Administrator. Also Rechtsklick auf die cmd.exe und auf "Als Administrator ausführen" klicken.

Zunächst gehen wir in unsere xampp/php Installation. Dies machen wir mit folgendem Befehl
 PHP 
1:
cd C:\Pfad\zum\xampp\php\verzeichnis

Standard hierbei ist, dass es meist C:\xampp\php ist, wenn man keine wilden Einstellungen vorgenommen hat. Hat man diese jedoch gemacht dann achtet bitte darauf, dass ihr einen Backslash (\) für den Pfad verwendet und kein Slash (/), denn dies führt häufig zu missverständen und wird dann nicht gerade als positiv bewertet.

Nun, sind wir in unserem php-ordner unserer xampp installation, machen wir bei der allerersten ausführung von pear folgendes:

 PHP 
1:
2:
3:
4:
5:
pear uninstall phpDocumentor
pear update-channels
pear upgrade-all
pear config-set data_dir c:/xampp/htdocs/pear
pear install --force --alldeps phpDocumentor

In diesem Abschnitt haben wir zuerst den phpDocumentor deinstalliert, dann unsere channels geupdatet und alles geupgradet. Zum Schluss haben wir phpDocumentor wieder installiert. Wenn alles erfolgreich verlaufen ist, dann können wir uns nun unsere Dokumentation erstellen. Dies machen wir mit folgendem Befehl:

 PHP 
1:
phpdoc -d C:\xampp\htdocs\Pfad\des\Projektes\ -t C:\xampp\htdocs\Pfad\des\Projektes\docs


mit -d definieren wir den oder die Ordner, die durch ein Komma getrennt werden. Sprich unser Projekt, welches wir sorgfältig dokumentiert haben. Nun möchten die generierten Dateien jedoch auch wo gespeichert werden, dies definieren wir mit -t. Ich habe den gleichen Ordner verwendet, jedoch in dem Unterordner docs, der nicht erst erstellt werden muss, da dieser erstellt wird, wenn der Ordner noch nicht existiert.

Hat alles geklappt, haben wir nun eine automatisch generierte phpDocumentor Dokumentation für unserer eigenes Projekt in HTML Version.

Es gibt auch ein Webinterface von phpDocumentor, jedoch habe ich noch nicht herausgefunden, wie man diese erstellt, dass man darauf auch zugreifen kann. Mit phpDocumentor ist soviel möglich und wenn ihr vllt. ein eigenes Template benutzen wollt, dann empfiehlt es sich mich phpdoch genauer zu beschäftigen. Wenn ich herausfinde, wie man dies machen kann, so werde ich diese mit 100%iger (Hunderprozentiger) Sicherheit hier veröffentlichen.

Mit freundlichen Grüßen und Viel spaß beim Experimentieren mit dem phpDocumentor
htaccess

Edit1: Bekommt ihr die folgende Fehlermeldung No releases available for package "pear.php.net/phpdocumentor"
install failed

wenn ihr pear --force --alldeps phpdocumentor ausführt, so leert euren Cache. Dies geht mit folgendem Befehl:

 PHP 
1:
pear clear-cache


Edit2: Nach der Installation bekommt ihr auch ein WebInterface mitgeliefert, welches unter http://localhost/pear/PhpDocumentor/ erreichen könnt. Ich persönlich finde, dass es ein nettes Programm ist, wenn da doch nicht so viele Fehler drin wären. Möchtet ihr diese nutzen, so müsst ihr Vorkenntnisse in PHP besitzen, um diese auszumerzen. Aber da fehlen meist nur Backslashes (\), da die Pfade nicht richtig vergeben wurden, so sah es vorher z.B. so aus:
 PHP 
1:
2:
3:
4:
5:
6:
7:
<?php
// ... Vorheriger Code
if ('C:\xampp\htdocs\pear\' != '@'.'DATA-DIR@'){
// Anweisung in der if-Abfrage
}
// ... Alles was danach kommt
?>


Seht ihr den Fehler? Ihr macht entweder nach dem pear das Backslash (\) weg oder ihr fügt noch eines hinzu, da PHP den Backslash so interpretiert, dass ihr das ' Highlighten wollt und somit fehlt ihm dann ein ' und er spuckt einen Syntax error aus. Ich empfehle einen Backslash hinzuzufügen

Dann gibt es noch in der file_config.php einen fehler und zwar wird der define falsch gemacht.
 PHP 
1:
2:
<?php
define
(PHPDOC_WEBROOT_DIR'PhpDocumentor'); ?>


Wie wir sehen, versucht er eine Definition neu zu definieren. Aber was will er neu definieren, wenn diese zuvor noch nie definiert wurde? Somit setzen wir, um diesen Fehler zu beheben die PHPDOC_WEBROOT_DIR in Einfache Gänsefüßchen (').

Gefallen euch die Templates nicht? Schaut euch die Convertes die in C:\xampp\php\pear\PhpDocumentor\phpDocumentor\Converters liegen, mal etwas genauer an und generiert dadurch eure eigene Template Datei. Viel Spaß




Post wurde schon 4x editiert, das letzte mal am 27.01.2014 um 16:16 von Htaccess
27.01.2014, 12:03 Profil | PM | E-Mail  
k3ks
Mitglied
Aktiver User


Dabei seit: 25.05.2008
Herkunft: Hamburg
Posts: 150
      Zitat | Bearbeiten

Alternative zu phpdoc kann man auch phpdox nutzen




Post wurde schon 1x editiert, das letzte mal am 07.02.2014 um 11:11 von k3ks
07.02.2014, 11:10 Profil | PM | E-Mail  
Htaccess
Mitglied
Sehr guter User


Dabei seit: 22.08.2010
Herkunft: Deutschland
Posts: 693
      Zitat | Bearbeiten

Nette Alternative, aber ich habe hier phpDocumentor gewählt, weil es das weltweit bekannteste Documentor für PHP ist.


07.02.2014, 14:46 Profil | PM | E-Mail  
k3ks
Mitglied
Aktiver User


Dabei seit: 25.05.2008
Herkunft: Hamburg
Posts: 150
      Zitat | Bearbeiten

Ein weiter wichtiger Parameter ist @return

Und meines wissens nutzt man @category, @package und @subpackage nicht mehr, seit den es namespaces in php gibt




Post wurde schon 1x editiert, das letzte mal am 07.02.2014 um 15:39 von k3ks
07.02.2014, 15:35 Profil | PM | E-Mail  
Seiten (1):  1 
PHP-Support.de » Programmierung » Sonstige Sprachen » [pear] phpDocumentor - Dokumentation erstellen   

Neues Thema | Antworten   


Powered by Command Board 1.0 - Beta 2.0 © 2004-08 PHP-Einfach | Impressum | Datenschutz