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

Abhängigkeiten automatisch aktualisieren mit Renovate
- Um Dependencies aktuell zu halten, wird bei GitHub oft und gerne der Dependabot eingesetzt. Mit Renovate existiert allerdings eine äußerst flexible Alternative, die im Folgenden kurz vorgestellt wird. …
Symfony-Projekte im Monorepo mit Nx bauen
- Mit dem Build-System Nx lassen sich beliebige Projekte in einem Monorepo auf einheitliche Weise testen und bauen. Es bedient sich verschiedener npm-Plugins, um dies für unterschiedliche Technologien …
Abhängigkeiten automatisch aktualisieren mit Dependabot
- Vor knapp eineinhalb Jahren haben wir gezeigt, wie man die Aktualisierung verwendeter Drittkomponenten mit GitHub Actions automatisieren kann. Zwischenzeitlich sind wir hierbei auf den Dependabot …
Hugo-Seiten im Netzwerk entwickeln und testen
- Hugo ist ein Generator für statische Seiten, welcher auf der Programmiersprache Go basiert. Die Inhalte werden mit Markdown verwaltet und dynamisch in HTML umgewandelt. Dies ist für die meisten …
SensioLabs Security Checker wurde eingestellt
- Zu den grundlegenden Aufgaben automatisierter Builds zählen unterschiedliche Prüfungen: so bietet es sich an, die Einhaltung der Coding-Styles zu überwachen, Qualitätsmetriken zu erheben und die …