CScript2Doc | ||||||||||||||||||||
1. Einführung | ||||||||||||||||||||
Jeder Hobby-PHP- oder -Perl-Programmierer kennt das Problem: Man schreibt seinen Code und will ihn für andere Personen zugänglich machen.
Doch damit der Code oder seine Funktionen wiederverwendbar ist, muss man die Funktionen erklären. CScript2Doc erzeugt aus Perl- oder PHP-Code eine eigenständige Onlinedokumentation im XML- oder HTML-Format. |
||||||||||||||||||||
2. Funktionsweise | ||||||||||||||||||||
CScript2Doc parst die angegebenen Dateien. Dabei werden Kommentarzeilen, die einem bestimmten Aufbau folgen (s.u.) ausgewertet und in die Onlinedokumentation integeriert.
Nach dem Parsen wird aus den gesammelten Code-Informationen eine Onlinedokumentation erstellt. |
||||||||||||||||||||
3. Kommentare | ||||||||||||||||||||
Texte oder Funktionen, die in die Onlinedokumentation aufgenommen werden sollen, müssen folgenden Aufbau besitzen:
// XML::<Funktion oder Metaangaben> (<Text>) # XML::<Funktion oder Metaangaben> (<Text>)Wie zu sehen ist, müssen die Kommentare mit Double-Slashs ("//" - Einzeilige Kommentare in PHP) oder einer Raute ("#" - Einzeilige Kommentare in PHP und Perl) beginnen. Mehrzeiliger Kommentartext ist vorerst nicht erlaubt. Nach dem Kommentarzeichen folgt der String "XML::". Dies weist dem CScript2Doc-Parser an, den folgenden Text in die Onlinedokumentation aufzunehmen. Nach der Zeichenfolge "XML::" folgen entweder Metaangaben oder Funktionsbeschreibungen. Folgende Angaben sind erlaubt:
|
||||||||||||||||||||
4. Anwendungsbeispiele | ||||||||||||||||||||
Zuweisung von Modulnamen, Beschreibung, Autor und Version eines Moduls:
// XML::MODUL (CTest) // XML::DESC (Test-Klasse) // XML::AUTHOR (::[CTH]Goldenhawk::) // XML::VERSION (1.0) Zuweisung einer Funktion: // XML::FUNC::newFunction ($this->newFunction($opts)) // XML::DESC::newFunction (newFunction erstellt einen Beispiel-Prototypen) // XML::VERSION::newFunction (1.0) // XML::RETURN:: (BOOL) |
||||||||||||||||||||
5. Erstellung der Onlindokumentation | ||||||||||||||||||||
Folgender Funktionen sind für die Klasse CScript2Doc erlaubt:
// Datei CScript2Doc.php integrieren include_once("CScript2Doc.php") // Neuen Prototypen erstellen $cs2d = new CScript2Doc; // Festlegen, ob eine Datei (file) oder // ein Ordner (dir) nach PHP-/Perl-Code gescannt werden soll $opts[type] = "dir"; // Datei bzw. Ordner festlegen $opts[input] = "h:/server_systeme/apache/users/php/modules"; // Ausgabedatei festlegen. Wird keine Datei angegeben, wird die Datei // out.xml im Ordner von CScript2Doc.php erstellt. $opts[ouput_file] = "c:/out.xml"; // Optionen festlegen $cs2d->setInput($opts); // Debuginformationen ausgeben $cs2d->debug = 1; // Ausgabeformat setzen (xml) $cs2d->output = "xml"; // Angegebene Datei bzw. Ordner parsen $cs2d->parseInput(); |