You can add ASDoc comments to class, property, method, and metadata elements to document ActionScript classes. For more information on documenting MXML files, see Documenting MXML files.

Documenting classes

The ASDoc tool automatically includes all public classes in its output. Place the ASDoc comment for a class just before the class declaration, as the following example shows:

/**
* The MyButton control is a commonly used rectangular button.
* MyButton controls look like they can be pressed.
* They can have a text label, an icon, or both on their face.
*/
public class MyButton extends UIComponent {
}

This comment appears at the top of the HTML page for the associated class.

To configure ASDoc to omit the class from the output, insert an @private tag anywhere in the ASDoc comment, as the following example shows:

/**
* @private
* The MyHiddenButton control is for internal use only. 
*/
public class MyHiddenButton extends UIComponent {
}

Documenting properties

The ASDoc tool automatically includes all public and protected properties in its output. You can document properties that are defined as variables or defined as setter and getter methods.

Documenting properties defined as variables

Place the ASDoc comment for a public or protected property that is defined as a variable just before the var declaration, as the following example shows:

/**
*The default label for MyButton.
* 
*@default null 
*/
public var myButtonLabel:String;

A best practice for a property is to include the @default tag to specify the default value of the property. The @default tag has the following format:

@default value 

This tag generates the following text in the output for the property:

The default value is value. 

For properties that have a calculated default value, or a complex description, omit the @default tag and describe the default value in text.

ActionScript lets you declare multiple properties in a single statement. However, this does not allow for unique documentation for each property. Such a statement can have only one ASDoc comment, which is copied for all properties in the statement. For example, the following documentation comment does not make sense when written as a single declaration and would be better handled as two declarations:

/** 
 * The horizontal and vertical distances of point (x,y)
 */
public var x, y;// Avoid this 

ASDoc generates the following documentation from the preceding code:

public var x
    The horizontal and vertical distances of point (x,y)

public var y
    The horizontal and vertical distances of point (x,y)

Documenting properties defined by setter and getter methods

Properties that are defined by setter and getter methods are handled in a special way by the ASDoc tool because these elements are used as if they were properties rather than methods. Therefore, ASDoc creates a property definition for an item that is defined by a setter or a getter method.

If you define a setter method and a getter method, insert a single ASDoc comment before the getter, and mark the setter as @private. Adobe recommends this practice because usually the getter comes first in the ActionScript file, as the following example shows:

/**
* Indicates whether or not the text field is enabled.
*/
public function get html():Boolean {}; 

/**
* @private
*/
public function set html(value:Boolean):void {};

The following rules define how ASDoc handles properties defined by setter and getter methods:

• If you precede a setter or getter method with an ASDoc comment, the comment is included in the output.
• If you define both a setter and a getter method, only a single ASDoc comment is needed - either before the setter or before the getter.
• If you define a setter method and a getter method, insert a single ASDoc comment before the getter, and mark the setter as @private.
• You do not have to define the setter method and getter method in any particular order, and they do not have to be consecutive in the source-code file.
• If you define just a getter method, the property is marked as read-only.
• If you define just a setter method, the property is marked as write-only.
• If you define both a public setter and public getter method in a class, and you want to hide them by using the @private tag, they both must be marked @private.
• If you have only one public setter or getter method in a class, and it is marked @private, ASDoc applies normal @private rules and omits it from the output.
• A subclass always inherits its visible superclass setter and getter method definitions.

Documenting methods

The ASDoc tool automatically includes all public and protected methods in its output. Place the ASDoc comment for a public or protected method just before the function declaration, as the following example shows:

/**
* This is the typical format of a simple multiline documentation comment
* for the myMethod() method.
*
* <p>This is the second paragraph of the main description
* of the <code>myMethod</code> method.
* Notice that you do not use the paragraph tag in the
* first paragraph of the description.</p>
* 
* @param param1 Describe param1 here.
* @param param2 Describe param2 here.
* 
* @return A value of <code>true</code> means this; 
* <code>false</code> means that.
*
* @see someOtherMethod
*/
public function myMethod(param1:String, param2:Number):Boolean {}

If the method takes an argument, include an @param tag for each argument to describe the argument. The order of the @param tags in the ASDoc comment should match the order of the arguments to the method. The @param tag has the following syntax:

@param paramName description 

Where paramName is the name of the argument and description is a description of the argument.

If the method returns a value, use the @return tag to describe the return value. The @return tag has the following syntax:

@return description 

Where description describes the return value.

Documenting metadata

Flex uses metadata tags to define elements of a component. ASDoc recognizes these metadata tags and treats them as if there were properties or method definitions. The metadata tags recognized by ASDoc include:

• [Bindable]
• [DefaultProperty]
• [Effect]
• [Event]
• [Style]

For more information on these metadata tags, see Metadata Tags in Custom Components in Creating and Extending Adobe Flex 3 Components.

Documenting bindable properties

A bindable property is any property that can be used as the source of a data binding expression. To mark a property as bindable, you insert the [Bindable] metadata tag before the property definition, or before the class definition to make all properties defined within the class bindable.

When a property is defined as bindable, ASDoc automatically adds the following line to the output for the property:

This property can be used as the source for data binding.

For more information on the [Bindable] metadata tag, see Metadata Tags in Custom Components in Creating and Extending Adobe Flex 3 Components.

Documenting default properties

The [DefaultProperty] metadata tag defines the name of the default property of the component when you use the component in an MXML file.

When ASDoc encounters the [DefaultProperty] metadata tag, it automatically adds a line to the class description that specifies the default property. For example, see the List control in Adobe Flex Language Reference.

For more information on the [DefaultProperty] metadata tag, see Metadata Tags in Custom Components in Creating and Extending Adobe Flex 3 Components.

Documenting effects, events, and styles

You use metadata tags to add information about effects, events, and styles in a class definition. The [Effect], [Event], and [Style] metadata tags typically appear at the top of the class definition file. To document the metadata tags, insert an ASDoc comment before the metadata tag, as the following example shows:

/**
* Defines the name style.
*/
[Style "name"]

For events and effects, the metadata tag includes the name of the event class associated with the event or effect. The following example shows an event definition from the Flex mx.controls.Button class:

/**
* Dispatched when the user presses the Button control.
* If the <code>autoRepeat</code> property is <code>true</code>,
* this event is dispatched repeatedly as long as the button stays down.
*
* @eventType mx.events.FlexEvent.BUTTON_DOWN
*/
[Event(name="buttonDown", type="mx.events.FlexEvent")]

In the ASDoc comment for the mx.events.FlexEvent.BUTTON_DOWN constant, you insert a table that defines the values of the bubbles, cancelable, target, and currentTarget properties of the Event class, and any additional properties added by a subclass of Event. At the end of the ASDoc comment, you insert the @eventType tag so that ASDoc can find the comment, as the following example shows:

/**
* The FlexEvent.BUTTON_DOWN constant defines the value of the 
* <code>type</code> property of the event object 
* for a <code>buttonDown</code> event.
*
* <p>The properties of the event object have the following values:</p>
* <table class=innertable>
* <tr><th>Property</th><th>Value</th></tr>
* ...
* </table>
*
* @eventType buttonDown
*/
 public static const BUTTON_DOWN:String = "buttonDown"

The ASDoc tool does several things for this event:

• In the output for the mx.controls.Button class, ASDoc creates a link to the event class that is specified by the type argument of the [Event] metadata tag.
• ASDoc copies the description of the mx.events.FlexEvent.BUTTON_DOWN constant to the description of the buttonDown event in the Button class.

For a complete example, see the mx.controls.Button and mx.events.FlexEvent classes.

For more information on the [Effect], [Event], and [Style] metadata tags, see Metadata Tags in Custom Components in Creating and Extending Adobe Flex 3 Components.