30 May 2005
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:
- 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
- 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.
- 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.
- The 0.1 version number discouraged me from testing this one.
- A mature nice looking tool available only for Apple platform. It's commercial and the price seems to be fair.
- 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
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.