Wer seine Projekte regelmäßig mit einem Build-Server prüfen und testen lässt, erstellt oftmals auch eine API-Dokumentation. Dafür gibt es auch im PHP-Bereich eine Vielzahl unterschiedlicher Werkzeuge, beispielsweise PHPXref oder ApiGen. Dieser Beitrag stellt das Tool phpDox vor und gibt Einblick in das interessante Feature der Enricher.
Eine API-Dokumentation stellt in der Regel eine navigierbare Übersicht der in einem Projekt vorhandenen Klassen, Schnittstellen, Methoden usw. bereit. Damit können Entwickler, die diese Artefakte in ihrem eigenen Code nutzen wollen, Informationen über die benötigten Methoden einsehen und so beispielsweise herausfinden, welche Argumente eine bestimmte Funktion erfordert.
phpDox geht einen Schritt weiter und versucht, weitere Daten und Angaben übersichtlich in die Dokumentation mit aufzunehmen. Zum Beispiel wird bei einer Klasse neben ihren Variablen und Methoden auch angezeigt, ob und welche offenen Tasks noch vorhanden sind (diese werden über TODO-Marker erkannt).
phpDox erlaubt es darüber hinaus eine beliebige Erweiterbarkeit der API-Dokumentation um zusätzliche Informationen. Dies geschieht über sogenannte Enricher, die die Endausgabe ganz wortgemäß anreichern. phpDox bringt von Haus aus bereits einige Enricher mit:
- build
- Sammelt allgemeine Build-Informationen, wie zum Beispiel die aktuelle Zeit, die verwendete phpDox-Version, die aktivierten Enricher sowie Umgebungsparameter
- checkstyle
- Integriert die XML-Ausgabe des Metrikwerkzeugs CheckStyle. Damit sieht man in der API-Dokumentation einer Klasse direkt, welche Coding Style Probleme dort noch zu beheben sind.
- git
- Stellt Git-Informationen bereit. Optional können die neuesten X Einträge der Git-Historie einer Datei in deren API-Dokumentation mit angezeigt werden. So hat man einen Überblick über die kürzlich vorgenommenen Veränderungen.
- phploc
- Integriert die XML-Ausgabe des Metrikwerkzeugs PHPLoc. Dies bereichert die API-Dokumentation um Informationen bezüglich des Code-Umfangs des Projektes.
- phpunit
- Bindet Informationen über die Testabdeckung (Coverage) ein. So wird in der API-Dokumentation ersichtlich, welche Dateien noch nicht getestet werden und wie hoch ihre jeweilige Coverage ist.
- pmd
- Integriert die XML-Ausgabe des Metrikwerkzeugs PMD (PHPMessDetector). Damit sieht man in der API-Dokumentation direkt, welche potenziellen Programmierprobleme noch bestehen.
In Anbetracht der vielfältigen Daten, die auf diese Weise insgesamt in die API-Dokumentation mit einfließen, steigt deren Stellenwert auf ein neues Niveau: die erhöhte Aussagekraft führt auch zu einer stärkeren Relevanz einer API-Dokumentation im Projektteam.
