Javascript Code Dokumentation mit Doxygen

19. November 2010

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

  1. js2doxy.pl hier (zip) herunterladen
  2. Skript in das Verzeichnis /usr/bin/ kopieren (je nach Betriebssystem und Distribution eventuell verschieden)

    Dadurch kann man in jedem Verzeichnis auf das Skript zugreifen
  3. Javascript Quellcode in C++ Pseudocode überführen, z.B. so
  4. 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:

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:

Über

Hi, ich bin Johannes! Ich arbeite als IT Projektleiter bei MEHRKANAL in Essen und beschäftige mich auch in meiner Freizeit gerne mit IT Themen. Dabei interessieren mich sowohl die technischen Aspekte (aktuell GitLab CI, docker, RaspberryPi, Cloudcomputing, uvm.), aber auch methodische Themen wie Agilität, Produktentwicklung oder IT Outsourcing.

Ein Kommentar

zu Javascript Code Dokumentation mit Doxygen.
  1. Meike
    |

    Cool! Funktioniert!!!

Kommentar hinterlassen

Ich freue mich auf Feedback!

Please wait...