Specifications

264
CHAPTER 13
In this example, the source code for the Button class is in the directory C:\flex\frameworks\source\mx\controls.
The output is written to C:\flex\bin\flex-framework-asdoc directory.
To view the output, open the file C:\flex\bin\flex-framework-asdoc\index.html. For more information on running
the
asdoc command, see “Running the ASDoc tool” on page 280.
Creating ASDoc comments
A standard programing practice is to include comments in source code. The ASDoc tool recognizes a specific type
of comment in your source code and copies that comment to the generated output. The ASDoc tool recognizes
the following formatting and parsing rules for comments.
Writing an ASDoc comment
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 in the ActionScript or MXML file, 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 of the classes that ship with Flex contain the ASDoc comments that appear in the Adobe Flex Language
Reference. For example, view the mx.controls.Button class for examples of ASDoc comments.