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

GitHub integriert Code Security Scanner
- Im offiziellen GitHub Changelog werden regelmäßig Beiträge über unterschiedliche Neuerungen und Innovationen auf der GitHub Plattform veröffentlicht, zum Beispiel in Bezug auf Funktionen in der …
GitHub Actions - Eine Aktion zum Bauen und Testen von Zikula-Modulen
- Vor ein paar Wochen haben wir unsere generator-action vorgestellt, welche die einfache Generierung von Zikula-Erweiterungen mit dem Standalone Generator von ModuleStudio erlaubt. Diese Action wird als …
GitHub Actions - Eine Aktion zum Generieren von Zikula-Modulen
- Der Standalone-Generator ModuleStudio bietet einen Standalone-Generator, mit dem sich jederzeit eine Anwendung über die Kommandozeile generieren lässt. Einige allgemeine Informationen hierzu sind der …
GitHub Actions - Programmatische Trigger, Build Pipelines, Dashboard
- In diesem Beitrag geht es darum, mehrere und unterschiedliche Build Jobs miteinander zu verknüpfen. Je größer eine Build Infrastruktur wird, desto häufiger wird man mit solchen Anforderungen …
GitHub Actions - Java-Projekte bauen und testen
- Nachdem im letzten Artikel gezeigt wurde, mit welchen Mitteln sich in GitHub Actions Projekte auf Basis von PHP verarbeiten lassen, schauen wir nun auch einmal kurz in die Java-Welt. Werkzeuge für das …