PhpDocumentor

Aus THM-Wiki
Wechseln zu: Navigation, Suche

Mit dem Tool phpDocumentor ([1]) kann man ansprechende Dokumentationsdateien für den PHP-Code des eStudy-Projekts erstellen. Dazu wird eine Javadoc-ähnliche Notation verwendet. In den meisten Dateien des Projekts ist dies auch schon umgesetzt worden.

Im Folgenden wird beschrieben, was man tun muss, um die HTML-Dokumentation aus dem Quellcode zu erstellen.


Installation von PhpDocumentor

Bitte laden Sie sich die Installationsdatei von der PhpDocumentor-Website herunter und entpacken Sie diese in ein beliebiges Verzeichnis. Zur Installation muss i.d.R. nichts Weiteres mehr getan werden.

Mit der Zeile

 php phpdoc -h

(aus dem entpackten Verzeichnis heraus) kann man sich die Kommandozeilenparameter des Programms anzeigen lassen.

Direkter Aufruf

Das Programm kann direkt auf den eStudy-Quellcode (oder nur auf einen Teil davon) angewendet werden. Dazu wird folgendes Kommando verwendet:

 phpdoc -d <Pfad zum eStudy-Quellcode> -t <Zielverzeichnis>

PhpDocumentor liest dann alle Dateien in allen Unterverzeichnissen des angegebenen Pfades ein und erzeugt die HTML-Dateien im Zielverzeichnis.

Folgende Parameter sind außerdem möglich:

 -ti Titel der Dokumentation
 -pp Einbeziehung von mit @access private gekennzeichneten Methoden
 -s PHP-Code einfügen (mit Syntax-Highlighting)

Vordefinierte Konfigurationsdatei

Eine vordefinierte Konfigurationsdatei (eStudy_phpdoc.ini) befindet sich im doku-Ordner des eStudy-Repositorys. Sie enthält Einstellungen für das PhpDocumentor-Theme earthli und zur Inkludierung des PHP-Quellcodes in die Dokumentation. Außerdem wird der Titel korrekt gesetzt und die Pfade sind bereits so konfiguriert, dass das gesamte Projekt verarbeitet wird.

Um die vordefinierte Konfigurationsdatei zu benutzen, muss man im doku-Ordner folgendes Kommando ausführen:

 php <Pfad zu phpdoc>/phpdoc -c eStudy_phpdoc.ini

Es wird dann ein phpdoc-Unterordner angelegt, der die Dokumentation enthält.

Probleme

Unter Windows wird die Groß-/Kleinschreibung bei Dateinamen nicht beachtet. Deshalb kann es passieren, dass ein Package, für das in einigen Quelldateien unterschiedliche Groß-/Kleinschreibung verwendet wurde (z.B. eStudy-admin und eStudy-Admin), nicht korrekt verarbeitet wird. Die Klassen, die die zuletzt gefundene Schreibweise enthalten, überschreiben die aller anderen. Die Dokumentation zeigt dann unterschiedliche Packages mit unterschiedlichen Schreibweisen an; allerdings haben diese den selben Inhalt. Überschriebene Klassen tauchen in der Dokumentation nicht auf.

Achtung: Das Erzeugen der Dokumentation über das gesamte Projekt ist sehr speicherintensiv (ca. 1 GB Speicherverbrauch) und dauert entsprechend lange (zwischen 1-x Stunden), je nach Rechnersystem.