Tag: ASDoc

ASDocs are a great way to create an API for your AS3 classes. If you work on large projects with multiple developers, good documentation can be a big time saver – the other developers can access the public methods and properties of your classes without having to wade through your code.

I recently had an assignment building some animated components in Flash for a large Flex development project. Each component contained a dozen or so classes with a number of public methods and properties. Realistically, though, the Flex developer only needed to access the public methods and properties of a single container class for each component. The other classes just cluttered up the API with useless information. I also wanted to hide the references to stage instances in my component interface. While they are technically public properties, I didn’t want the Flex developer to reference them directly, so they shouldn’t appear in the API. Luckily, there is an easy way to hide things in ASDocs. Simply add the following comment above anything you want to exclude from your ASDocs:

/** @private */

This will exclude the element that follows from your ASDocs output. This can be used to hide a single property like this:

/** @private */
public var timeDisplay_mc:MovieClip; //this is a stage instance

Or it can be placed before the class definition to exclude an entire class from the ASDoc output:

package com.wastedpotential {
    import flash.display.MovieClip;

    /** @private */
    public class InvisibleClip extends MovieClip {

        ...stuff goes here...

    } //end class
} //end package

It’s a really simple way to clean up your API reference and hide all of the public elements that you don’t want other developers to have access to. I don’t bother creating ASDocs for many projects, but having a clean, useable API reference for large multi-developer projects is essential.

Flash AS3: Stop using “Automatically Declare Stage Instances”

By Andy

On December 27, 2010

In Actionscript/AS3, Flash

If you are compiling in the Flash IDE, you need to turn OFF the “Automatically Declare Stage Instances” option. It’s simple to do… go to File>Publish Settings, then click on the “Flash” tab and click the “Settings” button next to the Actionscript 3.0 dropdown. Simply uncheck the box and you’re done. It’s a crutch that is turned on by default in Flash and using it is a bad idea. Here are 4 quick reasons not to use it:

No more mystery variables in your classes. If you ever have to hand off your work to someone else, it’s really helpful to have all stage instances declared in your classes:
```
public var foo_mc:MovieClip //foo_mc is a stage instance
```
It’s just a courtesy to other developers who might have to deal with your code.
It fixes SOME inheritance problems. Flash is a little funny about class inheritance and it sometimes chokes on things that seem like they should be valid subclassing to me. But, I have found that I have a lot less trouble with it since I started explicitly declaring all stage instances.
Your code will integrate better with a Flex environment. I don’t use Flex (now FlashBuilder) much, but I do sometimes build fancy schmancy animated components for use with Flex. You have to declare all stage instances in your class variable declarations for this to work. You might never have to deal with this, but why not create a workflow that is more portable?
ASDocs requires it. If you want to create documentation for your classes using ASDocs, you must have all of your stage instances declared. Otherwise, it throws an error on each one that you didn’t declare.

I’m sure there are even more reasons than this, but those are the ones that I’ve found. Leaving “Automatically Declare Stage Instances” turned on is lazy, so knock it off.

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

By Andy

On August 27, 2010

In Actionscript/AS3, Flash

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.

Our lies make baby Jesus cry

Tag: ASDoc

Flash AS3: How to hide public properties, methods, and classes in your ASDocs

Flash AS3: Stop using “Automatically Declare Stage Instances”

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