While writing my bachelor’s thesis, I thought it would be useful to include source code documentation for some JavaScript classes as an appendix. In my view, interested readers can understand certain constructs most quickly and easily if they can see which methods or functions occur where. Since I am writing my thesis in LaTeX, Doxygen immediately came to mind: I knew it included a TeX export alongside its excellent HTML export.
Unfortunately, I discovered that Doxygen does not support JavaScript out of the box. Fortunately, there is a workaround. Jörg Schaible wrote a Perl script called js2doxy that parses JavaScript code and generates a kind of C++ pseudocode. Doxygen can then process that, giving you its usual clean output in HTML and TeX.
As a Perl novice, I was briefly put off. I also could not find anywhere to download the script. But after a little reading, it turned out to be incredibly easy. I copied and pasted the script into a file, and I have uploaded it here to make things easier.
Quick guide to JavaScript documentation with Doxygen
-
Download js2doxy.pl here (ZIP).
-
Copy the script into /usr/bin/ (this may vary depending on your operating system and distribution).
jf-macbook:Dowloads jf$ sudo cp js2doxy.pl /usr/bin/js2doxy.plThis makes the script accessible from any directory.
-
Convert the JavaScript source code into C++ pseudocode, for example:
jf-macbook:js jf$ js2doxy.pl Task.js > Dokumentation/Task.cpp -
Select the directory containing the .cpp files as the source code directory in Doxygen.
Done.
An example page as a PDF is available here.
A few things need attention to get the result described above. All comments that Doxygen should process go between /** … */. Since JavaScript is not a type-safe language, you need a workaround to tell Doxygen about parameter types and function return types. There are three special annotations for this:
@tparam TYPE PARAM DESCRIPTION Documents function parameters; both the type and the parameter name must be specified
@treturn TYPE DESCRIPTION Documents a function’s return value
@type TYPE Defines the type of a variable
The Perl script also introduces the @ctor annotation, which lets you provide a separate comment for the constructor. The following annotations are also supported: @class, @file, @fn, @interface, @var.
The following example shows the beginning of a class with its documentation:
/**
* @class GanttChart
* Main client class. Encapsulates all client application logic
* and contains functions for creating the graphical
* user interface.
*
* @author Johannes Fuerwentsches
*
* @ctor Class constructor; creates a new instance.
*
* @tparam int id ID of the DOM element to which the Gantt chart is attached
* @tparam Date start Start date
* @tparam int showWeeks Number of weeks
* @tparam int width Width of the entire chart
* @tparam int height Height of the entire chart
* @tparam string jsonString Chart data as a JSON string
*/
function GanttChart(id, start, showWeeks, width, height, jsonString) {
// Parse the supplied JSON string into an object
var jsonObject = JSON.parse(jsonString);
/**
* Unique ID of this Gantt chart.
* @type int
*/
this._id = id;