Das Thema Kommentare im Sourcecode ist ja schon ziemlich alt und auch für die PHP-Entwickler ein alter Hut und somit stellt man sich direkt die Frage, was ich denn da heute erzählen will. Es geht heute um die phpdoc Compiler, die phpdoc-Blöcke aus dem Code extrahieren und in einer lesbaren Form zusammentragen. Ordentliches phpdoc erzeugt damit auch gleich eine ordentliche Dokumentation.
Der übliche Compiler ist der PhpDocumentor. Wer diesen bei – sagen wir mal – durchschnittlichen Projekten eingesetzt hat oder einsetzt weiß, dass es schon seine Zeit dauert, bis die Dokumentation erzeugt ist. Wenn wir jetzt wiedermal in Richtung CI schauen, stellen wir schnell fest, dass es dann einen Widerspruch gibt. Der Build-Prozess sollte möglichst wenig Zeit verbrauchen, damit er häufig angestoßen werden kann, aber dennoch möglichst vollständig sein. Ich kenne das Vorgehen, dass man die Generierung der Dokumentation aus dem CI herausnimmt und durch einen nächtlichen Cronjob durchführen lässt. Ob dieser Job dann auf dem CI-System läuft oder andersweitig ist an dieser Stelle dann zweitrangig. Auf jeden Fall gibt es über den Tag keine aktuelle Dokumentation und es gibt somit eine Kluft zwischen Doku und Source.
Es gibt natürlich auch alternative Compiler, denn dieses beschriebene Problem ist kein neues. Einer dieser Compiler ist DocBlox, den ich bei der Recherche entdeckt habe.
Die Geschwindigkeit hat mich begeistert. DocBlox ist sehr schnell und lässt sich somit in den Build-Prozess integrieren, ohne dass man sehr viel Zeit verliert. Die Optimierung auf die Geschwindigkeit kann man bei weiteren Durchläufen erkennen, da diese schneller als der initiale Durchlauf sind. Unveränderte Quellcodes werden nicht wieder betrachtet.
Eigentlich wollte ich ja einen kleinen Geschwindigkeitsvergleich an dieser Stelle anbringen, aber der ging etwas nach hinten los. Als Testobjekt sollte das Zend Framework in der aktuellen Version benutzt werden und der gesamte Source (inkl. Unittests) sollte analysiert werden. DocBlox hat dies in weniger als 18 Minuten erledigt. Den phpDocumentor habe ich nach über einer Stunde abgebrochen, da eine Ende noch nicht in Sicht war. Tja, schade! Interessant fand ich bei dem versuchten Vergleich die Tatsache, dass DocBlox sich bei ca 200MB Speicher eingependelt hat und der PhpDocumentor bei ca 500MB. Da die VM auch nur 512MB zur Verfügung hatte, hat DocBlox den Speicher auch geschickter genutzt.
Wie üblich gibt es eine kurze Beschreibung zur Installation. Ich habe den PEAR-Weg gewählt:
$ pear channel-discover pear.docblox-project.org $ pear channel-discover pear.zfcampus.org $ pear channel-discover pear.michelf.com $ pear install docblox/DocBlox-beta
Danach ist docblox
als Tool verfügbar. Mit den Parametern -d und -t kann man ein Sourceverzeichnis und ein Zielverzeichnis angeben. Sehr intuitiv und vom PhpDocumentor bekannt.