Using Eclipse and Ant to publish AS3 API Documents (AsDocs)
Ever since I started working with ActionScript 3 way back in the summer of 2007 and for the entire two plus years that I’ve been working on FoxR, I have had considerable trouble generating AsDoc API documentation.
Not that making AsDocs has ever really been easy, but back when I was working prominently in ActionScript 2, there was a handy and ridiculous simple program As2Doc that provided a simple and intuitive way to generate clean and professional looking API documents.
Sadly, I have yet to see a program like As2Doc for ActionScript 3. The good news is, however, that Adobe does provide an AsDoc application as part of both the Flex/Flash Builder platform install and the free Flex SDK packages. Simply called asdoc.exe, this nifty little app will take you AS3 files and generate the same style documentation as those found at Adobe LiveDocs.
The one major drawback of this program is that it’s a command line tool. To get it to compile your AsDocs properly, you have to write one heck of a long command string. And if you mess up one character, you have to keep tweaking it until you get it right. When you work in a fast paced and agile environemnt like I do, this is not a good solution. I knew there had to be a better way. So I did some Googling and finally came across one.
Compile AsDocs with an Ant Build script
I’ve been familiar with Apache Ant since back in my days with Starwood Hotels where our individual development sandboxes were compiled and managed by numerous ant build scripts. If you’re not familiar with them, they consist of one XML based file usually called build.xml and one or more optional files that defined a number of target tasks like compiling JAR files in Java or running the asdoc.exe for AsDoc compilation.
Doing Google searches I came across numerous examples of these Ant build scripts to compile ASDocs. But once again, Ant is a command line tool and I wanted a way to steamline both the editing and running of these scripts (otheriwse I’d just run asdoc.exe from the command line itself). I found numerous references to the ease of using Eclipse’s built in support for ant and chose to go that route.
The one major hurdle that I never could see to figure out was how to get my install of Eclipse Gallileo (which I downloaded with the PHP Development Tools plugin) to support both editing and running Ant scripts automatically. Out of the box, Eclipse was not providing me with the Ant Editor or Ant Builder tools I’d seen so many people referencing in their blog posts and tutotials. So I was stuck until I finally struck blog paydirt.
The solution turned out to be mind numbingly simple, but somehow took me a long time to dig. For Eclipse to automatically support Ant within the editor, you need to download the Java Development Tools (or JDT) plugin. A quick guide to performing this update in Flex 3 (which works the same across all Eclipse and Eclipse based Flex/Flash Builder IDEs) is available on gunua.com and I am Josh.com.
So with the JDT plug-in installed, I finally was able to edit my build.xml file within Eclipse by right clicking and choosing Open With… > Ant Editor and then running it via Run As… > Ant Build . A few bug fixes to some error found in the code while compiling and Wha-Lah, at long last I had FoxR Api Docs.
The Ant script that I ended up using (with obviuos changes for my library and local paths) was found at Ruben’s Blog. I’ve posted a copy of his script Zip file in the Appendix of this post for convineince.
I hope this post is helpful to anyone who might be strugglign with getting set up as I was.
Appendix: Downloads
Ruben’s Ant Build Files Zip
