Using the asdoc task

The Flex Ant tasks include a task to run the asdoc utility. This utility generates HTML documentation based on a defined set of tags that you can include in your ActionScript and MXML files.

For more information about using ASDoc, see ASDoc.

Required attributes

The asdoc Ant task requires that you specify a target class or classes to generate ASDoc for. This must be either a list of one or more classes, a directory of classes, or a namespace. You specify these by using the doc-classes, doc-sources, or doc-namespaces attributes.

If you use the doc-classes or doc-namespaces attributes, you must also specify a source-path argument. If you use the doc-namespaces attribute, you must also specify a namespace attribute.

Adobe recommends that you specify a value for the output attribute. If you do not specify a value, Ant creates a directory called asdoc-output in the same directory that you launched the command from. Ant then stores the HTML output files in that new directory.

Unsupported options

All options of the asdoc utility are supported by the asdoc Ant task.

Example

The following example defines two targets, doc and clean. The doc target generates ASDoc for the Spark and MX button classes. The clean target deletes all the files generated by the doc target.
<?xml version="1.0" encoding="utf-8"?> 
<project name="ASDoc Builder" basedir="."> 
    <property name="FLEX_HOME" value="C:/p4/flex/flex/sdk"/> 
    <property name="OUTPUT_DIR" value="C:/temp/ant/asdoc"/> 
    <taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" /> 
    <target name="doc"> 
        <asdoc output="${OUTPUT_DIR}" lenient="true" failonerror="true"> 
            <doc-sources 
                path-element="${FLEX_HOME}/frameworks/projects/spark/src/spark/components/Button.as"/> 
            <doc-sources 
                path-element="${FLEX_HOME}/frameworks/projects/framework/src/mx/controls/Button.as"/> 
        </asdoc> 
    </target> 
    <target name="clean"> 
        <delete includeEmptyDirs="true"> 
            <fileset dir="${OUTPUT_DIR}" includes="**/*"/> 
        </delete> 
    </target> 
</project>

You will have to change the values of the Flex home and output directory to match the locations of the directories on your file system.

To run this example, you can use the following Ant command:

ant clean doc

This example generates simple ASDoc output for the Spark and MX Button controls by using the doc-sources attribute. The output does not include all the parent classes that provide the inherited methods, properties, events, and other members of the Button controls.

To generate ASDoc that includes the parent classes of the Button controls, you can use an Ant task that uses the doc-classes attribute. When you do this, you must be sure to also define the source-path for the classes.

The following example generates ASDoc for the MX Button control. It includes the parent classes that this control inherits its members from. 
<?xml version="1.0" encoding="utf-8"?> 
<project name="ASDoc Builder" basedir="."> 
    <property name="FLEX_HOME" value="C:/p4/flex/flex/sdk"/> 
    <property name="OUTPUT_DIR" value="C:/temp/ant/asdoc"/> 
    <taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" /> 
    <target name="doc"> 
        <asdoc output="${OUTPUT_DIR}" lenient="true" failonerror="true"> 
            <compiler.source-path 
                path-element="${FLEX_HOME}/frameworks/projects/framework/src"/> 
            <doc-classes class="mx.controls.Button"/> 
        </asdoc> 
    </target> 
    <target name="clean"> 
        <delete includeEmptyDirs="true"> 
            <fileset dir="${OUTPUT_DIR}" includes="**/*"/> 
        </delete> 
    </target> 
</project>

You can also define an asdoc Ant task that includes all components in a particular namespace by using the doc-namespaces attribute. When you want to document all classes in a namespace, you must also point to the manifest file for that namespace by using the namespace attribute.

The following example generates ASDoc for all components in the Spark namespace:
<?xml version="1.0" encoding="utf-8"?> 
<project name="ASDoc Builder" basedir="."> 
    <property name="FLEX_HOME" value="C:/p4/flex/flex/sdk"/> 
    <property name="OUTPUT_DIR" value="C:/temp/ant/asdoc"/> 
    <taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/ant/lib/flexTasks.jar" /> 
    <target name="doc"> 
        <asdoc output="${OUTPUT_DIR}" lenient="true" failonerror="true"> 
            <compiler.source-path 
                path-element="${FLEX_HOME}/frameworks/projects/spark/src"/> 
            <doc-namespaces uri="library://ns.adobe.com/flex/spark"/> 
            <namespace 
                uri="library://ns.adobe.com/flex/spark" 
                manifest="${FLEX_HOME}/frameworks/projects/spark/manifest.xml"/> 
        </asdoc> 
    </target> 
    <target name="clean"> 
        <delete includeEmptyDirs="true"> 
            <fileset dir="${OUTPUT_DIR}" includes="**/*"/> 
        </delete> 
    </target> 
</project>

In this example, only the members that are inherited from other classes in the Spark namespace are added to the ASDoc output.

The flex-config.xml file contains a list of predefined namespace URIs and the locations of their manifest files. As a result, if you use the asdoc Ant task to generate ASDoc for one of these namespaces, and not a custom namespace, then you are not required to define the location of the manifest file. This is because the asdoc Ant task reads in their definitions. It is, however, best practice to define the manifest file location for all namespaces.