PHP: Dokumentation mit dem phpDocumentor (phpdoc)

Ja, die liebe Dokumentation. Als Entwickler ist es doch irgendwie das letzte was man machen möchte und was sicherlich am wenigsten Spaß bringt. Umso besser, wenn man sich etwas Arbeit abnehmen lassen kann.

Installation / Konfiguration

Ich arbeite aktuell mit MAMP unter Mac OS X Mountain Lion 10.8.5 und mit php 5.4.4 – hier habe ich mir auch schon PEAR konfiguriert und kann so ganz einfach die Erweiterung nachinstallieren – wie das geht habe ich mal in diesem Artikel angerissen:

cd /Applications/MAMP/bin/php/php5.4.4/bin
./pear channel-discover pear.phpdoc.org
./pear install phpdoc/phpDocumentor

In meinem Fall wurde Version 2.0.1 installiert. So sollte die Ausgabe in etwa aussehen:

downloading phpDocumentor-2.0.1.tgz ...
Starting to download phpDocumentor-2.0.1.tgz (2,653,745 bytes)
.........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................done: 2,653,745 bytes
install ok: channel://pear.phpdoc.org/phpDocumentor-2.0.1

Weiterhin ist es sinnvoll GraphViz direkt mit zu installieren. Mit diesem Library ist es phpDoc möglich, grafische Abhängigkeiten und Hierarchien zwischen den Klassen darzustellen. Bitte beachtet, dass ihr dazu brew installieren müsst (was ich aber generell immer empfehlen kann).

brew install graphviz
pear install Image_GraphViz

Falls die Installation nicht durchgeführt wird, bekommt man am Ende der phpDoc-Generierung die folgende Meldung:

[Zend\Stdlib\Exception\ExtensionNotLoadedException]
Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path?

Damit ich diese Version von überall aufrufen kann, lege ich einen Link im bin-Verzeichnis ab:

cd /usr/bin
sudo ln -s /Applications/MAMP/bin/php/php5.4.4/bin/phpdoc

Nutzung

Nun können wir die neu installierte Erweiterung auch schon ausprobieren. Dazu einfach in ein (relativ gut) dokumentiertes Projekt wechseln und folgenden Befehl ausführen:

phpdoc -d . -t docs

Nun wird alles in dem aktuellen Verzeichnis dokumentiert und nach docs gespeichert. Die Ausgabe zeigt außerdem sehr schön auf, welche Attribute, Methoden oder Klassen noch nicht dokumentiert sind.

Natürlich möchte man nicht immer alle Konfigurationsparameter per Hand vornehmen. In diesem Fall empfiehlt es sich, eine phpdoc.xml in das Projekt zu legen. Was hier genau konfiguriert werden kann, lässt sich hier nachlesen. Ein Template für die Konfiguration findet man hier:

/Applications/MAMP/bin/php/php5.4.4/lib/php/phpDocumentor/data/phpdoc.tpl.xml

Fazit

Zum Abschluss bleibt zu sagen: Tolle Lösung um sehr einfache Dokumentationen zu erstellen. Wenn man sich daran gewöhnt hat, denkt man schon beim Programmieren daran die entsprechenden Kommentare an die Klassen, Methoden und Attribute zu schreiben. So zieht sich die Dokumentation über die komplette Projektlänge und schlägt nicht erst am Ende auf.

Weiterhin gefällt es mir sehr gut, dass phpDoc auf Bootstrap setzt (wenn auch noch nicht auf Version 3).

Leider sind die Klassennamen von Magento teilweise sehr lang und machen das Layout der Dokumentation etwas kaputt. Dafür gibt es aber sicher per Konfiguration noch eine Lösung.


Beitrag veröffentlicht

in

, , , , , ,

von

Schlagwörter: