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 fast ein Jahrzehnt Erfahrung im Bereich Web-Entwicklung mit PHP und Web-Design. Diese Eigenschaften machen mich zu einem geeigneten und geschätzten Ansprechpartner für die Umsetzung Ihres Projektes. Weiterhin bin ich seit Ende 2013 Magento Certified Developer.

4 Kommentare


  • Mark Knochen

    Hallo, ich habe nach Deinem Beispiel einen Link in /usr/bin abgelegt und sehe den da auch. Allerdings sagt die Konsole trotzdem immer noch phpdoc „command not found“ ? Was mache ich falsch?

    Und wie kann ich diesen Link dann wieder löschen?

    Danke schonmal

    Mark

    • Hi Mark,

      wem gehört der Link denn? Funktioniert der Befehl denn mit dem kompletten Pfad?
      Am besten einfach mal eine neue Terminal-Session öffnen, um sicher zu gehen dass auch in allen Pfaden gesucht wird. Aber normalerweise sollte das auch so funktionieren.

      Löschen kannst Du den Link einfach mit
      sudo rm /usr/bin/phpdoc

      Alternativ kannst Du auch in deine .bash_profile (im Home-Dir – anlegen falls sie nicht existiert), folgendes schreiben:

      PATH=/Applications/MAMP/bin/php/php5.4.4/bin:$PATH

      Dann spart man sich das anlegen der Links in /usr/bin/ und ist die schönere Lösung. Danach aber in jedem Fall eine neue Terminal-Session öffnen. In dem Fall sind die Befehle unter MAMP aber alle stärker als die unter /usr/bin/. Welches Programm aber wirklich ausgeführt wird, findest du mit whereis phpdoc raus.

      Ich hoffe ich konnte Dir helfen

  • Mark Knochen

    Bei mir liegt das Verzeichnis phpDoc unter Applications/XAMPP/htdocs

    In diesem befindet sich in ein bin Verzeichnis, welches die phpdoc.php beinhaltet … die soll doch aufgerufen werden?

    Installiert habe ich das ganze manuell aus dem tar.gz und eben in den htdocs Ordner im Apache gelegt .. stimmt das soweit?

    • Ach Du benutzt XAMPP? Das Tutorial ist auf MAMP ausgerichtet. Dazu kann ich leider sehr wenig sagen – ich nutze auf dem Mac ausschließlich MAMP.

Kommentar verfassen