Schreiben von Dokumentation für PHP-Projekte: von A bis Z

Einleitung

Dokumentation ist nicht nur eine nette Ergänzung zu einem Projekt, sondern ein kritisch wichtiges Element professioneller PHP-Entwicklung. Gut geschriebene Dokumentation beschleunigt das Onboarding neuer Entwickler, reduziert die Anzahl von Fehlern und macht den Code auch nach Jahren noch wartbar. In diesem Artikel gehen wir den Weg von den Grundlagen des Kommentarschreibens bis zur Erstellung einer vollständigen technischen Dokumentation für Ihr PHP-Projekt.

Wir werden die PHPDoc-Standards, Best Practices für die Formatierung, Tools zur automatischen Generierung durchgehen und die Frage beantworten: Wie macht man Dokumentation nützlich und nicht nur formal?

Grundlagen von PHPDoc: Wie man PHP-Code richtig kommentiert

Der PHPDoc-Standard (oder DocBlock) ist die allgemein akzeptierte Methode zur Dokumentation von PHP-Code. Er basiert auf speziellen Kommentaren, die mit /** beginnen und mit */ enden. Jeder dieser Blöcke beschreibt ein Code-Element: eine Klasse, eine Methode, eine Eigenschaft oder eine Funktion.

Grundlegende Struktur eines DocBlocks

Ein minimaler Dokumentationsblock umfasst eine Beschreibung und eine Reihe von Tags (Annotationen). Betrachten wir ein Beispiel für eine einfache Methode:

<?php\n\n/**\n * Berechnet die Summe zweier Zahlen.\n *\n * @param int $a Der erste Summand.\n * @param int $b Der zweite Summand.\n * @return int Die Summe der Zahlen.\n */\nfunction sum(int $a, int $b): int {\n    return $a + $b;\n}\n?>

Wichtige PHPDoc-Tags

\n
• @param — beschreibt einen Parameter einer Methode oder Funktion. Format: @param Typ $name Beschreibung.
\n
• @return — gibt den Rückgabetyp und dessen Beschreibung an.
\n
• @var — wird für Klasseneigenschaften verwendet, um deren Typ anzugeben.
\n
• @throws — dokumentiert Ausnahmen, die eine Methode werfen kann.
\n
• @see — Verweis auf ein anderes Dokumentationselement oder eine externe Ressource.
\n
• @deprecated — markiert ein Element als veraltet, mit Angabe einer Alternative.
\n

Beispiel für eine Klasse mit mehreren Tags:

<?php\n\n/**\n * Klasse für die Arbeit mit der Datenbank.\n *\n * @package App\\Database\n * @author  Ivan Ivanov\n * @version 1.0.0\n */\nclass Database {\n    /**\n     * @var PDO Verbindung zur DB.\n     */\n    private PDO $connection;\n\n    /**\n     * Stellt eine Verbindung zur Datenbank her.\n     *\n     * @param string $dsn  DSN-Verbindungszeichenfolge.\n     * @param string $user Benutzername.\n     * @param string $pass Passwort.\n     *\n     * @throws PDOException Wenn die Verbindung fehlschlägt.\n     */\n    public function connect(string $dsn, string $user, string $pass): void {\n        $this->connection = new PDO($dsn, $user, $pass);\n    }\n}\n?>

Tools zur Generierung von PHP-Dokumentation

Die manuelle Pflege der Dokumentation im HTML-Format ist ineffizient. Hier helfen automatische Generatoren. Der bekannteste ist phpDocumentor (phpdoc).

Installation und grundlegende Verwendung von phpDocumentor

phpDocumentor kann über Composer installiert werden:

composer require --dev phpdocumentor/phpdocumentor

Nach der Installation starten Sie die Dokumentationsgenerierung aus dem Projektstammverzeichnis:

vendor/bin/phpdoc -d src -t docs

Wobei -d src das Verzeichnis mit dem Quellcode und -t docs das Verzeichnis ist, in dem die generierte HTML-Dokumentation gespeichert wird.

Weitere nützliche Tools

\n
• Doxygen — unterstützt nicht nur PHP, sondern auch C++, Python, Java. Geeignet für Projekte mit gemischten Sprachen.
\n
• Sami — ein moderner Dokumentationsgenerator, der mehrere Versionen der Dokumentation für verschiedene Code-Zweige erstellen kann.
\n
• ApiGen — ein leichtgewichtiger Generator, der auf einfache Bedienung ausgelegt ist.
\n

Best Practices für das Schreiben von PHP-Dokumentation

Hochwertige Dokumentation ist