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.

Comments (8)

matthew hornApril 29, 2008
Rambo 007 said on Apr 19, 2008 at 8:53 AM :

     I believe the example is missing a quote:

     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"
PerruchioJune 5, 2008
I have tried to create a .BAT file on a windows machine:
     cd "c:\Flex SDK 3.0\bin"
     asdoc -source-path "c:\projects\myProject\src\" -doc-sources "c:\projects\myProject\src\"
     pause

It results in a couple of errors.  One is in the CLI window:
     Error loading: D:\Program Files\Java\jre1.6.0_05\bin\client\jvm.dll

The other is an alert dialog:
     This application has failed to start because MSVC471.dll was not found. Re-installing the application may fix this problem.


This particular page, although it appears to be a windows example, is lacking details to indicate whether this approach is for Mac, Linux, or windows.  It futher assumes that the user knows to CD to the bin directory in the SDK before attempting these commands.  You guys could really do a much better job at documenting ASDOC.
Ergonomics ExpertSeptember 13, 2008
It would be great to see better documentation for asdoc in general, it is probably not too complex a tool but as an inexperienced programmer I have found the current documentation very difficult to put to use.

The example given on this page for generating documentation for the flex framework relates (as far as I can understand to the Flex2 SDK).

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

I am unable to get this to run on my machine and get various errors when attempting to run asdoc. And in any case I  would prefer to generate the Flex Framework documentation from the Flex3/4 SDK checked out via subversion from Adobe Opensource. This operation is probably a bit more involved in the usage of asdoc so I have no idea how to do it  quickly and properly and I am unable to work it out from the current material.


There appear to be many undocumented features  of asdoc such as -keep-xml options which I fould out via a blog http://rantworld.blogs.com/flashlit/2007/02/use_asdoc_to_dr.html which was very useful. The resultant toplevel_classes.xml is very useful for me to be able to obtain easily.

I have also raised this issue in the Flex Bug and Issue Management System that seems to be related to the lack of documention for asdoc under issue key SDK-16843 "ASDoc ant files are incorrect and do not work"

More useful documention/examples would be greatly appreciated moving forwards.

Thanks
smgilson(Administrator)September 25, 2008
Hi,

Sorry about the incorrect command. Here is the working version, as run from the bin directory of a Flex Builder installation:

C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\bin>asdoc -source-path ../frameworks/projects/framework/src  -namespace http://www.adobe.com/2006/mxml">http://www.adobe.com/2006/mxml ../frameworks/projects/framework/manifest.xml -doc-namespaces http://www.adobe.com/2006/mxml

Stephen Gilson
Flex Doc Team
Steven BirthNovember 5, 2008
Trying to use ASDoc on my application code and it works great until it hits a class based on Window class.  So I then added a source-path for mx.core  but then it complains it can't find NativeWindow which is referenced in Window.as.  And I can't find where NativeWindow is defined.

Here is the command line I'm using:
asdoc  -source-path ./src   -doc-sources ./src/com/myproject    -source-path "/applications/adobe flex builder 3/sdks/3.1.0/frameworks/projects/airframework/src"
wvxvw(Moderator)November 5, 2008
Do a search in your FB installation for airglobal.swc (in SDK it'd be in <SDK>frameworks\libs\air) Then add this SWC to the other libraries.
Cardin LeeDecember 11, 2008
Something really odd is that, for the footer option, there's no need to use quotation marks to demarcate the string:

-footer string

Shouldn't it have been this to maintain consistency:

-footer "string"
smgilson(Administrator)December 18, 2008
Cardin Lee wrote "...there's no need to use quotation marks"

Like most options, the quotation marks are optional unless the argument contains spaces. For example this is how you specify a multiword footer:

- footer "My footer string"

If you omit the quotation marks, you will get an error.

Stephen
You need to sign in in order to post a comment.

Adobe Flex 3 Help

Running the ASDoc tool

Excluding classes

Options to the asdoc command

Comments (8)