wasted potential

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.