API-Dokumentation aufwerten - Enricher in phpDox

in  Builds & Tests , ,

API-Dokumentation aufwerten - Enricher in phpDox

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.

API-Dokumentation aufwerten - Enricher in phpDox
API-Dokumentation aufwerten - Enricher in phpDox

Weitere Beiträge in Kategorie Builds & Tests

Automatisierte Tests - ein Zwischenstand
- Seit dem kürzlich angekündigten Start der Testautomatisierung von ModuleStudio ist bereits eine Menge geschehen. So gibt es knapp 1.000 Tests für die DSL, darunter vorwiegend für UI-unabhängige …
Ran an die Tests!
- Schon ewig geplant, aber lange schmählich vernachlässigt, habe ich bei ModuleStudio die automatisierten Tests. Zwar ist schon seit Längerem die Infrastruktur dahingehend ausgerichtet, was …
Erneuertes Build-System für ModuleStudio
- Die Komponenten von ModuleStudio werden nun mit anderen Technologien gebaut. Statt Buckminster wird jetzt das Maven-basierte Tycho eingesetzt. Die Jenkins-Jobs wurden auf Pipelines umgestellt und …
Jenkins mit GitHub-Integration, Pipelines und Multibranch Workflows
- Gegenwärtig beschäftige ich mich mit zwei interessanten Punkten in Bezug auf Jenkins. Die neu gestaltete Website bietet dazu einen guten Einstiegspunkt. Der erste Punkt dreht sich darum, Jenkins …
Funktion für automatisches Update integriert
- ModuleStudio 0.7 beinhaltet nun eine automatische Aktualisierung. Damit wird das Herunterladen neuer Versionen unnötig. Beim jeden Start der Anwendung werden verfügbare Updates gesucht und, sofern …