Vjassdoc

Aus Mappedia

vjassdoc ist ein Programm zur Generierung einer API-Dokumentation aus Jass- bzw. vJass-Code. Es wurde von Baradé mit der Programmiersprache C++ entwickelt und zunächst auf inWarcraft.de und später auch auf Wc3Campaigns.net veröffentlicht. Die aktuelle Version trägt die Nummer 0.3. Das Programm verwendet in dieser Version sowohl Funktionen der C- und C++-Standardbibliothek als auch der Datenbankbibliothek SQLite3, der gettextlib-Bibliothek, der Boost-Bibliotheken, der glibc-Bibliothek und der KDE-4- und somit auch der Qt-4-Bibliotheken. Es ist als eine plattformübergreifende Anwendung für Unix- und Windows-Betriebssysteme gedacht, allerdings kann es unter OS Mac OS und Windows noch zu Problemen kommen, da der Programmierer selbst hauptsächlich ein Linux-System verwendet. Der gesamte Quell-Code steht unter den Bedingungen der GPLv2 und ist somit frei verfüg-, veränder- und verfielfältigbar. Für die Generierung der Make-Dateien muss das Programm cmake verwendet werden. Seit Version 0.3 ist es möglich eine einfache grafische Oberfläche zu kompilieren, insofern die KDE-Bibliotheken der Version 4 installiert sind.

[bearbeiten] Hintergrund

Es gibt eine Vielzahl von Programmen, die aus Quell-Code einer bestimmten Programmiersprache eine API-Dokumentation erzeugen. Meist wird diese Referenz dann in HTML erzeugt und lässt sich per Web-Browser betrachten. Da ein solches Programm bei den Skriptsprachen Jass und vJass noch nicht existierte, fasste der Benutzer Baradé den Entschluss, eines zu entwickeln.

[bearbeiten] Dokumentationskommentare

vjassdoc unterstützt sogenannte Dokumentationskommentare. Diese dienen der Beschreibung unterschiedlicher Objekte des Codes und werden in der Ausgabe separat aufgelistet bzw. erhalten sie wie jedes andere geparste Objekt eine eigene Referenzseite. Ein Dokumentationskommentar beginnt im Gegensatz zu einem gewöhnlichen Kommentar mit drei Schrägstrichen: ///. Da inzwischen von vJass auch Blockkommentare unterstützt werden, können auch Blockdokumentationskommentare verwendet werden. Diese beginnen im Gegensatz zu einem Blockkommentar mit zwei Sternen: /**. Zusätzlich zum Kommentarinhalt selbst kann man noch einige spezielle Schlüsselwörter für die Formatierung des Dokumentationskommentars verwende

In Version 0.3 werden folgende Schlüsselwörter unterstützt:

@author <Name des Autors>
@brief <Kurzbeschreibung>
@see <Bezeichner eines anderen geparsten Objekts>
@todo <Beschreibung dessen, was noch zu tun ist>

Zusätzlich kann man auch, anders als bei @see, explizit auf andere Objekte eines speziellen Typs verlinken:

@comment <Bezeichner eines Kommentars>
@keyword <Bezeichner eines Schlüsselwortes>
@textmacro <Bezeichner eines Textmakros>
@textmacroinstance <Bezeichner einer Textmakroinstanz>
@type <Bezeichner eines Typs>
@local <Bezeichner einer lokalen Variable>
@global <Bezeichner einer globalen Variable>
@member <Bezeichner eines Elements>
@parameter <Bezeichner eines Parameters>
@functioninterface <Bezeichner einer Funktionsschnittstelle>
@function <Bezeichner einer Funktion>
@method <Bezeichner einer Methode>
@implementation <Bezeichner einer Implementation>
@interface <Bezeichner einer Schnittstelle>
@struct <Bezeichner einer Struktur>
@module <Bezeichner eines Moduls>
@scope <Bezeichner eines Bezugsrahmens>
@library <Bezeichner einer Bibliothek>
@sourcefile <Bezeichner einer Quell-Datei>
@doccomment <Bezeichner eines Dokumentationskommentars>

In der aktuellen Version kann es noch zu Problemen bei der Namensfilterung kommen.

[bearbeiten] Eingabe

Neben den zu parsenden Code-Dateien können als Eingabeargumente diverse Optionen übergeben werden (siehe "Optionen"). Dabei können unter anderem mit einzubeziehende Datenbanken und ein Kompilierungsausgabepfad angegeben werden. Während die Einbeziehung anderer Datenbanken ab Version 0.3 zwar technisch gesehen möglich ist, jedoch für die meisten Objekttypen noch nicht unterstützt wird, ist das Umwandeln von vJass- zu Jass-Code nahezu unmöglich. Bis jetzt wird lediglich das Schreiben von globalen Variablen unterstützt, jedoch ist geplant aus vjassdoc zusätzlich einen ähnlichen Precompiler wie den JassHelper zu machen, welcher dessen Aufgaben jedoch schneller und zuverlässiger erledigen soll (siehe dazu "Zukunft").

[bearbeiten] Ausgabe

Das Programm kann eine HTML-Index-Datei, in welcher sämtliche geparste Objekte aufgelistet und mit deren Seiten verlinkt werden, erzeugen, sowie die einzelnen Seiten der geparsten Objekte. Außerdem ist es möglich, die Daten der geparsten Objekte in eine SQLite3-Datenbank zu schreiben. Zusätzlich gibt es erste Ansätze eines Compilers und Syntax-Checkers, welche die Aufgabe des JassHelpers übernehmen können sollen. Diese befinden sich allerdings noch in einem frühen Stadium der Entwicklung und sind daher mehr oder weniger unbenutzbar.

[bearbeiten] Anwendung

vjassdoc lässt sich über die Konsole aufrufen und besitzt keine grafische Oberfläche. Die Optionen lassen sich seit Version 0.2 per Kurzschreibweise verwenden und somit auch kombinieren. Seit Version 0.3 verwendet das Programm dazu die gängige getopt-Funktion der GNU-Bibliothek.

Folgende Optionen stehen zur Auswahl:

--help: Zeigt alle möglichen Optionen und deren Beschreibungen an.
--version: Zeigt die momentane Version von vjassdoc und Lizenzinformationen an.
-j --jass: vJass-Code wird ignoriert.
-d --debug: Zeilen, die mit dem vJass-Schlüsselwort debug beginnen, werden nicht ignoriert.
--private: Private Objekte werden geparst (seit Version 0.2.3).
-m --textmacros: Der Code zwischen Textmakroanweisungen wird geparst (seit Version 0.2.3).
-t --time: Ermittelt die vergangene Zeit und zeigt diese am Ende des Prozesses an.
-a --alphabetical: Alle Objekte werden in alphabetischer Reihenfolge sortiert.
-h --html: Das Programm erzeugt eine einfache HTML-API-Dokumentation.
-p --pages: Das Programm erzeugt für jedes geparste Objekt eine HTML-Datei.
-b --database: Geparste Objekte werden in einer SQLite3-Datenbank gespeichert, welche von anderen Programmen ausgelesen werden kann.
-v --verbose: Das Programm zeigt mehr Informationen über den Prozess an.
--title <arg>: <arg> muss durch den für die API-Dokumentation verwendeten Titel ersetzt werden.
--importdirs <args>: <args> muss durch eine oder mehrere Import-Verzeichnisse ersetzt werden (Für das //!-Import-Makro aus vJass verwendet).
--files <args>: <args> muss durch die zu parsenden Dateien ersetzt werden.
--dir <arg>: <arg> muss durch den Ausgabeverzeichnispfad ersetzt werden.

[bearbeiten] Internationalisierung

Dank des Programms gettext verfügt vjassdoc über eine Mehrsprachenfähigkeit. Derzeit existierien Übersetzungen ins Englische, Deutsche und Makedonische (jedoch noch unvollständig).

[bearbeiten] Veröffentlichungen

2009-11-09: Version 0.3
2009-03-09: Version 0.2.3
2009-02-11: Version 0.2.2
2009-01-25: Version 0.2.1
2009-01-15: Version 0.2
2008-10-11: Version 0.1 wurde unter die GPLv2 gestellt
2008-08-16: Version 0.1

[bearbeiten] Zukunft

Zukünftig ist vom Entwickler Baradé geplant, die von Hand geschriebene "File"-Parse-Klasse durch automatisch generierte Code-Dateien mittels den Anwendungen Lex, Yacc und Bison zu ersetzen und so Änderungen und mögliche Anpassungen an neue Skriptsprachen wie Zinc besser vornehmen zu können. Außerdem soll es so besser oder überhaupt erst möglich sein mit vjassdoc Aufgaben des Programms JassHelper wie die Generierung von Jass-Code aus vJass-Code oder die Syntaxfehlerfindung in Zweiterem zu erledigen. Zudem sollen die Unterstützung der Dokumentationskommentarschlüsselwörter, die der Einbeziehung von Datenbanken, sowie angebotene Autovervollständigungsfunktionen verbessert werden.