Using the ASDoc tool

The ASDoc tool, asdoc, 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.

To see a list of the command-line options available to the ASDoc tool, use the ‑help list option, as the following example shows:
asdoc -help list
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 library-path option to specify the directory containing the SWC files: 
asdoc ... -library-path+=C:\myLibs

You can also use a Flex Ant task to run the ASDoc tool. For more information, see Using the asdoc task.

Defining the input files to the ASDoc tool

Use the following options to specify the list of classes processed by the asdoc command: doc-sources, doc-classes, and doc-namespaces. The doc-classes and doc-namespaces options require you to specify the source-path option to specify the root directory of your files.

Note: 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.

The most basic example is to specify the path to a single class by using the doc-sources option, as the following example shows:

asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls\Button.as 
    -output framework-asdoc
This example generates ASDoc content for the Flex Button control shipped with Flex, and writes the output to the flex\bin\framework-asdoc directory.

You can specify multiple input class files, separated by spaces, as the following example shows:

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

The two previous examples use the output 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.

The doc-sources 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:

asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls 
    -output framework-asdoc

You can specify multiple directories, separated by spaces.

Use the doc-classes option to specify the package and class name of a file to process. Use the doc-classes option with the source-path option, as the following example shows:

asdoc -source-path C:\flex\frameworks\projects\framework\src 
    -doc-classes mx.controls.Button mx.controls.ButtonBar  
    -output framework-asdoc

The source-path 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 doc-classes option is a space delimited list of input files that use dot notation to specify the package name of each class.

You can combine the doc-sources and doc-classes options to specify the input to the ASDoc tool, as the following example shows:

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

In this example, you compile all the validator classes as well as the Button and ButtonBar components.

Compiling dependent files

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 doc-classes option. If class A imports class B, both class A and class B are compiled and included in the ASDoc output.

The following example specifies only the mx.controls.Button class as input:
asdoc -source-path C:\flex\frameworks\projects\framework\src  
    -doc-classes mx.controls.Button 
    -output framework-asdoc

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 source-path option to locate these dependent classes.

If you set the exclude-dependencies option to true, dependent classes found when compiling the input classes are not documented. The default value is false, which means any classes that would normally be compiled along with the specified classes are documented.

The following example generates ASDoc content only for the Button class: 
asdoc 
    -source-path C:\flex\frameworks\projects\framework\src  
    -doc-classes mx.controls.Button 
    -output framework-asdoc 
    -exclude-dependencies=true
Setting the exclude-dependencies option to true improves the performance of the ASDoc tool because you do not have to build output for all dependent classes.
Note: You cannot use exclude-dependencies with input class specified by the doc-sources option.

Adding package descriptions

To add package descriptions to the output, you can use the package or package-description-file options of ASDoc.

The package option lets you specify the descriptions on the ASDoc command line. You can specify more than one package option. The following example adds two package descriptions to the output: 
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"
If you have many packages, you can use the package-description-file option to specify an XML file that contains the descriptions, as the following example shows: 
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
In this example, the package descriptions are located in the myPackages.xml file. The file specified by the package-description-file option has the following format: 
<overviews> 
    <packages> 
        <package name="package.name1"> 
            <shortDescription> 
                <![CDATA[ 
                    Short description appears on the All Packages page. 
                ]]> 
            </shortDescription> 
            <description> 
                <![CDATA[ 
                    Long description appears on the package page. 
                ]]> 
            </description> 
        </package> 
    </packages> 
</overviews>
For example: 
<overviews> 
    <packages> 
        <package name="mx.core"> 
            <shortDescription> 
                <![CDATA[ 
                    The &lt;b&gt;mx.core package&lt;/b&gt; contains the 
                    base classes and interfaces. 
                ]]> 
            </shortDescription> 
            <description> 
                <![CDATA[ 
                    The mx.core package contains the 
                    base classes and interfaces, 
                    such as UIComponent, used by Flex. 
                ]]> 
            </description> 
        </package> 
        <package name="mx.controls"> 
            <shortDescription> 
                <![CDATA[ 
                    The mx.controls package contains 
                    the Flex user-interface controls. 
                ]]> 
            </shortDescription> 
            <description> 
                <![CDATA[ 
                    The mx.controls package contains 
                    the Flex user-interface controls. 
                ]]> 
            </description> 
        </package> 
    </packages> 
</overviews>

Notice that the HTML tag for bold text is entered by using the HTML character code for the “<“ and “>” characters.

Using a manifest file as input

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:

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

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 doc-classes option, and the manifest file by using the doc-namespace 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.

For more information on manifest files, see About manifest files.

Excluding classes

All the classes specified by the doc-classes, doc-sources, and doc-namespaces options are documented, with the following exceptions:

  • If you specified the class by using the exclude-classes 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.

  • If the ASDoc comment for the class contains the @private tag, the class is not documented.

  • If the class is found in a SWC, the class is not documented.

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: 
asdoc -source-path . -doc-sources . -exclude-classes comps.PageWidget comps.ScreenWidget

The excluded classes are still compiled along with all the other input classes; only their content in the output is suppressed.

Use the exclude-sources option to exclude a file from being input to the compilation. This option is different from the exclude-classes option which you use to exclude a class from the output. However, the exclude-classes option still compiles the specified class. When you specify a class by using the exclude-sources option, the class is not even compiled.

Note: You can only exclude classes added by the doc-sources option, not classes added by the doc-namespaces or doc-classes options.
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 doc-sources for mx/core, you get compiler errors because the compiler tries to process all the files in the directory. Instead, you can use the exclude-source 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:
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

Excluding a namespace

To exclude an entire namespace from ASDoc, edit the ASDoc_Config_Base.xml file in the asdoc\templates directory of your Flex installation.

Note: Do not edit any other settings in the ASDoc_Config_Base.xml file. Set all other options from the asdoc command line.
For each namespace that you want to exclude, add a new <namespace> tag to the <namespaces> tag in the ASDoc_Config_Base.xml file, as the following example shows: 
<namespaces hideAll="false"> 
... 
    <namespace hide="true">my_custom_namespace</namespace> 
</namepaces>

Adding ASDoc XML files to a SWC files

Flex SWC files include a docs folder that contains the intermediate XML files created by the ASDoc tool. These files are used by Adobe® Flash® Builder™ to show code hints and documentation.

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 keep-xml and skip-xsl options set to true, the XML files are retained.

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.

Handling ASDoc errors

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.

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 </code> or </p> tag. The source code still compiles, but ASDoc fails because it cannot generate the output.

The following example shows the error message for an ASDoc comment that omits a closing </code> tag:

[Fatal Error] :10:5: The element type "code" must be terminated by the matching end-tag "</code>". 
Encountered not well-formed text. Please see C:\flex\bin\framework-asdoc\validation_errors.log for details.

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.

Use the lenient option to configure the ASDoc tool to generate output even when it encounters an error in an ASDoc comment. When specified, the lenient option causes the tool to omit the incorrect ASDoc comment from the output, but to complete the build. The following example uses the lenient option:
asdoc -doc-sources C:\flex\frameworks\projects\framework\src\mx\controls\Button.as 
    -lenient 
    -output framework-asdoc
With the lenient 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:
[Fatal Error] :10:5: The element type "code" must be terminated by the matching end-tag "</code>". 
Encountered not well-formed text. Please see C:\flex\bin\framework-asdoc\validation_errors.log for details. 
Documentation was created in C:\flex\bin\framework-asdoc\

Using a configuration file with the ASDoc tool

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:

asdoc -load-config+=configFileName.xml -output framework-asdoc

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.

The previous example uses the load-config option to specify the name of the configuration file. Notice that this option uses the += 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 = 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.

The following configuration file creates the same output as the example in the section Using a manifest file as input to generates ASDoc content for all classes in the Flex framework.swc file: 
<?xml version="1.0"?>
<flex-config xmlns="http://www.adobe.com/2006/flex-config">

    <compiler>        
        <source-path>
            <path-element>C:\flex\frameworks\projects\framework\src</path-element> 
        </source-path>           

        <namespaces>    
            <namespace>
                <uri>http://www.adobe.com/2006/mxml</uri>
                <manifest>C:\flex\frameworks\projects\framework\manifest.xml</manifest>
            </namespace>
        </namespaces>    
    </compiler>

    <doc-classes>
        <class>FrameworkClasses</class>
    </doc-classes>
        
    <doc-namespaces>
        <uri>http://www.adobe.com/2006/mxml</uri>
    </doc-namespaces>
</flex-config>

For more information on configuration files, see About configuration files.

Options to the asdoc tool

The asdoc tool works the same way as the mxmlc compiler and takes all the same command-line options. For more information on mxmlc, see Flex compilers.

The following table lists the command-line options specific to the asdoc tool:

Option

Description

 
-doc-classes path-element [...]

A list of classes to document. These classes must be in the source path. This is the default option.

This option works the same way as does the ‑include‑classes option for the compc component compiler. For more information, see Using compc, the component compiler. 

-doc-namespaces uri manifest

A list of URIs to document. The classes must be in the source path.

You must include a URI and the location of the manifest file that defines the contents of this namespace.

This option works the same way as does the ‑include‑namespaces option for the compc component compiler. For more information, see Using compc, the component compiler. 

-doc-sources path-element [...]

A list of files to document. If a directory name is in the list, it is recursively searched.

This option works the same way as does the ‑include‑sources option for the compc component compiler. For more information, see Using compc, the component compiler.

-examples-path path-element

Specifies the location of the include examples used by the @includeExample 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 examples-path as c:\myExamples. For a class in the package myComp.myClass, the example must be in the directory c:\myExamples\myComp.myClass.

 
-exclude-classes string

A list of classes not documented. You must specify individual class names. Alternatively, if the ASDoc comment for the class contains the @private tag, is not documented. 

-exclude-dependencies true|false

Whether all dependencies found by the compiler are documented. If true, the dependencies of the input classes are not documented.

The default value is false.

-exclude-sources path-element [...]

Exclude a file from compilation. This option is different from the -exclude-classes option which you use to exclude a class from the output. However, the -exclude-classes option still compiles the specified class.

You can only exclude classes added by the doc-sources option, not classes added by the doc-namespaces or doc-classes options. 

-footer string

The text that appears at the bottom of the HTML pages in the output documentation.

-keep-xml=false|true

When true, retain the intermediate XML files created by the ASDoc tool. The default value is false. 

-left-frameset-width int

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.

The default value is 210 pixels.

-lenient

Ignore XHTML errors (such as a missing </p> tag) and produce the ASDoc output. All errors are written to the validation_errors.log file. 

-main-title "string"

The text that appears at the top of the HTML pages in the output documentation.

The default value is "API Documentation". 

-output string

The output directory for the generated documentation. The default value is "asdoc-output".

 
-package name"description"

The descriptions to use when describing a package in the documentation. You can specify more than one package option.

The following example adds two package descriptions to the output:

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"

-package-description-filefileName

Specifies an XML file containing the package descriptions.

-skip-xsl=false|true

When true, configures the ASDoc tool to generate the intermediate XML files only, and not perform the final conversion to HTML. The default value is false.

-strict=false|true

Disable strict compilation mode. By default, classes that do not define constructors, or contain methods that do not define return values cause compiler failures. Set strict to false to override this default and continue compilation.

 
-templates-path string

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. 

-window-title "string"

The text that appears in the browser window in the output documentation.

The default value is "API Documentation".

The asdoc command also recognizes the following options from the compc component compiler:

  • -source-path

  • -library-path

  • -namespace

  • -load-config

  • -actionscript-file-encoding

  • -help

  • -advanced

  • -benchmark

  • -strict

  • -warnings

    For more information, see Using mxmlc, the application compiler. 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.