Documenting with as2api

A month ago I started a research on the available ActionScript documentation software. I knew already most of the tools, but I've never needed such a program before and this time I had to look a little bit deeper. Here I'm going to summarize the impressions that I got:

AS2docGenerator

Nice project that has not been updated for a long time. I didn't find a way to generate docs recursively from package folders and it requires @class or @interface comment tags.

BLDoc

A promising tool with a good option for Flash IDE documentation that I actually don't need. The community edition works only 5000 lines of code and this makes it unsuitable in my case.

ActionDoc

This one has not been updated for more than an year. The author has put an effort in the UI, but I personally don't find it very useful.

ASDocGen

The 0.1 version number discouraged me from testing this one.

VisDoc

A mature nice looking tool available only for Apple platform. It's commercial and the price seems to be fair.

AS2Doc

May be the best tool on the market, but the price is unaffordable for my project.

Natural Docs

Great software that supports a large number of programming languages. My personal problems with it are the non-javadoc comment format and the feature heavy output.

I have seen all these before so when I found the as2api project it was totally new for me. The good thing about as2api is that it supports a standard set of JavaDoc tags making your code compatible with other documenting tools. It's implemented in Ruby and it looks like a free software. The author hasn't mentioned a license, but I believe that the rights granted are close to GPL, MIT or a similar OSI compatible license. The as2api output was fair enough for me and I decided to go with it for the EnFlash documentation.

I downloaded the Windows all-in-one executable and it worked well, but it didn't contain all the latest fixes and improvements. So I decided to try the CVS copy and to spend some time with the interpreter installation and command line execution. Lately I hear only positive opinions about Ruby and I was happy that I had a reason to play with it. The as2api scripts are very clear and I stared to make some changes needed. I had to hardcode a few strings because currently there're still not input parameters implemented. At the end I finished with a customized version that contains the following differences:

• Lots of tag changes and fixes
• Valid XHTML output
• Simplified and enhanced CSS

My revisions are available for download and I hope that David will include them in the original as2api code.

The documentation of the upcoming EnFlash release is a sample of as2api usage, but currently only the EnFlash and EnFlashObject classes are commented.

The Ruby syntax still looks a little strange to me and that's may be because of my programming background. The language is powerful, there's a growing community around it and it's future looks bright.