Flash AS3: The simple way to create an API reference with ASDoc

I have known for some time that I could generate an Actionscript API Reference for my own class packages using ASDoc, but it’s a command-line tool and I haven’t done any command-line programming in about 12 years, so I didn’t want to deal with the hassle. Then, I found this blog post by Derek Griggs (link is gone now, but go read his blog anyway – it’s good) where he created a batch file that he could simply run when he wanted to generate the docs. Genius! And since ASDoc comes packaged with the FREE Flex SDK, anyone can do this (well, almost anyone). The following instructions are for Windows users. Sorry Apple heads.

Step 1: Download the Free Flex SDK from Adobe here

Step 2: Unzip the downloaded file and place it somewhere logical on your hard drive. I placed it in the C:/Program Files/Adobe/ folder.

Step 2.5 (Optional): open the flex config XML file found here: [flex sdk folder]/frameworks/flex-config.xml and tweak your settings. For example, you may want to set the <strict> option to false.

Step 3: Open a simple text editor like Notepad and create the following file (or download the sample packet here and use the included batch file sample):

cls
set path=C:\Program Files\Adobe\flex_sdk_4.1\bin
asdoc.exe -source-path classes -doc-sources classes -window-title "Wasted Potential Sample AS Documentation" -main-title "Sample Documentation" -footer "This is a test<br/>www.wastedpotential.com" -output docs
pause

Step 4: Save this file as “asdoc.bat” in a folder one level up from your class package(s). For example, In my Flash projects, I usually have a folder named “classes” that contains all of my class packages, so I save this batch file outside of the “classes” folder. When I run the batch file, it will create a folder named “docs.”

Step 5: Modify the file as needed. The file is simple, but I’ll explain it piece by-piece:

cls

“Clear screen” removes any other output from the terminal window.

set path=C:\Program Files\Adobe\flex_sdk_4.1\bin

This sets the path where your computer can find the executable file you wish to run. In this case, it is the location of asdoc.exe. If you placed the Flex SDK somewhere else, you will need to set this path for your configuration.

asdoc.exe

Runs the ASDoc executable

-source-path classes
-doc-sources classes

Options that tell ASDoc where to find the classes it is documenting.

-window-title "Wasted Potential Sample AS Documentation"
-main-title "Sample Documentation"
-footer "This is a test<br/>www.wastedpotential.com"

These are more options. They simply set some text in the output files.

-output docs

This option specifies the folder where your new API will be created. If it doesn’t exist yet, ASDoc will create it. There are more options than this, but these are the important ones. Click here to check out some of the other options.

pause

This simply keeps the terminal window open. Without this line, the terminal window closes and you can’t view any error messages.

Step 6: Save the file again and double-click it to run it.

Step 7: Wait a few seconds until it is done running. If your classes have errors, the script will fail. Fix the errors and try again. If it succeeds, you will now have a full set of Actionscript API docs for your classes. Open them up and check them out.

Now, you can go add valid Javadoc-style comments to your classes and you will have a professional API reference for your project. Sweet! Don’t know how to add Javadoc comments? Well, I created a sample class package and batch file for you to play with. You can download the sample here. There are also lots of resources on the web for how to write Javadoc comments. The best reference I have found is here.

IMPORTANT: ASDoc is a bit touchy and fails A LOT when trying to generate an API. Here are a few caveats:

• Your classes must not have any compiler errors or ASDoc will fail.
• Your javadoc comment syntax must be correct or ASDoc will fail with a cryptic error about
  “toplevel.xml”
• You must declare stage instances explicitly. If you use Flash and have “Automatically declare stage instances” turned on in the Actionscript 3.0 publish settings, ASDoc will fail, throwing an error for each stage instance name in your classes that doesn’t appear in the variable declarations.
• Even more annoying, if you use any open-source packages like Papervision, their syntax must also be flawless, or ASDoc will fail (in fact, ASDoc failed for me when trying to run it on a project with the Papervision3D package). For large projects, this can be a huge pain. So, you may want to run ASDoc on any open-source libraries first to make sure they compile correctly by themselves.
• if you use any flash packages that are not in the Flex SDK, you must add them to the compiler path. For example, the Flex SDK does not include the flash “fl” package (used for motion tween, etc). You can add the paths to the batch file if you can figure out where the files are. In the case of the “fl” package, add this option to the batch file:

  -compiler.source-path "C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\ActionScript 3.0\Classes"

  (that path is “C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\ActionScript 3.0\Classes”). Then, you may need to use the -exclude-classes option to prevent the additional classes from being added to the output.

If anyone knows how to modify these instructions for a Mac, let me know and I’ll update the post.

You can download the sample files here.