60 Years of Misery...and Then You Die!!!

Documenting Code

Documentation of code is a necessary evil that all good programmers must, at some point in a project, do. Having let that paradigm slip at the beginning, I’m currently going through the process of ‘refactoring’ my JavaScript documentation for a project I’m working on. Taking time out from that, here’s a brief history of documenting the project’s JavaScript.

ScriptDoc

Initially I choose ScriptDoc; this wasn’t a conscious decision, but simply because it’s the default documentation spec used by Aptana. It certainly works well for small scripts with a handful of global functions and variables, but when it came to the more complicated object-oriented coding we’re employing in this project, it got hopeless confused.

This is due to the very nature of JavaScript using prototypal inheritance, rather than the classical inheritance found in, say Java and ActionScript. Many JavaScript users baulk at this way of writing object-oriented code, and as such there is a healthy community of JavaScript users trying to crowbar inheritance practices they’re more used to into it.

Consequently, the ways of implementing inheritance in JavaScript are vast and convoluted. ScriptDoc is just too broad a specification to be able to handle these intricases. The same can be said for Natural Docs; by trying to be something for everyone, it fails to work with JavaScript. Of course, both languages have a multitude of tags to precisely define what, say, the inner function of a constructor is actually doing, but that kind of misses the point of documenting; it should be as unobtrusive and intuitive as possible.

JsDoc Tookit

From this point it seemed the only logically conclusion would be to use a documentation tool specific to JavaScript; this lead to the JsDoc Toolkit. Easy to pick up and use, this tool started as the next version of JsDoc, a scripting tool written in Perl. JsDoc Toolkit differs by being written entirely in JavaScript, running through the Rhino JavaScript engine, a Java implementation of a JavaScript engine. This gives the tool access to the same environment of the code it’s documenting.

Ant

We’re all for smooth building practices here, so we wanted to integrate the running of JsDoc Toolkit into our build process as easily as possible. Currently we were using a Java task, filled with command line parameters and complicated attributes. This not only looked ugly, but was prone to errors. The logical conclusion was to write our own Ant task, wrapped around the JsDoc Toolkit.

This turned out to be an easier process than I would have thought; there is a lot of documentation around about how to write custom classes, and as all the work is done by the Rhino engine, which, like Ant is also written in Java, the coding was a breeze.

Unashamed plug follows: You can get your very own copy from Google Code here.

A Bug

For those of you into that kind of thing, just a quick note on a small bug that took up most of a weekend trawling through the source files to fix.

In it’s simplest form, to run the Rhino engine you supply it with a file name, and it will run it. This file name is pushed onto a static array, and is only removed when the Java runtime ends, i.e. the class is destroyed.

So, when running the newly created jsdoctoolkit ant task once in a build file, everything was fine. But running it twice in the same build file, strange things started to happen; the first task ran once as expected, but the second task ran twice. The more times you called the task, the more times it would run. Weird.

Here’s what was happening. When you started the build file, the static array was initialized. Then you run the ant task the first time, and which called Rhino, which appended the name of the file to the static array, and ran this file. Then you called the task again, which appended the file name to the static array again, so it now contains the same file twice, and ran through all these files. And so on.
This was very annoying, compounded by the fact there was no method to clear the static array and the array could only be accessed by a class in the same package.

The Future

Currently version 2 of the Toolkit is in beta, and it looks to be an even better tool This is in no small part due to the creator interacting with, and listening to, end-users. Hopefully it will be picked up by a wider audience.