ActionScript API Generators

Documentation for the Minimap component is coming soon. I'm currently trying out the handful of documentation generation tools available for ActionScript 2.0. Some of my initial comments:

Natural Docs

The first one I took a look at was Natural Docs. The output from Natural Docs is beautiful: it has a nice-looking layout, is well-organized, and even lists class descendents. I found this feature very useful when I was working with the Gallery2 API earlier this week. Natural Docs has javascript package menus and will also collapse packages that contain a single class or folder into one link. This means users only click once to view org.somepackage.SomeClass as long as org and org.somepackage contain no other classes or packages. This saves the time of clicking through org, somepackage, and SomeClass.

The big down-side to Natural Docs is the syntax for documenting your code. Each variable, method, or class you want to document needs to be preceded by Variable: varName, Function: funcName, or Class: className. I don't really see why this extra syntax is necessary but I suspect is has something to do with Natural Docs' ability to support such a wide variety of languages. For existing projects--especially large ones--this might be enough of a deterrent for people considering Natural Docs. I wouldn't want to be the one to add the necessary syntax to generate decent documentation for Flash's core classes (a project which isn't too far-fetched considering the useless LiveDocs website).

AS2API

While the output of this documentation generator isn't as nice to look at, documenting your code is much easier; especially if you're used Java. AS2API supports a lot of the Java documentation tags and produces output that is only as ugly as Sun's Java API. It doesn't have nifty features like Natural Docs' javascript package menus but it's very practical and produces meaningful output for Flash's core files without having to go in and modify all the documentation comments.

I'm still trying to decide how important it is that my docs look good. Do developers really care how the documentation looks? Will anyone else be looking at it? I guess I'll wait to try the free community edition of BLDoc and then make a decision.