API-Dokumentationen mit ApiGen erstellen
Warum eigentlich API-Dokumentationen?
Eine gute Dokumentation ist wichtig für jedes Projekt, egal ob es sich dabei um ein von der Community entwickeltes Open Source-Tool handelt oder um eine für einen Kunden geschriebene Software. Eine API-Dokumentation erleichtert es Entwicklern, neu ins Projekt einzusteigen oder sich einen Überblick über alle relevanten Teile des Projekts zu verschaffen.
Ein weiterer Vorteil von API-Dokumentationen ist, dass sie sich schnell und automatisch generieren lassen. Dieser Schritt kann in den Build-Prozess integriert werden, so dass immer eine aktuelle, ggf. auch versionierte Dokumentation vorliegt. Sie sind sozusagen der leicht erfüllbare Mindeststandard für eine Dokumentation.
Denn, seien wir ehrlich, eine API-Dokumentation erklärt und veranschaulicht nicht (das machen Codebeispiele und handgeschriebene Dokumentationen), sondern ist eher eine Art Nachschlagewerk. Durch die immer besseren Funktionalitäten von IDEs verliert es sogar mittlerweile an Bedeutung. Ich persönlich schaue nur selten in einer API-Dokumentation nach, wenn ich das Projekt schon in meiner Entwicklungsumgebung vorliegen habe. Your mileage may vary 
Generatoren für PHP-Code-Dokumentationen
Für PHP existiert schon seit langem der PHPDoc-Standard zur Dokumentation von Software, angelehnt an Javadoc. Lange Zeit war phpDocumentor das Werkzeug der Wahl zum Erstellen von API-Dokumentationen. Update:Allerdings wird phpDocumentor nicht mehr aktiv weiterentwickelt und unterstützt auch keine Features (z.B. Namespaces) mehr, die ab Version 5.3 in PHP Einzug gehalten haben. Daher ist es für moderne Projekte nicht mehr ohne weiteres zu gebrauchen. Mike van Riel, einer der Entwickler von phpDocumentor2 hat kommentiert, dass das Tool sehr wohl weiterentwickelt wird, auch neue PHP-Features unterstützt und deutlich schneller sein soll als früher. Das ist der Grund, warum auch große Projekte wie das ZF2 noch auf dieses bewährte Tool setzen. Danke, Mike!
Wer nach Alternativen sucht, wird vermutlich auf Doxygen stoßen, das neben PHP sehr viele weitere Sprachen unterstützt. Das API von Symfony2 wird von einem Generator namens Sami erzeugt, den Chef-Entwickler Fabien Potencier geschrieben hat. Und es gibt ApiGen:
ApiGen has support for PHP 5.3 namespaces, packages, linking between documentation, cross referencing to PHP standard classes and general documentation, creation of highlighted source code and experimental support for PHP 5.4 traits.
Einsatz für ApiGen
Ich habe ApiGen auf die empfohlene Methode mithilfe von PEAR installiert, es gibt aber auch eine Download-Variante und die Möglichkeit, das GitHub-Repository zu klonen.
Für mein vorliegendes Symfony2-Projekt wollte ich eine API-Dokumentation erstellen, die nur die selbst geschriebenen Bundles berücksichtigt, also alles unterhalb von src/. Wer möchte, kann aber auch das gesamte vendors/-Verzeichnis oder Teile davon miteinbeziehen. Das kann sinnvoll sein, wenn auch vom Framework geerbte Methoden mit in die Dokumentation aufgenommen werden sollen.
In dem in diesem Projekt bereits bestehende Verzeichnis docs/ erzeugte ich
NEON ist ein Format für Konfigurationsdateien, das YAML ähnelt und offenbar von den ApiGen-Entwicklern stammt. Es ist so simpel, dass es sich kaum lohnt, darüber zu streiten, ob dieses weitere Format denn überhaupt notwendig ist
source:
- "../../src/"
exclude:
- "<em>/tests/</em>"
- "<em>/DataFixtures/</em>"
- "*Test.php"
destination:
"./docs/"
title: MyProject
report: "./report/report.xml"
docs/apigen/docs/, ein Fehlerbericht, der in meinem Fall hauptsächlich auf fehlende Methodenbeschreibungen hinweist, in docs/apigen/report/report.xml: Wie das Ergebnis aussieht, zeigt beispielhaft die API-Dokumentation des Nella Frameworks. Ich bin mit ApiGen ganz zufrieden, denn es ist schnell zu installieren, zu konfigurieren und einzusetzen. Wahrscheinlich gibt es noch eine Menge weiterer Tools da draußen, die bestimmt ähnlich gut funktionieren. Welche Tools verwendet ihr?
Trackbacks
Keine Trackbacks
Kommentare
Ansicht der Kommentare: Linear | Verschachtelt
Mike van Riel am :
I'm afraid that the I have to point out that phpDocumentor is actively developed for over a year now. We are working hard on phpDocumentor2 and, for example, the ZF2 docs is generated by phpDocumentor2.
With phpDocumentor2 documentation is generated much faster than phpDocumentor1 and it supports all modern features, such as namespaces, out of the box.
Matthias Gutjahr am :
Thanks for the heads up, Mike, I stand corrected and updated my post. I wonder where I got the wrong information from. I mean, I actually looked at the phpdoc.org website but obviously did not read anything there. Sorry, keep up the good work - I will probably give phpDocumentor2 a try next time!
Mike van Riel am :
Thanks! Let me know if you encounter any issues or see room for improvement.
Stephan Krauß am :
Hallo !
Ich wurde durch deinen Artikel auf Apigen aufmerksam. Leider kenne ich die möglichen Tags in Apigen zu wenig. Kann man im PhpDoc Block Tags setzen die die Abhängigkeit von anderen Klassen und Methoden kennzeichnet ?
Mit freundlichen Grüßen
Stephan
Stephan Krauß schrieb auch: Einladung zum Themenabend: “agiles Projektmanagment”