JavaScript Documentation Tools

JavaScript documentation is a pain in the ass.

I’ve complained about this on my blog before, but I’ve spent the past week or so trying to test the handful of JavaScript documentation tools that are available and I’m actually starting to get mad. Why? Because there’s little standardization, and you have to be a computer scientist to get some of the tools to work.

Working on a Windows machine seems to further tie my hands, as (again) the tools all seem to use command line processes. While this isn’t a major handicap, I’m lucky in that I know what I’m doing — the average (or beginner) programmer is going to quickly get lost.

In an ongoing effort to explore my options as a JavaScript developer, here’s a review of the tools I’ve tried so far:

JS Doc Toolkit

After downloading the ZIP file, it’s pretty basic to extract. The project uses JAVA to walk the filesystem, parse your JS files, and build your documentation. The readme file is pretty self-explanatory, and walks you through using the command line (Mac, Linux, or Windows). I wrote a simple .BAT file to do the work for me… and I’m now a double-click away from fresh documentation.

YUI DOC

I’m already very critical of YUI, and I personally think this tool just sucks.

Not only do you have to know Python to run YUI DOC, but it doesn’t even work with the current version of Python! Are you kidding me? It needs to run on v2.4.3 – when v2.6.1 and v3.0.1 are available. That’s just retarded, and because I don’t feel like installing an older version of Python onto either of my machines (I have Vista and MacOSX) I simply gave up.

I also don’t like the output on YUI’s own documentation site, so I’m not really crying about this.

jGrouse

jGrouse is another JAVA-based tool which runs on top of the ANT platform.

Honestly, I had a hell of a time installing and running jGrouse. I had to re-install JAVA on my machine because I didn’t have the SDK with tools.jar installed… oy vey.

Once I finally got jGrouse running, I noticed that it didn’t pick up most of the comments I already had written for JS Doc Toolkit. Boo urns.

ScriptDoc

Here’s a framework you don’t have to install – it comes builtin with the Aptana IDE!

I haven’t been using the Aptana IDE much, but I might start. The interface is slick, and the fact that it has ScriptDoc builtin with the IDE is gravy.

Lessons Learned

If I weren’t doing a bunch of .NET development side-by-side with JavaScript, I would absolutely be using Aptana… and ScriptDoc. It’s by far the easiest documentation tool available, and clearly the best choice for Windows users.

JS Doc Toolkit is a close second, and (for now) the option I’m going with.

I have to say that it really bothers me that JavaScript documentation is not standarized at this point. Not only is setting up a tool a pain in the ass, but many of the tools want your documentation parameters in a specific order – which is just confusing. The parameters aren’t standardized across all of the documentation tools, which is even more confusing and frustrating if you want to change tools.

UPDATE (6/25/09): New post on Ext-Doc tool.