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:

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

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).

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:

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:

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:

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.

Über

Jahrgang 87, gelernter Softwareentwickler und 15 Jahr Erfahrung im Bereich Web-Entwicklung mit PHP. Weiterhin bin ich seit Ende 2013 Magento Certified Developer.