Creating ASDoc comments in ActionScript

An ASDoc comment consists of the text between the characters /** that mark the beginning of the ASDoc comment, and the characters */ that mark the end of it. The text in a comment can continue onto multiple lines.

Use the following format for an ASDoc comment:

/**  
* Main comment text. 
*  
* @tag Tag text. 
*/

As a best practice, prefix each line of an ASDoc comment with an asterisk (*) character, followed by a single white space to make the comment more readable, and to ensure correct parsing of comments. When the ASDoc tool parses a comment, the leading asterisk and white-space characters on each line are discarded; blanks and tabs preceding the initial asterisk are also discarded.

The ASDoc comment in the previous example creates a single-paragraph description in the output. To add additional comment paragraphs, enclose each subsequent paragraph in HTML paragraph tags, <p></p>. You must close the <p> tag, in accordance with XHTML standards, as the following example shows:

/** 
* First paragraph of a multiparagraph description. 
* 
* <p>Second paragraph of the description.</p> 
*/

All the classes that ship with Flex contain the ASDoc comments that appear in the ActionScript 3.0 Reference for the Adobe Flash Platform. For example, view the mx.controls.Button class for examples of ASDoc comments.

Place an ASDoc comment immediately before the declaration for a class, interface, constructor, method, property, or metadata tag that you want to document, as the following example shows for the myMethod() method:

/** 
* This is the typical format of a simple 
* multiline (single paragraph) main description  
* for the myMethod() method, which is declared in  
* the ActionScript code below. 
* Notice the leading asterisks and single white space 
* following each asterisk. 
*/ 
public function myMethod(param1:String, param2:Number):Boolean {}

The ASDoc tool ignores comments placed in the body of a method and recognizes only one comment per ActionScript statement.

A common mistake is to put an import statement, or other code line or metadata tag, between the ASDoc comment for a class and the class declaration. Because an ASDoc comment is associated with the next ActionScript statement in the file after the comment, this example associates the comment with the import statement, not the class declaration:

/** 
* This is the class comment for the class MyClass. 
*/ 
import flash.display.*; // MISTAKE - Do not to put import statement here. 
class MyClass { 
}

The main body of an ASDoc comment begins immediately after the starting characters, /**, and continues until the tag section, as the following example shows:

/**  
* Main comment text continues until the first tag. 
*  
* @tag Tag text. 
*/

The first sentence of the main description of the ASDoc comment should contain a concise but complete description of the declared entity. The first sentence ends at the first period followed by a space, tab, or line terminator.

ASDoc uses the first sentence to populate the summary table at the top of the HTML page for the class. Each type of class element (method, property, event, effect, and style) has a separate summary table in the ASDoc output.

The tag section begins with the first ASDoc tag in the comment, defined by the first @ character that begins a line, ignoring leading asterisks, white space, and the leading separator characters, /**. The main description cannot continue after the tag section begins.

The text following an ASDoc tag can span multiple lines. You can have any number of tags, where some tags can be repeated, such as the @param and @see tags, while others cannot.

The following example shows an ASDoc comment that includes a main description and a tag section. Notice the use of white space and leading asterisks to make the comment more readable:

/** 
* Typical format of a simple multiline comment. 
* This text describes the myMethod() method, which is declared below. 
* 
* @param param1 Describe param1 here. 
* @param param2 Describe param2 here. 
* 
* @return Describe return value here. 
* 
* @see someOtherMethod 
*/ 
public function myMethod(param1:String, param2:Number):Boolean {}

For a complete list of the ASDoc tags, see ASDoc tags.

By default, the ASDoc tool generates output for all public and protected elements in an ActionScript class, even if you omit the ASDoc comment for the element. The ASDoc tool ignores all elements defined as private.

To make ASDoc ignore a public or protected element, insert an ASDoc comment that contains the @private tag anywhere in the comment. The ASDoc comment can contain additional text along with the @private tag, which is also excluded from the output.

ASDoc generates output for all public classes in the list of input classes. You can specify to ignore an entire class by inserting an ASDoc comment that contains the @private tag before the class definition. The ASDoc comment can contain additional text along with the @private tag, which is also excluded from the output, as the following example shows:

/** 
* This class is omitted from the output. 
* 
* @private 
*/ 
public class MyClass { 
}

By default, the ASDoc tool copies information and a link for all elements inherited by a subclass from a superclass. In some cases, a subclass might not support an inherited element. You can use the [Exclude] metadata tag to cause ASDoc to omit the inherited element from the list of inherited elements.

The [Exclude] metadata tag has the following syntax:

[Exclude(name="elementName", kind="property|method|event|style|effect")] 

For example, to exclude documentation on the click event in the MyButton subclass of the Button class, insert the following [Exclude] metadata tag in the MyButton.as file:

[Exclude(name="click", kind="event")] 

You can use selected HTML entities and HTML tags to define paragraphs, format text, create lists, and add anchors. For a list of the supported HTML tags, see Summary of commonly used HTML elements.

Write the text of an ASDoc comment in XHTML-compliant HTML. That means your HTML syntax has to conform to XML syntax rules. For example, close all HTML tags, such as <p> and <code> tags, by inserting the closing </p> or </code> tag.

The following example comment contains HTML tags to format the output:

/** 
* This is the typical format of a simple multiline 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 {}

The ASDoc tool can fail if your source files contain non-UTF-8 characters such as curly quotes. If it does fail, the error messages it displays refers to a line number in the class. That message helps you track down the location of the special character.

ASDoc passes all HTML tags and tag entities in a comment to the output. Therefore, if you want to use special characters in a comment, enter them using HTML code equivalents. For example, to use a less-than (<) or greater-than (>) symbols in a comment, use &lt; and &gt;. To use the at-sign (@) in a comment, use &#64;. Otherwise, these characters are interpreted as literal HTML characters in the output.

For a list of common HTML tags and their entity equivalents, see Summary of commonly used HTML elements.

Because asterisks (*) are used to delimit comments, ASDoc does not support asterisks within a comment. To use an asterisk in an ASDoc comment, use the double tilde (~~).

The ASDoc style sheet contains a class called hide, which you use to hide text in an ASDoc comment by setting the class attribute to hide. Hidden text does not appear in the ASDoc HTML output, but does appear in the generated HTML file. Therefore, do not use it for confidential information. The following example uses the hide 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. 
* 
* <span class="hide">This text is hidden.</span> 
* @eventType mx.events.FlexEvent.BUTTON_DOWN 
*/

The following rules summarize how ASDoc processes an ActionScript file:

• If an ASDoc comment precedes an ActionScript element, ASDoc copies the comment and code element to the output file.

• If an ActionScript element is not preceded by an ASDoc comment, ASDoc copies the code element to the output file with an empty description.

• If an ASDoc comment contains the @private ASDoc tag, the associated ActionScript element and the ASDoc comment are ignored.

• The comment text must precede any @ tags, otherwise the comment text is interpreted as an argument to an @ tag. The only exception is the @private tag, which can appear anywhere in an ASDoc comment.

• HTML tags, such as <p></p>, and <ul></ul>, in ASDoc comments are passed through to the output.

• HTML tags must use XML style conventions, which means there must be a beginning and ending tag. For example, close an <li> tag with a </li> tag.