Life near the Frontier

The last few months I've been working on an API written in JavaScript (let's call it JSAPI) at work. Naturally I looked for a Doxygen-like tool to generate the documentation. It is very surprising that there are only a handful of such tools.

First, I tried out JSDoc. It's simple and easy to use; plus the output looks like something out of JavaDoc. The problem is, it does not handle string containing JavaScript code (the kind of string you'd feed to eval()) correctly.

Next, I tried JsDoc Toolkit. It is okay, but there does not seem to be a way to control the output. What I want to achieve is grouping functions in a big class by functionality. JsDoc Toolkit simply outputs all functions sorted alphabetically, so I end up with GetThings() functions at the top and SetThings() at the bottom. Lots of scrolling and eye straining needed to find functions I want.

Finally, I followed the recommendation from "The State of JavaScript Documentation Tools" article. I decided to switch to Natural Docs. After a painful day of converting my existing comments into Natural Docs format; I'm quite happy with the output. My only gripe is that there is only 1 file for all functions in our API. I'd prefer a way to output 1 output file for each class. I really like the layout of the output, though.

This whole process gives me the feeling that support for JavaScript documentation is rather minimum even though it is (very?) popular. After all, it's the only scripting language for a browser. Why is it so? Is it because no one has used it for a large API yet? What about Google Maps API? (Actually I wonder what Google uses to generate their documentation. If you know, please tell me by commenting.)

Then I realized that this is the problem with any JavaScript tool. For example, until now I haven't found a satisfactory IDE for JavaScript. Generic text editor is fine (I'm still using EditPlus myself), but navigating a big JSAPI file (thousands of lines) is a pain. I want something like Visual Studio's automatically-generated drop-down list of functions. For now, the best solution I found is Aptana Studio. But honestly, it feels slow and clunky to me. The only reason I'm using it is for its auto-generated function index.

If I think about it, it feels odd that there is no nice IDE for such a popular language. I'm curious what other JSAPI developers use. Surely they don't just use a generic text editor?