Wednesday, December 26, 2007

Launching ASDoc with External Tools

While redoing the player, I have been writing a lot of actionscript lately. And by a lot I mean a ton. After I had everything working properly, the time came to go back through and clean it all up. In that process, I came across ASDoc, the documentation generator for actionscript. Like JavaDoc or PHPDocumentor, you mark up your code with multi-line comments, and after running the tool, you get a nice pretty set of HTML pages that make it understandable.

As usual, I dove right in. Marked up all of my methods and member variables and was ready to go. But, ASDoc has quite a few arguments to customize the output and using the shell to run this every time I made a change got old real fast.

Now enter External Tools from the Eclipse framework. If you haven't used external tools in the past, basically it allows you to configure and run mind numbing tasks click and go style. After digging through the flex mailing lists for a bit, I came across this. Problem solved.

But.... I had several projects I wanted to document and I didn't want a million of these external tool configurations all over the place. Another nice feature of External Tools is variable substitution on workspace and project levels. So, here is how to add the external tool to run asdoc on the currently open project:
  1. Click Run-> External Tools -> Open External Tools Dialog
  2. Click on the New Configuration button
  3. Name it Generate ASDoc
  4. For location, enter the path to asdoc. On windows, the default is C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\bin\asdoc.exe
  5. In the working directory, enter ${project_loc}
  6. In the arguments input, -source-path . -doc-sources ./com -window-title "${project_name}" -main-title "${project_name}"
  7. Click Apply
After you run "Generate ASDOC", you will get a new folder in your project called asdoc-oputput that contains the fruit of our labor. If you open up index.html, it will look something like this:

Pretty sexy, no?

About the Arguments

Here is a quick explanation of what the arguments in the above instructions do. You can view all of the available arguments here.

-source-path . Sets the working path for asdoc. Why not use ${project_loc} instead of setting the working directory? For some reason, external tools doesn't like spaces in its substitutions (even with proper escaping). Since the default workspace in flex builder contains spaces, this can be quite a pickle. Setting the working directory gets around this (thanks Jimmy!).

-doc-sources ./com Tells ASDoc to generate docs for everything inside ${project_loc}/com/. If you are documenting a Flex Library Project, you can keep the code as is. Note: If you are trying to document a normal Flex Project (ie your code is in ${project_loc}/src/), change the arguments appropriately.

-window-title "${project_name}" -main-title "${project_name}" Sets the HTML title and any other title references to the name of your project.


Aaron said...

I cannot tell you how useful this post was! Thank you so much for this insightful tutorial. The External Tools implementation saves a ton of time and is much less problematic than the traditional command line.

Muzak said...

About a year ago I asked for an enhancement in the Flex Bug Tracker to have this documented.

You can vote for the enhancement here:

Jesse Freeman said...

Great post. Been using Ant in FDT but was having some trouble getting it to work constantly in FlexBuilder 3. This is a big hep!

Anonymous said...

Using Flex Builder 3 and I've followed the instructions but I keep getting a message Variable references empty selection: ${project_loc}

Do I need to set this variable up somewhere?

Lucas said...

$project_loc should be automatically defined for you. Are you using the standalone flex builder? Ant integration requires that you use the eclipse plugin.

S├ębastien said...

When Flex prompts that ${project_loc} is empty, it just means that you have to select (or highlight) the project you want to be doc'd in the left part of Flex IDE (the project navigator, in fact)...

Anybody knows something about using the external-library-path with sources folders instead of swc file ?

Nico said...

Excellent post, many thanks!