Asual

Monday,
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:

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.

« Previous Post | Next Post »

Trackbacks:

Left by [ NikO ] at Mon 19 April 2010, 4:15 PM

As2Api
J'ai enfin trouv� mon bonheur pour la g�n�ration de documentation � la JavaDoc.Je voulais un outil, simple, libre, et pas machine � vapeur, qui me demande pas de configurer 46 machins etc ....Cet outil, c'est as2api. Cela n�cessite...

Comments:

Left by Byron Saltysiak at Mon, 19 Apr 4:15 PM
as2api is indeed released under the GNU GPL. I too had trouble finding it quickly (perhaps we should suggest that they make it explicit on the website. Anyway I found the license in a file named "COPYING" in the SVN repo: http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/
as2api/COPYING?view=log&rev=50

Good luck with as2api - I agree that it is the best tool out there for the job.
Left by Rostislav at Mon, 19 Apr 4:15 PM
@Byron - Thanks for pointing this out. Long live as2api!

@codeNoob - The executable is too old. See instructions how to run the Ruby scripts at as2api website. It's not that hard.
Left by codeNoob at Mon, 19 Apr 4:15 PM
k, i'll check that out. thx 4 the fast answer.
Left by codeNoob at Mon, 19 Apr 4:15 PM
hola,
tested the first three doctools you mentioned too (plus as2api) and what you say is exactly my opinion. I downloaded as2api as an executable, so using it was no problem. But how to get started with your revision?
Left by Svetoslav Sotirov at Mon, 19 Apr 4:15 PM
The latest tests we conducted for generating documentation using Eclipse and following this article:
http://www.statik1.com/mt-weblog/archives/000092.html
Produced very nice results.

Projects

Syndication

Blog Search

Blog Categories

Blog posts

Recommended sites