Running the ASDoc tool


You use the following options to specify the list of classes processed by the asdoc command: doc-classes, doc-sources, 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.

The most basic example is to specify a class or list of classes using the doc-classes option, as the following example shows:

asdoc -source-path . -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo

In this example, the classes must be located at comps\GraphingWidget.as and comps\GraphingWidgetTwo.as, where comps is a subdirectory of the directory from which you run the asdoc command. The arguments of the doc-classes option use dot notation that corresponds to the package name of the class.

If the classes are not in the current directory, use the source-path option to specify that directory. For example, if the two input classes are in the directory C:\flex\class_dir\comps, then use the following command-line to invoke asdoc:

asdoc -source-path C:\flex\class_dir -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo

Your application might require library files, represented as SWC files, to compile. In the next example, you use the -library-path option to specify the directory containing the SWC files:

asdoc -source-path . -doc-classes myComponents.BlueButton  -library-path C:\myLibs

You can also specify the source classes by using the doc-sources option. This option causes asdoc to recursively search directories. The following command line generates output for all classes in the current directory and its subdirectories:

asdoc -source-path . -doc-sources .

You can specify a namespace as the input by using the doc-namespaces option. The following command line documents all the classes in the core framework:

asdoc -source-path frameworks 
    -namespace http://framework frameworks/core-framework-manifest.xml 
    -doc-namespaces http://framework

Excluding classes

All of 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.
  • 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

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

If you set the exclude-dependencies option to true, dependent classes found when compiling 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.

For example, you specify class A by using the doc-classes option. If class A imports class B, both class A and class B are documented.

Options to the asdoc command

The options to the asdoc command work the same way that mxmlc and compc options work. For more information on mxmlc and comp, see Using the Flex Compilers.

The following table lists the options to the asdoc command:

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 whose classes should be documented. 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 that should be documented. 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.

-exclude-classes string A list of classes that should not be 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.

-footer string The text that appears at the bottom of the HTML pages in the output documentation.
-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.

-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”

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

~ by mjcprasad2000 on May 2, 2009.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

 
%d bloggers like this: