Trepanning for gold

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.

Previous

Flash AS3: How to get useful error statements from Flash

Next

Flash AS3: dynamically draw a mask with lines

7 Comments

  1. Ribs

    The amount of time this tutorial and script just saved me is just too awesome. Thank you for this!

  2. Ribs

    Ok one setback. Either I’m commenting my code wrong for asDocs or this tool does not pick up the asDoc(javadoc) comments. my comment is formed like:

    /**
    * some words
    * some more words
    */
    

    Can you confirm that this tool does not pick up comments?

    thx

  3. Ribs

    Solved it. The asDoc generator is super sensitive to the formatting of the comments. one little space off and it doesn’t pick up the comment. The format I got to work is this, exactly spaced as it appears here:

    /**
     *  some words
     *  some more words
     **/
    

    Pay special attention to the spacing.

  4. admin

    @Ribs
    I haven’t noticed that issue with the spacing. Getting the hang of the comments is tricky though. Always place your comment directly above the line you are commenting. For example, general info about the class should be placed just before the “public class…” statement. The <br> tag seems to have been deprecated because ASDoc ignores it. And, if you use any parameters, such as @returns or @author, they must be the LAST item in a comment. If you place them first, ASDoc ignores the comment.

    For the class comments (the ones above the “public class…” statement), format your comments as follows to generate the abbreviated description for the listings pages:

    /**
     * This is the abbreviated description for the class listing. This is  
     * more info that will only appear when you open the documentation 
     * for the class. 
     */
    

    The first period tells ASDoc where to break the comment for the listing pages.

  5. admin

    I’ve update the post to provide the code needed to add flash-specific packages to your classes. if you get an error that a package can’t be found (such as fl.motion.*), it is probably flash-specific and not packaged with the Flex SDK. Find the files and add them to your compile path. Voila! Thanks kirupa forum!

  6. I am getting an error the program can’t start because MSVCR71.dll is missing from your computer. try reinstalling the program to fix this problem.

    can you help me with this?

  7. admin

    sorry, that sounds like an issue with your computer, not with the software. Just Google the error that you’re getting and you should be able to find someone who knows something about I.T. (not me) to help you pinpoint the issue.

Powered by WordPress & Theme by Anders Norén