2010
Javascript Code Dokumentation mit Doxygen
Gerade beim Schreiben meiner Bachelorarbeit dachte ich, dass es sinnvoll sei die Quelltextdokumentation mancher Javascript Klassen als Anhang an die Arbeit anzuhängen. Meiner Meinung nach kann der geneigte Leser so am schnellsten und besten bestimmte Konstrukte nachvollziehen, wenn er sich einen Überblick darüber verschaffen kann, welche Methoden (Funktionen) an welche Stelle vorkommen. Da ich meine Bachelorarbeit mit LaTeX schreibe kam mir direkt Doxygen in den Sinn, da ich wusste das hier (neben dem genialen HTML-Export) auch ein Tex-Export mitgeliefert wird.
Leider musste ich feststellen, dass Doxygen von sich aus kein Javascript unterstützt. Doch glücklicherweise gibt es dazu Abhilfe. Jörg Schaible hat ein Perl Skript namens js2doxy geschrieben, das den Javascript Code parst und daraus eine Art C++ Pseudocode erzeugt. Diesen wiederum kann Doxygen dann verarbeiten und man erhält die gewohnt saubere Ausgabe in HTML und Tex.
Als Perl Laie war ich zunächst kurz abgeschreckt. Außerdem habe ich nirgendwo eine Downloadmöglichkeit für das Skript gefunden. Ich habe mich dann aber kurz eingelesen und siehe da es ist wirklich Kinderleicht. Das Skript habe ich per Copy/Paste in eine Datei kopiert, damit es leichtern wird hab ich es hier mal hochgeladen.
Kurzanleitung Javascript Doxygen Dokumentation
- js2doxy.pl hier (zip) herunterladen
- Skript in das Verzeichnis /usr/bin/ kopieren (je nach Betriebssystem und Distribution eventuell verschieden)
jf-macbook:Dowloads jf$ sudo cp js2doxy.pl /usr/bin/js2doxy.pl
Dadurch kann man in jedem Verzeichnis auf das Skript zugreifen
Javascript Quellcode in C++ Pseudocode überführen, z.B. so
jf-macbook:js jf$ js2doxy.pl Task.js > Dokumentation/Task.cpp
- Verzeichnis mit .cpp Dateien als Sourcecode Verzeichnis in Doxygen auswählen
Fertig.
Eine Beispielseite als PDF Datei gibt es hier.
Damit das Ergebnis aussieht wie oben sind einige Dinge zu beachten. Alle Kommentare die von Doxygen berücksichtigt werden sollen stehen zwischen /** ... */. Da Javascript keine typsichere Sprache ist muss man einen Umweg gehen, um Doxygen die Informationen über den Typ von Parametern, bzw. den Rückgabetyp von Funktionen mitzuteilen. Dazu gibt es drei spezielle Annotationen:
@tparam TYPE PARAM DESCRIPTION Dient zur Dokumentation von Funktionsparametern, dabei muss neben dem Typ auch der Bezeichner des Parameters angegeben werden @treturn TYPE DESCRIPTION Dient zur Dokumentation des Rückgabewertes einer Funktion @type TYPE Dient zur Definitions des Typs einer Variable
Außerdem führt das Perl Skript noch die Annotation @ctor ein, mit Hilfe dieser kann man einen gesonderten Kommentar für den Konstruktor hinterlegen. Ansonsten werden folgende Annotationen unterstützt: @class, @file, @fn, @interface, @var
Folgendes Beispiel zeigt den Anfang einer Klasse samt Dokumentation:
/**
* @class GanttChart
* Hauptklasse des Clients. Kapselt die gesamte Programmlogik
* des Clients enthält Funktionen zur Erzeugung der grafischen
* Benutzerschnittstelle.
*
* @author Johannes Fuerwentsches
*
* @ctor Kontruktor der Klasse, erzeugt eine neue Instanz.
*
* @tparam int id ID des DOM Elements an das das Gantt-Diagramm gehangen wird
* @tparam Date start Startdatum
* @tparam int showWeeks Anzahl Wochen
* @tparam int width Breite des gesamten Diagramms
* @tparam int height Hoehe des gesamten Diagramms
* @tparam string jsonString Daten für das Diagramm als JSON String
*/
function GanttChart(id, start, showWeeks, width, height, jsonString) {
// Übergebenen JSON String in Objekt parsen
var jsonObject = JSON.parse(jsonString);
/**
* Eindeutige ID dieses Gantt-Diagramms.
* @type int
*/
this._id = id;