Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_asdoc_asd.html
blob: 81d652e6bd301c10e8f4ced2acf9061bfc537996 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<meta name="DC.Type" content="topic"/>
<meta name="DC.Title" content="ASDoc"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe7_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>ASDoc</title>
</head>
<body id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe7_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe7_verapache"><!-- --></a>
<h1 class="topictitle1">ASDoc</h1>
<div>
<p>ASDoc is a command-line tool that you can use to create
API language reference documentation as HTML pages from the ActionScript
classes and MXML files in your Flex application.</p>
</div>
<div class="nested1" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fef_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fef_verapache"><!-- --></a>
<h2 class="topictitle2">About the ASDoc tool</h2>
<div>
<p>The ASDoc tool parses one or more ActionScript class definitions
and MXML files, and generates API language reference documentation
for all public and protected methods and properties. The ASDoc tool
also recognizes many types of metadata, such as the <samp class="codeph">[Bindable]</samp>, <samp class="codeph">[Event]</samp>, <samp class="codeph">[Style]</samp>,
and <samp class="codeph">[Effect]</samp> metadata tags. </p>
<p>You specify a single class, multiple classes, an entire namespace,
or any combination as inputs to the ASDoc tool. </p>
<p>ASDoc generates its output as a directory structure of HTML files
that matches the package structure of the input class files. Also,
ASDoc generates an index of all public and protected methods and
properties. To view the ASDoc output, open the index.html file in
the top-level directory of the output. </p>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fec_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fec_verapache"><!-- --></a>
<h3 class="topictitle3">Using ASDoc</h3>
<div>
<p>To use ASDoc, run the <samp class="codeph">asdoc</samp> command from
the bin directory of your Flex installation. For example, from the
bin directory, enter the following command to create output for
the Flex Button class:</p>
<pre class="codeblock"> asdoc -source-path C:\flex\frameworks\projects\framework\src
  -doc-classes mx.controls.Button
  -main-title "Flex API Documentation"
  -window-title "Flex API Documentation"
  -output framework-asdoc</pre>
<p>In this example, the source code for the Button class is in the
directory C:\flex\frameworks\projects\framework\src\mx\controls.
Use the <samp class="codeph">source-path</samp> option to specify where the
ASDoc tool looks for the source code, and the <samp class="codeph">doc-classes</samp> option
to specify the name of the class to process. </p>
<p>The ASDoc tool writes the output to C:\flex\bin\framework-asdoc
directory, as defined by the <samp class="codeph">output</samp> option. </p>
<div class="p">The ASDoc tool supports many options for specifying the files
to process. For example, instead of explicitly specifying the list
of files to process, you can use the <samp class="codeph">doc-sources</samp> option
to specify a directory name. The following example runs the ASDoc
tool on all files in the C:\flex\frameworks\projects\framework\src\mx\controls
directory:<pre class="codeblock">asdoc
-doc-sources C:\a\flex\flex\sdk\frameworks\projects\framework\src\mx\controls
-main-title "Flex API Documentation"
-window-title "Flex API Documentation"
-output framework-asdoc</pre>
</div>
<p>To view the output, open the file C:\flex\bin\framework-asdoc\index.html.
For more information on running the <samp class="codeph">asdoc</samp> command,
see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ffa_verapache">Using
the ASDoc tool </a>. </p>
</div>
</div>
</div>
<div class="nested1" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fed_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fed_verapache"><!-- --></a>
<h2 class="topictitle2">Creating ASDoc comments in ActionScript</h2>
<div>
<p>A standard programming 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. </p>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fee_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fee_verapache"><!-- --></a>
<h3 class="topictitle3">Writing an ASDoc comment</h3>
<div>
<p>An ASDoc comment consists of the text between the characters <samp class="codeph">/**</samp> that
mark the beginning of the ASDoc comment, and the characters <samp class="codeph">*/</samp> that
mark the end of it. The text in a comment can continue onto multiple
lines.</p>
<p>Use the following format for an ASDoc comment:</p>
<pre class="codeblock"> /**
 * Main comment text.
 *
 * @tag Tag text.
 */</pre>
<p>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. </p>
<p>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, <samp class="codeph">&lt;p&gt;&lt;/p&gt;</samp>.
You must close the <samp class="codeph">&lt;p&gt;</samp> tag, in accordance
with XHTML standards, as the following example shows:</p>
<pre class="codeblock"> /**
 * First paragraph of a multiparagraph description.
 *
 * &lt;p&gt;Second paragraph of the description.&lt;/p&gt;
 */</pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fff_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">Placing ASDoc comments</h3>
<div>
<p>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 <samp class="codeph">myMethod()</samp> method:</p>
<pre class="codeblock"> /**
 * 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 {}</pre>
<p>The ASDoc tool ignores comments placed in the body of a method
and recognizes only one comment per ActionScript statement.</p>
<p>A common mistake is to put an <samp class="codeph">import</samp> statement,
or other code line or metadata tag, between the ASDoc comment for
a class and the <samp class="codeph">class</samp> 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 <samp class="codeph">class</samp> declaration: </p>
<pre class="codeblock"> /**
 * This is the class comment for the class MyClass.
 */
 import flash.display.*; // MISTAKE - Do not to put import statement here.
 class MyClass {
 }</pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffe_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting ASDoc comments</h3>
<div>
<p>The main body of an ASDoc comment begins immediately after
the starting characters, <samp class="codeph">/**</samp>, and continues until
the tag section, as the following example shows: </p>
<pre class="codeblock"> /**
 * Main comment text continues until the first tag.
 *
 * @tag Tag text.
 */</pre>
<p>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. </p>
<p>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. </p>
<p>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, <samp class="codeph">/**</samp>.
The main description cannot continue after the tag section begins.</p>
<p>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 <samp class="codeph">@param</samp> and <samp class="codeph">@see</samp> tags, while
others cannot.</p>
<p>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:</p>
<pre class="codeblock"> /**
 * 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 {}</pre>
<p>For a complete list of the ASDoc tags, see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff6_verapache">ASDoc
tags</a>.</p>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffd_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">Using the @private tag</h3>
<div>
<p>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.</p>
<p>To make ASDoc ignore a public or protected element, insert an
ASDoc comment that contains the <samp class="codeph">@private</samp> tag anywhere
in the comment. The ASDoc comment can contain additional text along
with the <samp class="codeph">@private</samp> tag, which is also excluded from
the output.</p>
<p>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 <samp class="codeph">@private</samp> tag
before the class definition. The ASDoc comment can contain additional
text along with the <samp class="codeph">@private</samp> tag, which is also
excluded from the output, as the following example shows:</p>
<pre class="codeblock"> /**
 * This class is omitted from the output.
*
* <strong>@private</strong>
 */
 public class MyClass {
 }</pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff8_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff8_verapache"><!-- --></a>
<h3 class="topictitle3">Excluding an inherited element</h3>
<div>
<p>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 <samp class="codeph">[Exclude]</samp> metadata tag to cause ASDoc to omit
the inherited element from the list of inherited elements.</p>
<p>The <samp class="codeph">[Exclude]</samp> metadata tag has the following
syntax:</p>
<pre class="codeblock"> [Exclude(name="elementName", kind="property|method|event|style|effect")] </pre>
<p>For example, to exclude documentation on the <samp class="codeph">click</samp> event
in the MyButton subclass of the Button class, insert the following <samp class="codeph">[Exclude]</samp> metadata
tag in the MyButton.as file:</p>
<pre class="codeblock"> [Exclude(name="click", kind="event")] </pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffb_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffb_verapache"><!-- --></a>
<h3 class="topictitle3">Using HTML tags </h3>
<div>
<p>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 <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-8000_verapache">Summary
of commonly used HTML elements</a>. </p>
<p>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 <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;code&gt;</samp> tags,
by inserting the closing <samp class="codeph">&lt;/p&gt;</samp> or <samp class="codeph">&lt;/code&gt;</samp> tag. </p>
<p>The following example comment contains HTML tags to format the
output:</p>
<pre class="codeblock"> /**
 * This is the typical format of a simple multiline comment
 * for the myMethod() method.
 *
 * &lt;p&gt;This is the second paragraph of the main description
 * of the &lt;code&gt;myMethod&lt;/code&gt; method.
 * Notice that you do not use the paragraph tag in the
 * first paragraph of the description.&lt;/p&gt;
 *
 * @param param1 Describe param1 here.
 * @param param2 Describe param2 here.
 *
 * @return A value of &lt;code&gt;true&lt;/code&gt; means this;
 * &lt;code&gt;false&lt;/code&gt; means that.
 *
 * @see someOtherMethod
 */
 public function myMethod(param1:String, param2:Number):Boolean {}</pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff6_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff6_verapache"><!-- --></a>
<h3 class="topictitle3">Using special characters</h3>
<div>
<p>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.</p>
<p>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
(&lt;) or greater-than (&gt;) symbols in a comment, use <samp class="codeph">&amp;lt;</samp> and <samp class="codeph">&amp;gt;</samp>.
To use the at-sign (@) in a comment, use <samp class="codeph">&amp;#64;</samp>.
Otherwise, these characters are interpreted as literal HTML characters
in the output. </p>
<p>For a list of common HTML tags and their entity equivalents,
see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-8000_verapache">Summary
of commonly used HTML elements</a>.</p>
<p>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 (~~). </p>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff4_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff4_verapache"><!-- --></a>
<h3 class="topictitle3">Hiding text in ASDoc comments</h3>
<div>
<p>The ASDoc style sheet contains a class called <samp class="codeph">hide</samp>,
which you use to hide text in an ASDoc comment by setting the class
attribute to <samp class="codeph">hide</samp>. 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 <samp class="codeph">hide</samp> class:</p>
<pre class="codeblock"> /**
 * Dispatched when the user presses the Button control.
 * If the &lt;code&gt;autoRepeat&lt;/code&gt; property is &lt;code&gt;true&lt;/code&gt;,
 * this event is dispatched repeatedly as long as the button stays down.
 *
 * &lt;span class="hide"&gt;This text is hidden.&lt;/span&gt;
 * @eventType mx.events.FlexEvent.BUTTON_DOWN
 */</pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffc_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">Rules for parsing ASDoc comments</h3>
<div>
<p>The following rules summarize how ASDoc processes an ActionScript
file:</p>
<ul>
<li>
<p>If an ASDoc comment precedes an ActionScript element,
ASDoc copies the comment and code element to the output file.</p>
</li>
<li>
<p>If an ActionScript element is not preceded by an ASDoc comment,
ASDoc copies the code element to the output file with an empty description.</p>
</li>
<li>
<p>If an ASDoc comment contains the <samp class="codeph">@private</samp> ASDoc
tag, the associated ActionScript element and the ASDoc comment are
ignored.</p>
</li>
<li>
<p>The comment text must precede any @ tags, otherwise the comment
text is interpreted as an argument to an @ tag. The only exception
is the <samp class="codeph">@private</samp> tag, which can appear anywhere
in an ASDoc comment.</p>
</li>
<li>
<p>HTML tags, such as <samp class="codeph">&lt;p&gt;&lt;/p&gt;</samp>,
and <samp class="codeph">&lt;ul&gt;&lt;/ul&gt;</samp>, in ASDoc comments are passed
through to the output. </p>
</li>
<li>
<p>HTML tags must use XML style conventions, which means there
must be a beginning and ending tag. For example, close an <samp class="codeph">&lt;li&gt;</samp> tag
with a <samp class="codeph">&lt;/li&gt;</samp> tag.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="nested1" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff7_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff7_verapache"><!-- --></a>
<h2 class="topictitle2">Documenting ActionScript elements</h2>
<div>
<p>You can add ASDoc comments to class, property, method,
and metadata elements to document ActionScript classes. For more
information on documenting MXML files, see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff2_verapache">Documenting
MXML files</a>.</p>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe9_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe9_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting classes</h3>
<div>
<p>The ASDoc tool automatically includes all public classes
in its output. Place the ASDoc comment for a class just before the <samp class="codeph">class</samp> declaration,
as the following example shows:</p>
<pre class="codeblock"> /**
 * 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 {
 }</pre>
<p>This comment appears at the top of the HTML page for the associated
class. </p>
<p>To configure ASDoc to omit the class from the output, insert
an <samp class="codeph">@private</samp> tag anywhere in the ASDoc comment,
as the following example shows:</p>
<pre class="codeblock"> /**
 * @private
 * The MyHiddenButton control is for internal use only.
 */
 public class MyHiddenButton extends UIComponent {
 }</pre>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffa_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffa_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting properties</h3>
<div>
<p>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. </p>
<div class="section" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffa_verapache__WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe8_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffa_verapache__WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fe8_verapache"><!-- --></a><h4 class="sectiontitle">Documenting
properties defined as variables</h4>
<p>Place the ASDoc comment
for a public or protected property that is defined as a variable
just before the <samp class="codeph">var</samp> declaration, as the following
example shows:</p>
<pre class="codeblock"> /**
 * The default label for MyButton.
 *
 * @default null
 */
 public var myButtonLabel:String;</pre>
<p>A best practice
for a property is to include the <samp class="codeph">@default</samp> tag to
specify the default value of the property. The <samp class="codeph">@default</samp> tag
has the following format:</p>
<pre class="codeblock"> <em>@default value</em> </pre>
<p>This
tag generates the following text in the output for the property:</p>
<pre class="codeblock"> The default value is <em>value</em>. </pre>
<p>For
properties that have a calculated default value, or a complex description, omit
the <samp class="codeph">@default</samp> tag and describe the default value
in text.</p>
<p>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:</p>
<pre class="codeblock"> /**
* The horizontal and vertical distances of point (x,y)
*/
 public var x, y;// Avoid this </pre>
<p>ASDoc generates the
following documentation from the preceding code:</p>
<pre class="codeblock"> public var x
  The horizontal and vertical distances of point (x,y)
 
 public var y
  The horizontal and vertical distances of point (x,y)</pre>
</div>
<div class="section" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffa_verapache__WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff9_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ffa_verapache__WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff9_verapache"><!-- --></a><h4 class="sectiontitle">Documenting
properties defined by setter and getter methods</h4>
<p>Properties
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.</p>
<p>If
you define a setter method and a getter method, insert a single
ASDoc comment before the getter, and mark the setter as <samp class="codeph">@private</samp>.
This is a recommended practice because usually the getter comes
first in the ActionScript file, as the following example shows:</p>
<pre class="codeblock"> /**
 * Indicates whether or not the text field is enabled.
 */
 public function get html():Boolean {};
 
 /**
 * @private
 */
 public function set html(value:Boolean):void {};</pre>
<p>The
following rules define how ASDoc handles properties defined by setter
and getter methods:</p>
<ul>
<li>
<p>If you precede a setter or getter
method with an ASDoc comment, the comment is included in the output.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>If you define a setter method and a getter method, insert
a single ASDoc comment before the getter, and mark the setter as <samp class="codeph">@private</samp>.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>If you define just a getter method, the property is marked
as read-only.</p>
</li>
<li>
<p>If you define just a setter method, the property is marked
as write only.</p>
</li>
<li>
<p>If you define both a public setter and public getter method
in a class, and you want to hide them by using the <samp class="codeph">@private</samp> tag,
they both must be marked <samp class="codeph">@private</samp>.</p>
</li>
<li>
<p>If you have only one public setter or getter method in a
class, and it is marked <samp class="codeph">@private</samp>, ASDoc applies
normal <samp class="codeph">@private</samp> rules and omits it from the output.</p>
</li>
<li>
<p>A subclass always inherits its visible superclass setter
and getter method definitions.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fea_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7fea_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting methods</h3>
<div>
<p>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 <samp class="codeph">function</samp> declaration, as
the following example shows:</p>
<pre class="codeblock"> /**
 * This is the typical format of a simple multiline documentation comment
 * for the myMethod() method.
 *
 * &lt;p&gt;This is the second paragraph of the main description
 * of the &lt;code&gt;myMethod&lt;/code&gt; method.
 * Notice that you do not use the paragraph tag in the
 * first paragraph of the description.&lt;/p&gt;
 *
 * @param param1 Describe param1 here.
 * @param param2 Describe param2 here.
 *
 * @return A value of &lt;code&gt;true&lt;/code&gt; means this;
 * &lt;code&gt;false&lt;/code&gt; means that.
 *
 * @see someOtherMethod
 */
 public function myMethod(param1:String, param2:Number):Boolean {}</pre>
<p>If the method takes an argument, include an <samp class="codeph">@param</samp> tag
for each argument to describe the argument. The order of the <samp class="codeph">@param</samp> tags
in the ASDoc comment must match the order of the arguments to the
method. The <samp class="codeph">@param</samp> tag has the following syntax:</p>
<pre class="codeblock"> @param <em>paramName</em>  <em>description</em> </pre>
<p>Where <em>paramName</em> is the name of the argument and <em>description</em> is
a description of the argument. </p>
<p>If the method returns a value, use the <samp class="codeph">@return</samp> tag
to describe the return value. The <samp class="codeph">@return</samp> tag has
the following syntax:</p>
<pre class="codeblock"> @return <em>description</em> </pre>
<p>Where <em>description</em> describes the return value. </p>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff3_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff3_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting metadata</h3>
<div>
<p>Flex uses metadata tags to define certain characteristics
of a class. ASDoc recognizes some of these metadata tags to generate
output. The metadata tags recognized by ASDoc include the following:</p>
<ul>
<li>
<p>
<samp class="codeph">[Bindable]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[DefaultProperty]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[Deprecated]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[Effect]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[Event]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[Exclude]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[SkinPart]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[SkinState]</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">[Style]</samp>
</p>
</li>
</ul>
<p>Some metadata tags take an ASDoc comment, such as <samp class="codeph">[Effect]</samp> and <samp class="codeph">[Event]</samp>.
Other metadata tags, such as <samp class="codeph">[Bindable]</samp> and <samp class="codeph">[DefaultProperty]</samp> do
not. If you put an ASDoc comment before a metadata tag that does
not accept a comment, the comment is passed through to the next
element in the class. If the next element in the class already has
an ASDoc comment, the comment on the metadata tag is ignored. </p>
<p>For more information on the <samp class="codeph">[Exclude]</samp> tag, see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff8_verapache">Excluding
an inherited element</a>.</p>
<p>For more information on using these metadata tags in an application,
see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache">Metadata
tags in custom components</a>.</p>
</div>
<div class="nested3" id="WS03d33b8076db57b9-30add85122092189f9-8000_verapache"><a name="WS03d33b8076db57b9-30add85122092189f9-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Documenting bindable properties</h4>
<div>
<p>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 <samp class="codeph">[Bindable]</samp> metadata tag before the
property definition, or before the class definition to make all
properties defined within the class bindable. The <samp class="codeph">[Bindable]</samp> metadata
tag does not take an ASDoc comment.</p>
<p>When a property is defined as bindable, ASDoc automatically adds
the following line to the output for the property:</p>
<pre class="codeblock"> This property can be used as the source for data binding.</pre>
<p>For more information on the <samp class="codeph">[Bindable]</samp> metadata
tag, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache">Metadata
tags in custom components</a>.</p>
</div>
</div>
<div class="nested3" id="WS03d33b8076db57b9-30add85122092189f9-7fff_verapache"><a name="WS03d33b8076db57b9-30add85122092189f9-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Documenting default properties</h4>
<div>
<p>
The <samp class="codeph">[DefaultProperty]</samp> metadata
tag defines the name of the default property of the component when
you use the component in an MXML file. The <samp class="codeph">[DefaultProperty]</samp> metadata
tag does not take an ASDoc comment.</p>
<p>When ASDoc encounters the <samp class="codeph">[DefaultProperty]</samp> metadata
tag, it automatically adds a line to the class description that
specifies the default property. For example, see the List control
in <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe<sup>®</sup>
Flash<sup>®</sup> Platform</a>
</em>.</p>
<p>For more information on the <samp class="codeph">[DefaultProperty]</samp> metadata
tag, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache">Metadata
tags in custom components</a>.</p>
</div>
</div>
<div class="nested3" id="WS03d33b8076db57b9-30add85122092189f9-7ffe_verapache"><a name="WS03d33b8076db57b9-30add85122092189f9-7ffe_verapache"><!-- --></a>
<h4 class="topictitle4">Documenting deprecated properties</h4>
<div>
<p>A class or class elements marked as deprecated is one which
is considered obsolete, and whose use is discouraged. While the
class or class element still works, its use can generate compiler
warnings. </p>
<p>Insert the <samp class="codeph">[Deprecated]</samp> metadata tag before
a property, method, or class definition to mark that element as
deprecated. The <samp class="codeph">[Deprecated]</samp> metadata tag does
not take an ASDoc comment. </p>
<div class="p">The following example uses the <samp class="codeph">[Deprecated]</samp> metadata
tag to mark the dataProvider property as obsolete: <pre class="codeblock">[Deprecated(replacement="MenuBarItem.data")]
public function set dataProvider(value:Object):void
{}</pre>
</div>
<p>When ASDoc encounters the <samp class="codeph">[Deprecated]</samp> metadata
tag, it adds a line to the output marking the item as deprecated,
and inserts a link to the replacement item. </p>
<p>The mxmlc command-line compiler supports the <samp class="codeph">show-deprecation-warnings</samp> compiler
option, which, when <samp class="codeph">true</samp>, configures the compiler
to issue deprecation warnings when your application uses deprecated
elements. The default value is <samp class="codeph">true</samp>.</p>
<p>For more information on the <samp class="codeph">[Deprecated]</samp> metadata
tag, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a6c_verapache">Deprecated metadata
tag</a>.</p>
</div>
</div>
<div class="nested3" id="WS03d33b8076db57b9-30add85122092189f9-7ffd_verapache"><a name="WS03d33b8076db57b9-30add85122092189f9-7ffd_verapache"><!-- --></a>
<h4 class="topictitle4">Documenting skin states and skin
parts</h4>
<div>
<p>You use metadata tags to add information about skin parts
and skin states to a class definition. Put the <samp class="codeph">[SkinPart]</samp>metadata
tag before a property definition in the source code file, and put
the <samp class="codeph">[SkinState]</samp> metadata tag at the top of the class
definition.</p>
<p>The <samp class="codeph">[SkinPart]</samp>metadata tag does not take an
ASDoc comment. It is used to identify that a property corresponds
to a skin part, as the following example shows:</p>
<pre class="codeblock">[SkinPart(required="false")]
/**
* A skin part that defines the label of the button.
*/
public var labelElement:TextGraphicElement;</pre>
<p>A property identified as a skin part appears in the ASDoc output
in the Skin Part section, not in the Properties section. The ASDoc
comment for the property appears in the Skin Part section.</p>
<p>The <samp class="codeph">[SkinState]</samp>metadata tag takes an ASDoc comment
describing the skin state, as the following example shows:</p>
<pre class="codeblock">/**
* Up State of the Button
*/
[SkinState("up")]</pre>
<p>The ASDoc comment for the skin state appears in the Skin States
section of the ASDoc output.</p>
</div>
</div>
<div class="nested3" id="WS03d33b8076db57b9-30add85122092189f9-7ffc_verapache"><a name="WS03d33b8076db57b9-30add85122092189f9-7ffc_verapache"><!-- --></a>
<h4 class="topictitle4">Documenting effects, events, and
styles</h4>
<div>
<p>You use metadata tags to add information about effects,
events, and styles in a class definition. The <samp class="codeph">[Effect]</samp>, <samp class="codeph">[Event]</samp>,
and <samp class="codeph">[Style]</samp> 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:</p>
<pre class="codeblock"> /**
 * Defines the name style.
 */
 [Style "name"]</pre>
<p>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:</p>
<pre class="codeblock"> /**
 * Dispatched when the user presses the Button control.
 * If the &lt;code&gt;autoRepeat&lt;/code&gt; property is &lt;code&gt;true&lt;/code&gt;,
 * 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")]</pre>
<p>In the ASDoc comment for the <samp class="codeph">mx.events.FlexEvent.BUTTON_DOWN</samp> constant,
you insert a table that defines the values of the <samp class="codeph">bubbles</samp>, <samp class="codeph">cancelable</samp>, <samp class="codeph">target</samp>,
and <samp class="codeph">currentTarget</samp> 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 <samp class="codeph">@eventType</samp> tag
so that ASDoc can find the comment, as the following example shows:</p>
<pre class="codeblock"> /**
 * The FlexEvent.BUTTON_DOWN constant defines the value of the
 * &lt;code&gt;type&lt;/code&gt; property of the event object
 * for a &lt;code&gt;buttonDown&lt;/code&gt; event.
 *
 * &lt;p&gt;The properties of the event object have the following values:&lt;/p&gt;
 * &lt;table class="innertable"&gt;
 * &lt;tr&gt;&lt;th&gt;Property&lt;/th&gt;&lt;th&gt;Value&lt;/th&gt;&lt;/tr&gt;
 * ...
 * &lt;/table&gt;
 *
 * @eventType buttonDown
 */
public static const BUTTON_DOWN:String = "buttonDown"</pre>
<p>The ASDoc tool does several things for this event:</p>
<ul>
<li>
<p>In the output for the mx.controls.Button class, ASDoc
creates a link to the event class specified by the <samp class="codeph">type</samp> argument
of the <samp class="codeph">[Event]</samp> metadata tag.</p>
</li>
<li>
<p>ASDoc copies the description of the <samp class="codeph">mx.events.FlexEvent.BUTTON_DOWN</samp> constant
to the description of the <samp class="codeph">buttonDown</samp> event in the
Button class. </p>
<p>For a complete example, see the mx.controls.Button
and mx.events.FlexEvent classes.</p>
<p>For more information on the <samp class="codeph">[Effect]</samp>, <samp class="codeph">[Event]</samp>,
and <samp class="codeph">[Style]</samp> metadata tags, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache">Metadata
tags in custom components</a>.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="nested1" id="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff2_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff2_verapache"><!-- --></a>
<h2 class="topictitle2">Documenting MXML files</h2>
<div>
<p>An MXML file contains several types of elements, including
MXML code, ActionScript code in <samp class="codeph">&lt;fx:Script&gt;</samp> blocks,
and metadata tags. The ASDoc tool supports all these element types
so that you can generate ASDoc content for MXML files just as you
can for ActionScript classes.</p>
<p>MXML files correspond to ActionScript classes where the superclass
corresponds to the first tag in the MXML file. For an application
file, that tag is the <samp class="codeph">&lt;s:Application&gt;</samp> tag
and therefore an MXML application file appears in the ASDoc output
as a subclass of the Application class.</p>
</div>
<div class="nested2" id="WS0877AF1A-6BA3-4590-980F-A80836DF97C7_verapache"><a name="WS0877AF1A-6BA3-4590-980F-A80836DF97C7_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting MXML elements</h3>
<div>
<div class="p">Use the following syntax to specify an ASDoc comment in
an MXML file for an element defined in MXML:<pre class="codeblock">&lt;!--- asdoc comment --&gt;</pre>
</div>
<div class="p">The comment must contain three dashes following the opening <samp class="codeph">&lt;!</samp> characters, and
end with two dashes before the closing <samp class="codeph">&gt;</samp> character,
as the following example shows:<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- asdoc\MyVBox.mxml --&gt;
&lt;!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
--&gt;
&lt;mx:VBox xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;!---
Comment for button
--&gt;
&lt;s:Button id="myButton" label="This button has a comment"/&gt;
&lt;/mx:VBox&gt;</pre>
</div>
<p>In this example, the first comment is a standard XML comment
ignored by ASDoc. The second comment precedes the root tag of the
component and uses the three dashes to identify it as an ASDoc comment.
An ASDoc comment on the root tag is equivalent to the ASDoc comment
before an ActionScript class definition. Therefore, the comment
appears at the top of the output ASDoc HTML file. </p>
<div class="p">A leading dash at the beginning of each comment line, and any
whitespace characters before the dash, are ignored, as the following
example shows: <pre class="codeblock">&lt;!---
- Comment for my class
- which is implemented as mxml
--&gt;</pre>
</div>
<div class="p">If you copy a comment from an ActionScript file that uses the
/**, *, and **/ characters, those characters are also ignored, as
the following example shows: <pre class="codeblock">&lt;!---
/**
* Comment for my class
* which is implemented as mxml
*/
--&gt;
&lt;!---
* Comment for my class
* which is implemented as mxml
--&gt;</pre>
</div>
<p>All MXML elements in the file correspond to public properties
of the component. The comment before the Button control defines
the ASDoc comment for the public property named myButton of type
mx.controls.Button. </p>
<p>You can use any ASDoc tags in these comments, including the <samp class="codeph">@see</samp>, <samp class="codeph">@copy</samp>, <samp class="codeph">@param</samp>, <samp class="codeph">@return</samp>,
and other ASDoc comments.</p>
<div class="p">The ASDoc command-line tool only processes elements of an MXML
file that contain an <samp class="codeph">id</samp> attribute. If the MXML
element has an <samp class="codeph">id</samp> attribute but no comment, the
element appears in the ASDoc output with a blank comment. An MXML
element with no <samp class="codeph">id</samp> attribute is ignored, even if
it is preceded by an ASDoc comment, as the following example shows:<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- asdoc\MyVBoxID.mxml --&gt;
&lt;!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
@see mx.container.VBox
--&gt;
&lt;mx:VBox xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;!---
Comment for first button appears in the output.
--&gt;
&lt;s:Button id="myButton" label="This button has a comment"/&gt;
&lt;s:Button id="myButton2"
label="Has id but no comment so appears in output"/&gt;
&lt;!---
Comment for button with no id is ignored by ASDoc.
--&gt;
&lt;s:Button label="This button has no id"/&gt;
&lt;/mx:VBox&gt;</pre>
</div>
<p>Comments before Definition, Library, and Private tags are ignored.
Also comments inside a private block are ignored.</p>
</div>
</div>
<div class="nested2" id="WSC2AB77F9-FB0F-4332-A834-1BA4BF1BF0C0_verapache"><a name="WSC2AB77F9-FB0F-4332-A834-1BA4BF1BF0C0_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting ActionScript in &lt;fx:Script&gt;
blocks</h3>
<div>
<div class="p">Insert ASDoc comments for ActionScript code in the <samp class="codeph">&lt;fx:Script&gt;</samp> block
by using the same syntax as you use in an ActionScript file. The
only requirement is that the ASDoc comments must be within a <samp class="codeph">CDATA</samp> block,
as the following example shows:<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- asdoc\MyVBoxComplex.mxml --&gt;
&lt;!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
--&gt;
&lt;mx:VBox xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;!---
Comment for language element - this comment will be ignored.
--&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.MouseEvent;
/**
* For a method in an &amp;lt;Script&amp;gt; block,
* same rules as in an AS file.
*
* @param eventObj The event object.
*/
public function handleClickEvent(eventObj:MouseEvent):void {
dispatchEvent(eventObj);
}
/**
* For a property in an &amp;lt;Script&amp;gt; block,
* same rules as in an AS file.
*/
public var myString:String = new String();
]]&gt;
&lt;/fx:Script&gt;
&lt;!---
Comment for first button appears in the output.
--&gt;
&lt;s:Button id="myButton" label="This button has a comment"
click="handleClickEvent(event);"/&gt;
&lt;s:Button id="myButton2"
label="Has id but no comment so appears in output"/&gt;
&lt;!---
Comment for button with no id is ignored by ASDoc.
--&gt;
&lt;s:Button label="This button has no id"/&gt;
&lt;/mx:VBox&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WSb0a29bf92525419c1ec2a7d4120ddbf824a-8000_verapache"><a name="WSb0a29bf92525419c1ec2a7d4120ddbf824a-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting MXML declarations</h3>
<div>
<div class="p">You can add ASDoc comments to <samp class="codeph">&lt;fx:Declaration&gt;</samp> blocks
in MXML, as the following example shows:<pre class="codeblock">&lt;fx:Declarations&gt;
&lt;!---
Specifies the skin for the first button on the ButtonBar.
@default spark.skins.default.ButtonBarFirstButtonSkin
--&gt;
&lt;fx:Component id="firstButton"&gt;
&lt;s:ButtonBarButton skinClass="spark.skins.default.ButtonBarFirstButtonSkin" /&gt;
&lt;/fx:Component&gt;
&lt;/fx:Declarations&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS1CCDAFDF-AE3F-42df-8E64-165BB86BDC00_verapache"><a name="WS1CCDAFDF-AE3F-42df-8E64-165BB86BDC00_verapache"><!-- --></a>
<h3 class="topictitle3">Documenting metadata tags</h3>
<div>
<div class="p">You can insert ASDoc comments for metadata tags in <samp class="codeph">&lt;fx:Metadata&gt;</samp> blocks in
an MXML file. For metadata tags, the ASDoc comments use the same
syntax as you us in an ActionScript file. The only requirement is
that the ASDoc comments must be within a <samp class="codeph">CDATA</samp> block,
as the following example shows:<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- asdoc\MyVBoxMetaData.mxml --&gt;
&lt;!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
--&gt;
&lt;mx:VBox xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;!---
Comment for language element - this comment will be ignored.
--&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.MouseEvent;
/**
* For a method in an &amp;lt;Script&amp;gt; block,
* same rules as in an AS file.
*
* @param eventObj The event object.
*/
public function handleClickEvent(eventObj:MouseEvent):void {
dispatchEvent(eventObj);
}
/**
* For a property in an &amp;lt;Script&amp;gt; block,
* same rules as in an AS file.
*/
public var myString:String = new String();
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Metadata&gt;
&lt;![CDATA[
/**
* Defines the default style of selected text.
*/
[Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]
/**
* The component dispatches the darken event
* when the darken property changes.
*
* @eventType flash.events.Event
*/
[Event(name="darken", type="flash.events.Event")]
/**
* Played when the component darkens.
*/
[Effect(name="darkenEffect", event="darken")]
]]&gt;
&lt;/fx:Metadata&gt;
&lt;!---
Comment for first button appears in the output.
--&gt;
&lt;s:Button id="myButton" label="This button has a comment"
click="handleClickEvent(event);"/&gt;
&lt;/mx:VBox&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff6_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff6_verapache"><!-- --></a>
<h2 class="topictitle2">ASDoc tags</h2>
<div>
<p>The following table lists the ASDoc tags:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e1505">
<p>ASDoc tag </p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e1511">
<p>Description</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e1517">
<p>Example</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock"><samp class="codeph">@copy reference</samp></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Copies an ASDoc comment from the referenced
location. The main description, <samp class="codeph">@param</samp>, and <samp class="codeph">@return</samp> content
is copied; other tags are not copied.</p>
<p>You typically use the <samp class="codeph">@copy</samp> tag
to copy information from a source class or interface not in the
inheritance list of the destination class. If the source class or
interface is in the inheritance list, use the <samp class="codeph">@inheritDoc</samp> tag
instead. </p>
<p>You can add content to the ASDoc comment before
the <samp class="codeph">@copy</samp> tag. </p>
<p>Specify the location by using
the same syntax as you do for the <samp class="codeph">@see</samp> tag. For
more information, see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff8_verapache">Using
the @see tag</a>. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<p>
<samp class="codeph">@copy #stop</samp>
</p>
<p>
<samp class="codeph">@copy flash.display.MovieClip#stop</samp>()</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock"><samp class="codeph">@default </samp><em>value</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Specifies the default value for a property,
style, or effect. The ASDoc tool automatically creates a sentence
in the following form when it encounters an <samp class="codeph">@default</samp> tag: </p>
<div class="p">
<pre class="codeblock">The default value is <em>value</em>. </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@default 0xCCCCCC</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@eventType <em>package.class.CONSTANT</em>@eventType <em>String</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Use the first form in a comment for an <samp class="codeph">[Event]</samp> metadata
tag. It specifies the constant that defines the value of the <samp class="codeph">Event.type</samp> property
of the event object associated with the event. The ASDoc tool copies
the description of the event constant to the referencing class. </p>
<p>Use
the second form in the comment for the constant definition. It specifies
the name of the event associated with the constant. If the tag is omitted,
ASDoc cannot copy the constant's comment to a referencing class. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<p>See <a href="flx_asdoc_asd.html#WS03d33b8076db57b9-30add85122092189f9-7ffc_verapache">Documenting
effects, events, and styles</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@example <em>exampleText</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Defines a code example in an ASDoc comment.
By preceding the code example with this tag, ASDoc applies style
properties, generates a heading, and puts the code example in the
correct location. </p>
<p>Enclose the code in <samp class="codeph">&lt;listing version="3.0"&gt;&lt;/listing&gt;</samp> tags. </p>
<p>Whitespace
formatting is preserved and the code is displayed in a gray, horizontally
scrolling box. </p>
<p>If the code inside the <samp class="codeph">&lt;listing&gt;</samp> tags
uses literal “&lt;“, “&gt;”, or”&amp;” characters, convert them
to the HTML character-code equivalent.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<p>
<samp class="codeph">@example The following code sets the volume level for your sound:</samp>
</p>
<p>
<samp class="codeph">&lt;listing version="3.0"&gt; </samp>
</p>
<p>
<samp class="codeph">var mySound:Sound = new Sound(); mySound.setVolume(VOL_HIGH); </samp>
</p>
<p>
<samp class="codeph">&lt;/listing&gt;</samp>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@exampleText <em>string</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Use this tag in an ASDoc comment in an external
example file that is referenced by the <samp class="codeph">@includeExample</samp> tag.
The ASDoc comment must precede the first line of the example, or follow
the last line of the example. </p>
<p>External example files support
one comment before and one comment after example code. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<p>
<samp class="codeph">/** </samp>
</p>
<p>
<samp class="codeph">* This text does not appear </samp>
</p>
<p>
<samp class="codeph">* in the output. </samp>
</p>
<p>
<samp class="codeph">* @exampleText But this does. </samp>
</p>
<p>
<samp class="codeph">*/</samp>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<p>
<samp class="codeph">@includeExample <em>textFile</em>
</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Imports an example text file into the ASDoc output.
ASDoc searches for the example file based on the package name of
the class and the directory specified by the <samp class="codeph">-examples-path</samp> option
to the ASDoc tool. </p>
<p>For example, you use the <samp class="codeph">examples-path</samp> option
to set the directory to c:\examples. To add an example for the mx.controls.Button class,
place it in the mx\controls\directory under c:\examples, meaning
the c:\examples\mx\controls directory. </p>
<div class="p">You can further qualify
the location of the file by specifying a path to the <samp class="codeph">@includeExample</samp> tag.
For example, you specify the <samp class="codeph">@includeExample</samp> as
shown below:<pre class="codeblock">@includeExample buttonExample/ButtonExample.mxml</pre>
</div>
<p/>
<p>ASDoc
looks for an example in the directory c:\examples\mx\controls\buttonExample.</p>
<p>If
you insert this tag in the comment for a class, the example appears
at the end of the output HTML file. If you insert it in the ASDoc
comment for a class element, the example appears in the detailed
description of the element. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<p>
<samp class="codeph">@includeExample ButtonExample.mxml</samp>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@inheritDoc</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Copies the comment from the superclass into the
subclass, or from an interface implemented by the subclass. Use
this tag in the comment of an overridden method or property. You
cannot use this tag with comments on metadata tags.</p>
<p>The main
ASDoc comment, <samp class="codeph">@param</samp>, and <samp class="codeph">@return</samp> content
are copied; other tags are not. You can add content to the comment before
the <samp class="codeph">@inheritDoc</samp> tag.</p>
<p>When you include this
tag, ASDoc uses the following search order: </p>
<p>1. Interfaces
implemented by the current class, in alphabetical order of the package
and class name, and all their base-interfaces.</p>
<p>2. Immediate
superclass of current class.</p>
<p>3. Interfaces of immediate superclass
and all their base-interfaces. </p>
<p>4. Repeat steps 2 and 3 until
the Object class is reached.</p>
<p>You can also use the <samp class="codeph">@copy</samp> tag,
but the <samp class="codeph">@copy</samp> tag is for copying information from
a source class or interface that is not in the inheritance chain
of the subclass. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@inheritDoc</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@internal <em>text</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Hides the text attached to the tag in the
generated output. The hidden text can be used for internal comments. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@internal Please do not publicize the undocumented use of the third parameter in this method.</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@param <em>paramName</em> <em>description</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Adds a descriptive comment to a method parameter.
The <samp class="codeph">
<em>paramName</em>
</samp> argument must match a parameter
definition in the method signature. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@param fileName The name of the file to load.</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@private</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Exclude the element from the generated output. </p>
<p>To
omit an entire class, put the <samp class="codeph">@private</samp> tag in the
ASDoc comment for the class; to omit a single class element, put
the <samp class="codeph">@private</samp> tag in the ASDoc comment for the element. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@private</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@return <em>description</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Adds a Returns section to a method description
with the specified text. ASDoc automatically determines the data
type of the return value. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@return The translated message.</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@see <em>reference</em> <em>[displayText]</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Adds a See Also heading with a link to a
class element. For more information, see <a href="flx_asdoc_asd.html#WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff8_verapache">Using
the @see tag</a>. </p>
<p>Do not include HTML formatting characters
in the arguments to the <samp class="codeph">@see</samp> tag.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@see flash.display.MovieClip</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<p>
<samp class="codeph">@since <em>text</em>
</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Adds a Since section to a class or element. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<p>
<samp class="codeph">@since January 12, 2009</samp>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1505 ">
<div class="p">
<pre class="codeblock">@throws <em>package.class.className</em>  <em>description</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1511 ">
<p>Documents an error that a method can throw. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e1517 ">
<div class="p">
<pre class="codeblock">@throws SecurityError Local untrusted SWFs may not communicate with the Internet.</pre>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff8_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ff8_verapache"><!-- --></a>
<h3 class="topictitle3">Using the @see tag</h3>
<div>
<p>The <samp class="codeph">@see</samp> tag lets you create cross-references
to elements within a class; to elements in other classes in the
same package; and to other packages. You can also cross-reference
URLs outside ASDoc. The <samp class="codeph">@see</samp> tag has the following
syntax:</p>
<pre class="codeblock"> @see reference [displayText]</pre>
<p>where <em>reference</em> specifies the destination of the link,
and <em>displayText</em> optionally specifies the link text. The location
of the destination of the <samp class="codeph">@see</samp> tag is determined
by the prefix to the <em>reference</em> attribute:</p>
<ul>
<li>
<p>
<samp class="codeph">#</samp> ASDoc looks in the same class for
the link destination.</p>
</li>
<li>
<p>
<em>ClassName</em> ASDoc looks in a class in the same package
for the link destination.</p>
</li>
<li>
<p>
<em>PackageName</em> ASDoc looks in a different package for
the link destination.</p>
</li>
<li>
<p>
<samp class="codeph">effect</samp> ASDoc looks for an effect property
for the link destination.</p>
</li>
<li>
<p>
<samp class="codeph">event</samp> ASDoc looks for an event property
for the link destination.</p>
</li>
<li>
<p>
<samp class="codeph">style</samp> ASDoc looks for a style property for
the link destination.</p>
</li>
</ul>
<div class="note"><span class="notetitle">Note:</span> You cannot insert HTML tags in reference. However,
you can add an HTML link without using the <samp class="codeph">@see</samp> tag
by inserting the HTML code in the ASDoc comment.</div>
<div class="p">The following table shows several examples of the <samp class="codeph">@see</samp> tag:
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e2284">
<p>Example</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e2290">
<p>Result</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see "Just a label" </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Text string</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see http://www.cnn.com </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>External web site</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see package-detail.html </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Local HTML file</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see AccessibilityProperties </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Class in same package</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see flash.display.TextField </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Class in different package</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see flash.ui.ContextMenu#customItems</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Property in class in different package</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see mx.containers.DividedBox#style:dividerAffordance</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Style property in class in different package</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see #updateProperties() </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Method in same class as <samp class="codeph">@see</samp> tag</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see flash.ui.ContextMenu#clone() </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Method in class in different package</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<div class="p">
<pre class="codeblock">@see flash.util.#clearInterval() </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Package method in flash.util</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<p>
<samp class="codeph">@see mx.controls.Buttont#style:horizontalGap</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Style property in Button class.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<p>
<samp class="codeph">@see mx.containers.Accordion#event:change</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Event in Accordion class.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2284 ">
<p>
<samp class="codeph">@see mx.core.UIComponent#effect:creationCompleteEffect</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2290 ">
<p>Effect property in UIComponent class.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-8000_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Summary of commonly used HTML elements</h3>
<div>
<p>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 <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;code&gt;</samp> tags,
by inserting the closing <samp class="codeph">&lt;/p&gt;</samp> or <samp class="codeph">&lt;/code&gt;</samp> tag. </p>
<p>The following table lists commonly used HTML tags and character
codes within ASDoc comments:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e2587">
<p>Tag or Code</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e2593">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;p&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Starts a new paragraph. You must close <samp class="codeph">&lt;p&gt;</samp> tags.</p>
<p>Do
not use <samp class="codeph">&lt;p&gt;</samp> for the first paragraph of a
doc comment (the paragraph after the opening <samp class="codeph">/**</samp>)
or the first paragraph associated with a tag. Use the <samp class="codeph">&lt;p&gt;</samp> tag
for subsequent; for example:</p>
<p>
<samp class="codeph">/** </samp>
</p>
<p>
<samp class="codeph">* The first sentence of a main description. </samp>
</p>
<p>
<samp class="codeph">* </samp>
</p>
<p>
<samp class="codeph">* &lt;p&gt;This line starts a new paragraph.&lt;/p&gt; </samp>
</p>
<p>
<samp class="codeph">* </samp>
</p>
<p>
<samp class="codeph">* &lt;p&gt;This line starts a third paragraph.&lt;/p&gt;</samp>
</p>
<p>
<samp class="codeph">*/</samp>
</p>
<p>ASDoc
ignores white space in comments. To add white space for readability
in the AS file, do not use the <samp class="codeph">&lt;p&gt;</samp> tag but
add blank lines.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">class="hide"</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Hides text. Use this tag if you want to
add documentation to the source file but do not want it to appear
in the output.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;listing&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Indicates a program listing (sample code). </p>
<p>Use
this tag to enclose code snippets that you format as separate paragraphs,
in monospace font, and in a gray background to distinguish the code
from surrounding text. Close all <samp class="codeph">&lt;listing&gt;</samp> tags. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;pre&gt; </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Formats text in monospace font, such as
a description of an algorithm or a formula. Do not use <samp class="codeph">&lt;br/&gt;</samp> tags
at end of line.</p>
<p>Use <samp class="codeph">&lt;listing&gt;</samp> tag for
code snippets. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;br/&gt; </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Adds a line break. You must close this tag.</p>
<p>Comments
for most tags are automatically formatted; you do not generally
have to add line breaks. To create additional white space, add a
new paragraph instead.</p>
<p>This tag might not be supported in
the future, so use it only if necessary. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;ul&gt;, &lt;li&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Creates a list. You must close these tags.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;table&gt;&lt;th&gt;&lt;tr&gt;&lt;td&gt; </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Creates a table. For basic tables that conform
to ASDoc style, set the class attribute to <samp class="codeph">innertable</samp>.
Avoid setting any special attributes. Avoid nesting structural items,
such as lists, within tables.</p>
<p>ASDoc uses a standard CSS stylesheet
that has definitions for the <samp class="codeph">&lt;table&gt;</samp>, <samp class="codeph">&lt;th&gt;</samp>, <samp class="codeph">&lt;tr&gt;</samp> and <samp class="codeph">&lt;td&gt;</samp> tags.
You must close these tags. </p>
<p>Use <samp class="codeph">&lt;th&gt;</samp> for
header cells instead of <samp class="codeph">&lt;td&gt;</samp>, so the headers
get formatted correctly.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;img&gt; </pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Inserts an image. To create the correct
amount of space around an image, enclose the image reference in <samp class="codeph">&lt;p&gt;&lt;/p&gt;</samp> tags.
Captions are optional; if you use a caption, make it boldface. You
must close the <samp class="codeph">&lt;img&gt;</samp> tag by ending it with <samp class="codeph">/&gt;</samp>,
as the following example shows:</p>
<div class="p">
<pre class="codeblock">&lt;img src = "../../images/matrix.jpg" /&gt;</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;code&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Applies monospace formatting. You must close
this tag.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;strong&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Applies bold text formatting. You must close
this tag.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&lt;em&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Applies italic formatting. You must close
this tag.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;lt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Less-than operator (&lt;) . Ensure that
you include the final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Greater-than operator (&gt;). Ensure that
you include the final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#38;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Ampersand (&amp;). Do not use <samp class="codeph">&amp;amp;</samp>.
Ensure that you include the final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<p>
<samp class="codeph">&amp;#42;</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Do not use a literal “*” character in the
body of a comment; instead, insert the HTML character code &amp;#42;.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#x2014;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Em dash. Ensure that you include the final
semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#x99;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Trademark symbol (™)
that is not registered. This character is superscript by default,
so do not enclose it in <samp class="codeph">&lt;sup&gt;</samp> tags. Ensure
that you include the final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#xA0;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Nonbreaking space. Ensure that you include
the final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#xAE;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Registered trademark symbol (<sup>®</sup>).
Enclose this character in <samp class="codeph">&lt;sup&gt;</samp> tags to make
it superscript. Ensure that you include the final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#xB0;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Degree symbol. Ensure that you include the
final semicolon (;).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2587 ">
<div class="p">
<pre class="codeblock">&amp;#64;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e2593 ">
<p>Do not use an @ sign in an ASDoc comment;
instead, insert the HTML character code: &amp;#64;.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested1" id="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ffa_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ffa_verapache"><!-- --></a>
<h2 class="topictitle2">Using the ASDoc tool </h2>
<div>
<p>The ASDoc tool, <samp class="codeph">asdoc</samp>, is in the flex\bin
directory of a Flex installation. To run the ASDoc tool, make sure
that you either first change to the bin directory, or you add the
bin directory to your system path. </p>
<div class="p">To see a list of the command-line options available to the ASDoc
tool, use the <samp class="codeph">‑help list</samp> option, as the following
example shows:<pre class="codeblock">asdoc -help list</pre>
</div>
<div class="p">By default, the ASDoc tool compiles its input files against the
library SWC files in the flex\frameworks\libs directory in your
Flex installation. If you must add additional SWC files to compile
your code, you can add them by using the <samp class="codeph">library-path</samp> option
to specify the directory containing the SWC files: <pre class="codeblock">asdoc ... -library-path+=C:\myLibs</pre>
</div>
<p>You can also use a Flex Ant task to run the ASDoc tool. For more
information, see <a href="flx_anttasks_an.html#WSda78ed3a750d6b8f4ce729f5121efe6ca1b-8000_verapache">Using
the asdoc task</a>.</p>
</div>
<div class="nested2" id="WS9A06747A-712D-4350-B0F6-BD5EBBABAC5F_verapache"><a name="WS9A06747A-712D-4350-B0F6-BD5EBBABAC5F_verapache"><!-- --></a>
<h3 class="topictitle3">Defining the input files to the
ASDoc tool</h3>
<div>
<p>Use the following options to specify the list of classes
processed by the <samp class="codeph">asdoc</samp> command: <samp class="codeph">doc-sources</samp>, <samp class="codeph">doc-classes</samp>,
and <samp class="codeph">doc-namespaces</samp>. The <samp class="codeph">doc-classes</samp> and <samp class="codeph">doc-namespaces</samp> options
require you to specify the <samp class="codeph">source-path</samp> option to
specify the root directory of your files.</p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> The examples below assume that you installed Flex in the
c:\flex directory on your machine. All the Flex source code is then
available in the C:\flex\frameworks\projects directory. </div>
</div>
<p>The most basic example is to specify the path to a single class
by using the <samp class="codeph">doc-sources</samp> option, as the following
example shows:</p>
<div class="p">
<pre class="codeblock">asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls\Button.as
-output framework-asdoc </pre>
This example generates
ASDoc content for the Flex Button control shipped with Flex, and
writes the output to the flex\bin\framework-asdoc directory. </div>
<p>You can specify multiple input class files, separated by spaces,
as the following example shows:</p>
<div class="p">
<pre class="codeblock">asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls\Button.as
C:\flex\frameworks\projects\framework\src\mx\controls\ButtonBar.as
-output framework-asdoc </pre>
</div>
<p>The two previous examples use the <samp class="codeph">output</samp> option
to the directory that contains the ASDoc output. You can specify
an absolute or relative path. In the previous example, the output
directory is named framework-output relative to the current working
directory. To view the output of your ASDoc build, open the index.html
file in the output directory.</p>
<p>The <samp class="codeph">doc-sources</samp> option takes a directory as
an argument, as well as a file list. If you specify a directory,
the ASDoc tool generates output for all files in the specified directory
and any subdirectories. Use this option to build ASDoc output for
all the files in the C:\flex\frameworks\projects\framework\src\mx\controls directory,
as the following example shows:</p>
<div class="p">
<pre class="codeblock">asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls
-output framework-asdoc </pre>
</div>
<p>You can specify multiple directories, separated by spaces. </p>
<p>Use the <samp class="codeph">doc-classes</samp> option to specify the package
and class name of a file to process. Use the <samp class="codeph">doc-classes</samp> option
with the <samp class="codeph">source-path</samp> option, as the following example
shows:</p>
<pre class="codeblock"> asdoc -source-path C:\flex\frameworks\projects\framework\src
-doc-classes mx.controls.Button mx.controls.ButtonBar
-output framework-asdoc </pre>
<p>The <samp class="codeph">source-path</samp> option adds directories to the
source path. The ASDoc tool searches directories in the source path
for the files to process. The value to the <samp class="codeph">doc-classes</samp> option
is a space delimited list of input files that use dot notation to
specify the package name of each class.</p>
<p>You can combine the <samp class="codeph">doc-sources</samp> and <samp class="codeph">doc-classes</samp> options
to specify the input to the ASDoc tool, as the following example
shows:</p>
<div class="p">
<pre class="codeblock">asdoc -source-path C:\flex\frameworks\projects\framework\src
-doc-classes mx.controls.Button mx.controls.ButtonBar
-doc-sources C:\flex\frameworks\projects\framework\src\mx\validators
-output framework-asdoc</pre>
</div>
<p>In this example, you compile all the validator classes as well
as the Button and ButtonBar components. </p>
</div>
</div>
<div class="nested2" id="WS464250F8-2CF5-4be4-8049-2C9FD9884998_verapache"><a name="WS464250F8-2CF5-4be4-8049-2C9FD9884998_verapache"><!-- --></a>
<h3 class="topictitle3">Compiling dependent files</h3>
<div>
<p>When performing a build, the ASDoc tool compiles the input
files and also attempts to compile any dependent files referenced
by the input files. For example, you specify class A as an input
by using the <samp class="codeph">doc-classes</samp> option. If class A imports
class B, both class A and class B are compiled and included in the ASDoc
output.</p>
<div class="p">The following example specifies only the mx.controls.Button class
as input:<pre class="codeblock">asdoc -source-path C:\flex\frameworks\projects\framework\src
-doc-classes mx.controls.Button
-output framework-asdoc</pre>
</div>
<p>The output of the build includes the mx.controls.Button class,
plus any class referenced by the Button class, and any classes referenced
by classes referenced by Button. The compiler uses the <samp class="codeph">source-path</samp> option
to locate these dependent classes.</p>
<p>If you set the <samp class="codeph">exclude-dependencies</samp> option to <samp class="codeph">true</samp>,
dependent classes found when compiling the input classes are not
documented. The default value is <samp class="codeph">false</samp>, which means
any classes that would normally be compiled along with the specified
classes are documented. </p>
<div class="p">The following example generates ASDoc content only for the Button
class: <pre class="codeblock">asdoc
-source-path C:\flex\frameworks\projects\framework\src
-doc-classes mx.controls.Button
-output framework-asdoc
<strong>-exclude-dependencies=true</strong></pre>
</div>
<div class="p">Setting the <samp class="codeph">exclude-dependencies</samp> option to <samp class="codeph">true</samp> improves
the performance of the ASDoc tool because you do not have to build
output for all dependent classes.<div class="note"><span class="notetitle">Note:</span> You cannot use <samp class="codeph">exclude-dependencies</samp> with
input class specified by the <samp class="codeph">doc-sources</samp> option.</div>
</div>
</div>
</div>
<div class="nested2" id="WS8086c3fe57005963-101598f11225baf50d4-8000_verapache"><a name="WS8086c3fe57005963-101598f11225baf50d4-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Adding package descriptions</h3>
<div>
<p>To add package descriptions to the output, you can use
the <samp class="codeph">package</samp> or <samp class="codeph">package-description-file</samp> options
of ASDoc. </p>
<div class="p">The <samp class="codeph">package</samp> option lets you specify the descriptions
on the ASDoc command line. You can specify more than one <samp class="codeph">package</samp> option.
The following example adds two package descriptions to the output: <pre class="codeblock">asdoc -doc-sources my_dir -output myDoc
-package com.my.business "Contains business classes and interfaces"
-package com.my.commands "Contains command base classes and interfaces"</pre>
</div>
<div class="p">If you have many packages, you can use the <samp class="codeph">package-description-file</samp> option
to specify an XML file that contains the descriptions, as the following example
shows: <pre class="codeblock">asdoc -source-path C:\\flex\sdk\frameworks\projects\framework\src
-doc-classes mx.controls.Button mx.controls.ButtonBar
-package-description-file myPackages.xml -output myDoc</pre>
</div>
<div class="p">In this example, the package descriptions are located in the
myPackages.xml file. The file specified by the <samp class="codeph">package-description-file</samp> option
has the following format: <pre class="codeblock">&lt;overviews&gt;
&lt;packages&gt;
&lt;package name="package.name1"&gt;
&lt;shortDescription&gt;
&lt;![CDATA[
Short description appears on the All Packages page.
]]&gt;
&lt;/shortDescription&gt;
&lt;description&gt;
&lt;![CDATA[
Long description appears on the package page.
]]&gt;
&lt;/description&gt;
&lt;/package&gt;
&lt;/packages&gt;
&lt;/overviews&gt;</pre>
</div>
<div class="p">For example: <pre class="codeblock">&lt;overviews&gt;
&lt;packages&gt;
&lt;package name="mx.core"&gt;
&lt;shortDescription&gt;
&lt;![CDATA[
The <strong>&amp;lt;b&amp;gt;mx.core package&amp;lt;/b&amp;gt;</strong> contains the
base classes and interfaces.
]]&gt;
&lt;/shortDescription&gt;
&lt;description&gt;
&lt;![CDATA[
The mx.core package contains the
base classes and interfaces,
such as UIComponent, used by Flex.
]]&gt;
&lt;/description&gt;
&lt;/package&gt;
&lt;package name="mx.controls"&gt;
&lt;shortDescription&gt;
&lt;![CDATA[
The mx.controls package contains
the Flex user-interface controls.
]]&gt;
&lt;/shortDescription&gt;
&lt;description&gt;
&lt;![CDATA[
The mx.controls package contains
the Flex user-interface controls.
]]&gt;
&lt;/description&gt;
&lt;/package&gt;
&lt;/packages&gt;
&lt;/overviews&gt;</pre>
</div>
<p>Notice that the HTML tag for bold text is entered by using the
HTML character code for the “&lt;“ and “&gt;” characters. </p>
</div>
</div>
<div class="nested2" id="WS1010D8F6-60A9-4438-9DB7-D1C0FC1E7F3C_verapache"><a name="WS1010D8F6-60A9-4438-9DB7-D1C0FC1E7F3C_verapache"><!-- --></a>
<h3 class="topictitle3">Using a manifest file as input</h3>
<div>
<p>If your source code is packaged for distribution as a SWC
file, you can use a manifest file to define the content of the SWC
file. You can use a manifest file as input to the ASDoc tool to
specify the input file list as the following example shows:</p>
<div class="p">
<pre class="codeblock">asdoc
-source-path C:\a\flex\flex\sdk\frameworks\projects\framework\src
-doc-classes FrameworkClasses
-namespace http://www.adobe.com/2006/mxml C:\flex\sdk\frameworks\projects\framework\manifest.xml
-doc-namespaces http://www.adobe.com/2006/mxml
-output framework-asdoc </pre>
</div>
<p>The preceding command line generates ASDoc content for all classes
in the Flex framework.swc file. Notice that your specify the FrameworkClasses
class file as input using the <samp class="codeph">doc-classes</samp> option,
and the manifest file by using the <samp class="codeph">doc-namespace</samp> option.
Most Flex SWC files are represented by a class file and a manifest
file. Therefore, to build ASDoc for the SWC file, you specify both
as input. </p>
<p>For more information on manifest files, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7aa8_verapache">About
manifest files</a>.</p>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff1_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7ff1_verapache"><!-- --></a>
<h3 class="topictitle3">Excluding classes</h3>
<div>
<p>All the classes specified by the <samp class="codeph">doc-classes</samp>, <samp class="codeph">doc-sources</samp>,
and <samp class="codeph">doc-namespaces</samp> options are documented, with
the following exceptions:</p>
<ul>
<li>
<p>If you specified the class by using the <samp class="codeph">exclude-classes</samp> option,
the class is not documented. You must specify the package name of
the files to omit, such as mx.controls.Button, separated by spaces. </p>
</li>
<li>
<p>If the ASDoc comment for the class contains the <samp class="codeph">@private</samp> tag,
the class is not documented. </p>
</li>
<li>
<p>If the class is found in a SWC, the class is not documented.</p>
</li>
</ul>
<div class="p">In the following example, you generate output for all classes
in the current directory and its subdirectories, except for the
two classes comps\PageWidget and comps\ScreenWidget.as: <pre class="codeblock"> asdoc -source-path . -doc-sources . -exclude-classes comps.PageWidget comps.ScreenWidget </pre>
</div>
<p>The excluded classes are still compiled along with all the other
input classes; only their content in the output is suppressed.</p>
<p>Use the <samp class="codeph">exclude-sources</samp> option to exclude a
file from being input to the compilation. This option is different
from the <samp class="codeph">exclude-classes</samp> option which you use to
exclude a class from the output. However, the <samp class="codeph">exclude-classes</samp> option
still compiles the specified class. When you specify a class by
using the <samp class="codeph">exclude-sources</samp> option, the class is
not even compiled.</p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> You can only exclude classes added by the <samp class="codeph">doc-sources</samp> option,
not classes added by the <samp class="codeph">doc-namespaces</samp> or <samp class="codeph">doc-classes</samp> options. </div>
</div>
<div class="p">For example, the Flex mx/core package contains several include
files that are not stand-alone classes, but files included by other
classes. If you specify <samp class="codeph">doc-sources</samp> for mx/core,
you get compiler errors because the compiler tries to process all
the files in the directory. Instead, you can use the <samp class="codeph">exclude-source</samp> option
to specify the full path to the files to ignore from the compilation,
as the following example shows. Specify multiple paths separated
by spaces, as the following example shows:<pre class="codeblock">asdoc
-doc-sources C:\a\flex\flex\sdk\frameworks\projects\framework\src\mx\core
-exclude-sources C:\a\flex\flex\sdk\frameworks\projects\framework\src\mx\core\Version.as</pre>
</div>
</div>
<div class="nested3" id="WS4AF675C7-6535-4793-92B7-03A779094DF7_verapache"><a name="WS4AF675C7-6535-4793-92B7-03A779094DF7_verapache"><!-- --></a>
<h4 class="topictitle4">Excluding a namespace</h4>
<div>
<p>To exclude an entire namespace from ASDoc, edit the ASDoc_Config_Base.xml file
in the asdoc\templates directory of your Flex installation. </p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> Do not edit any other settings in the ASDoc_Config_Base.xml
file. Set all other options from the asdoc command line.</div>
</div>
<div class="p">For each namespace that you want to exclude, add a new <samp class="codeph">&lt;namespace&gt;</samp> tag
to the <samp class="codeph">&lt;namespaces&gt;</samp> tag in the ASDoc_Config_Base.xml
file, as the following example shows: <pre class="codeblock">&lt;namespaces hideAll="false"&gt;
...
&lt;namespace hide="true"&gt;my_custom_namespace&lt;/namespace&gt;
&lt;/namepaces&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS53d845b1b545acea-5be52e771266b3f5fd0-8000_verapache"><a name="WS53d845b1b545acea-5be52e771266b3f5fd0-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Adding ASDoc XML files to a SWC
files</h3>
<div>
<p>Flex SWC files include a docs folder that contains the
intermediate XML files created by the ASDoc tool. </p>
<p>You can add these XML files to your own SWC files. Normally,
these intermediate XML files are deleted when the ASDoc tool completes.
If you run the ASDoc tool with the <samp class="codeph">keep-xml</samp> and <samp class="codeph">skip-xsl</samp> options
set to <samp class="codeph">true</samp>, the XML files are retained. </p>
<p>By default, the ASDoc tool writes these XML files to the tempdita
directory in the output directory of your build. You have to manually
package them in your SWC file.</p>
</div>
</div>
<div class="nested2" id="WS0434D77E-8B7A-4fdc-A801-51265254877C_verapache"><a name="WS0434D77E-8B7A-4fdc-A801-51265254877C_verapache"><!-- --></a>
<h3 class="topictitle3">Handling ASDoc errors</h3>
<div>
<p>The ASDoc tool compiles all the input source files to generate
its output. Therefore, your source code must be valid to generate
ASDoc output. The ASDoc tool writes any compilation, such as syntax
errors, errors to the console window.</p>
<p>Errors in ASDoc comments are not compilation errors but they
do cancel the ASDoc build. For example, you can cause an error in
an ASDoc comment by omitting a closing <samp class="codeph">&lt;/code&gt;</samp> or <samp class="codeph">&lt;/p&gt;</samp> tag.
The source code still compiles, but ASDoc fails because it cannot
generate the output.</p>
<p>The following example shows the error message for an ASDoc comment
that omits a closing <samp class="codeph">&lt;/code&gt;</samp> tag:</p>
<div class="p">
<pre class="codeblock">[Fatal Error] :10:5: The element type "code" must be terminated by the matching end-tag "&lt;/code&gt;".
Encountered not well-formed text. Please see C:\flex\bin\framework-asdoc\validation_errors.log for details.</pre>
</div>
<p>The error message describes the condition that caused the error,
and specifies to view the validation_errors.log file for more information.
The validation_errors.log file contains additional information that
describes the error and the location of the error in the input file. </p>
<div class="p">Use the <samp class="codeph">lenient</samp> option to configure the ASDoc
tool to generate output even when it encounters an error in an ASDoc
comment. When specified, the <samp class="codeph">lenient</samp> option causes
the tool to omit the incorrect ASDoc comment from the output, but
to complete the build. The following example uses the <samp class="codeph">lenient</samp> option:<pre class="codeblock">asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls\Button.as
-lenient
-output framework-asdoc </pre>
</div>
<div class="p">With the <samp class="codeph">lenient</samp> option, you see the same error
message, and the ASDoc tool writes the same information to the validation_errors.log
file. But, the tool generates the output, as the following message
shows:<pre class="codeblock">[Fatal Error] :10:5: The element type "code" must be terminated by the matching end-tag "&lt;/code&gt;".
Encountered not well-formed text. Please see C:\flex\bin\framework-asdoc\validation_errors.log for details.<strong>
Documentation was created in C:\flex\bin\framework-asdoc\</strong></pre>
</div>
</div>
</div>
<div class="nested2" id="WS81930830-D5D4-471b-AF7C-544A6C29D140_verapache"><a name="WS81930830-D5D4-471b-AF7C-544A6C29D140_verapache"><!-- --></a>
<h3 class="topictitle3">Using a configuration file with
the ASDoc tool</h3>
<div>
<p>Depending on the number of input files, the input specification
to the ASDoc tool can get complex. To simplify it, you can use a
configuration file with the ASDoc tool. The configuration file is
an XML file that lets you specify the command-line arguments to
the tool in a file. YOu then run the tool as show below:</p>
<pre class="codeblock">asdoc -load-config+=<em>configFileName.xml</em> -output framework-asdoc </pre>
<p>By default, the ASDoc tool uses the flex\frameworks\flex-config.xml
configuration file. This configuration file contains many settings,
including the location of the Flex SWC files required to compile
the input files. You can want to look at this file for an example
of the types of information that you can write to a configuration
file. </p>
<p>The previous example uses the <samp class="codeph">load-config</samp> option
to specify the name of the configuration file. Notice that this
option uses the <samp class="codeph">+=</samp> syntax to add configFileName.xml
to the list of configuration files so that the tool still includes
the flex\frameworks\flex-config.xml configuration file. If you use
the <samp class="codeph">=</samp> syntax to specify the name of the configuration
file, you must also define much of the information in the flex\frameworks\flex-config.xml
configuration file. </p>
<div class="p">The following configuration file creates the same output as the
example in the section <a href="flx_asdoc_asd.html#WS1010D8F6-60A9-4438-9DB7-D1C0FC1E7F3C_verapache">Using
a manifest file as input</a> to generates ASDoc content for all
classes in the Flex framework.swc file: <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;flex-config xmlns="http://www.adobe.com/2006/flex-config"&gt;
&lt;compiler&gt;
&lt;source-path&gt;
&lt;path-element&gt;C:\flex\frameworks\projects\framework\src&lt;/path-element&gt;
&lt;/source-path&gt;
&lt;namespaces&gt;
&lt;namespace&gt;
&lt;uri&gt;http://www.adobe.com/2006/mxml&lt;/uri&gt;
&lt;manifest&gt;C:\flex\frameworks\projects\framework\manifest.xml&lt;/manifest&gt;
&lt;/namespace&gt;
&lt;/namespaces&gt;
&lt;/compiler&gt;
&lt;doc-classes&gt;
&lt;class&gt;FrameworkClasses&lt;/class&gt;
&lt;/doc-classes&gt;
&lt;doc-namespaces&gt;
&lt;uri&gt;http://www.adobe.com/2006/mxml&lt;/uri&gt;
&lt;/doc-namespaces&gt;
&lt;/flex-config&gt;</pre>
</div>
<p>For more information on configuration files, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fca_verapache">About
configuration files</a>.</p>
</div>
</div>
<div class="nested2" id="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7feb_verapache"><a name="WSd0ded3821e0d52fe1e63e3d11c2f44bb7b-7feb_verapache"><!-- --></a>
<h3 class="topictitle3">Options to the asdoc tool</h3>
<div>
<p>The <samp class="codeph">asdoc</samp> tool works the same way as the
mxmlc compiler and takes all the same command-line options. For
more information on mxmlc, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffd_verapache">Flex compilers</a>. </p>
<p>The following table lists the command-line options specific to
the <samp class="codeph">asdoc</samp> tool:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e3823">
<p>Option</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d51287e3829">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-doc-classes <em>path-element [...]</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>A list of classes to document. These classes
must be in the source path. This is the default option.</p>
<p>This
option works the same way as does the ‑include‑classes option for
the <samp class="codeph">compc</samp> component compiler. For more information,
see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fd2_verapache">Using
compc, the component compiler</a>. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-doc-namespaces <em>uri manifest</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>A list of URIs to document. The classes
must be in the source path.</p>
<p>You must include a URI and the
location of the manifest file that defines the contents of this
namespace. </p>
<p>This option works the same way as does the ‑include‑namespaces
option for the <samp class="codeph">compc</samp> component compiler. For more
information, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fd2_verapache">Using
compc, the component compiler</a>. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-doc-sources <em>path-element [...]</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>A list of files to document. If a directory
name is in the list, it is recursively searched.</p>
<p>This option
works the same way as does the ‑include‑sources option for the <samp class="codeph">compc</samp> component
compiler. For more information, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fd2_verapache">Using
compc, the component compiler</a>. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-examples-path <em>path-element</em>
</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>Specifies the location of the include examples
used by the <samp class="codeph">@includeExample</samp> tag. This option specifies
the root directory. The examples must be located under this directory
in subdirectories that correspond to the package name of the class.
For example, you specify the <samp class="codeph">examples-path</samp> as c:\myExamples.
For a class in the package myComp.myClass, the example must be in
the directory c:\myExamples\myComp.myClass.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-exclude-classes <em>string</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>A list of classes not documented. You must
specify individual class names. Alternatively, if the ASDoc comment
for the class contains the <samp class="codeph">@private</samp> tag, is not
documented. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-exclude-dependencies true|false</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>Whether all dependencies found by the compiler
are documented. If <samp class="codeph">true</samp>, the dependencies of the
input classes are not documented. </p>
<p>The default value is <samp class="codeph">false</samp>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-exclude-sources <em>path-element [...]</em>
</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>Exclude a file from compilation. This option
is different from the <samp class="codeph">-exclude-classes</samp> option which
you use to exclude a class from the output. However, the <samp class="codeph">-exclude-classes</samp> option
still compiles the specified class.</p>
<p>You can only exclude classes
added by the <samp class="codeph">doc-sources</samp> option, not classes added
by the <samp class="codeph">doc-namespaces</samp> or <samp class="codeph">doc-classes</samp> options. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-footer <em>string</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>The text that appears at the bottom of the
HTML pages in the output documentation.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-keep-xml=false|true</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>When <samp class="codeph">true</samp>, retain the intermediate
XML files created by the ASDoc tool. The default value is <samp class="codeph">false</samp>. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-left-frameset-width <em>int</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>An integer that changes the width of the
left frameset of the documentation. You can change this size to
accommodate the length of your package names. </p>
<p>The default
value is 210 pixels.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-lenient</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>Ignore XHTML errors (such as a missing &lt;/p&gt;
tag) and produce the ASDoc output. All errors are written to the
validation_errors.log file. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-main-title <em>"string"</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>The text that appears at the top of the
HTML pages in the output documentation. </p>
<p>The default value
is "<samp class="codeph">API Documentation</samp>". </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-output <em>string</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>The output directory for the generated documentation.
The default value is "<samp class="codeph">asdoc-output</samp>".</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-package <em>name</em> <em>"description"</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>The descriptions to use when describing
a package in the documentation. You can specify more than one <samp class="codeph">package</samp> option. </p>
<p>The
following example adds two package descriptions to the output: </p>
<p>
<samp class="codeph">asdoc -doc-sources my_dir -output myDoc -package com.my.business "Contains business classes and interfaces" -package com.my.commands "Contains command base classes and interfaces"</samp>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-package-description-file</samp>
<em>fileName</em>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>Specifies an XML file containing the package
descriptions. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-skip-xsl=false|true</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>When <samp class="codeph">true</samp>, configures the
ASDoc tool to generate the intermediate XML files only, and not
perform the final conversion to HTML. The default value is <samp class="codeph">false</samp>. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<p>
<samp class="codeph">-strict=false|true</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>Disable strict compilation mode. By default,
classes that do not define constructors, or contain methods that
do not define return values cause compiler failures. If necessary,
set <samp class="codeph">strict</samp> to <samp class="codeph">false</samp> to override
this default and continue compilation.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-templates-path <em>string</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>The path to the ASDoc template directory.
The default is the asdoc/templates directory in the ASDoc installation
directory. This directory contains all the HTML, CSS, XSL, and image files
used for generating the output. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3823 ">
<div class="p">
<pre class="codeblock">-window-title <em>"string"</em></pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d51287e3829 ">
<p>The text that appears in the browser window
in the output documentation. </p>
<p>The default value is "<samp class="codeph">API Documentation</samp>".</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The <samp class="codeph">asdoc</samp> command also recognizes the following
options from the compc component compiler:</p>
<ul>
<li>
<p>
<samp class="codeph">-source-path</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-library-path</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-namespace</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-load-config</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-actionscript-file-encoding</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-help</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-advanced</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-benchmark</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-strict</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">-warnings</samp>
</p>
<p>For more information, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fcc_verapache">Using
mxmlc, the application compiler</a>. All other application compiler
options are accepted but ignored so that you can use the same command-lines
and configuration files for the ASDoc tool that you can use for
mxmlc and compc.</p>
<p/>
</li>
</ul>
</div>
</div>
<p>Adobe and Adobe Flash Platform are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p>
</div>
</body>
</html>