30 May 2005

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:

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.
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

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.

3 Sep 2004


I was browsing the mailing list archives of SE|PY this morning while downloading its latest release. I wanted to read more about the new Javadoc comment auto generation feature mentioned on Alessandro's blog. It was a nice surprise to see a huge activity on the list from guys like Colin Moock, Nigel Pegg and Giacomo 'Peldi' Guilizzoni. They are not sparing of good words about the project and they also give some good ideas about new features and improvements. Hopefully this will help SE|PY to evolve and become a dominant ActionScript editor. The fact that it has been used inside Macromedia speaks a lot. I don't know much about the status of MacOS port, but some time ago Mike Chambers has posted a step by step guide to getting the SE|PY ActionScript editor to run on OS X.

I'm using SE|PY everyday since its 0.9.x days and I'm really happy with it. There are frequent updates, bug fixes, new configuration possibilities and not on the last place, its free. Its up to you to decide how much you can donate to this great open source project.



Blog Search

Blog Categories

Blog posts

Recommended sites