/** * This is a public method and demonstrates asdoc documentation for a public * method. * * @param aString String to be traced. */ public function publicMethod(aString:String):void { trace( "publicMethod(String) received " + aString ); }

/** * This is a public method that won't be documented in asdoc-generated HTML * documentation because of the @private tag included herein. * * @param aString String to be traced. * @private */ public function publicHiddenMethod(aString:String):void { trace( "publicHiddenMethod() received " + aString ); }

/** A public property String. */ public var publicProperty:String = "A Public Property";

If you've worked with Javadoc-style comments in the past, the ASDoc-style comments above will look very familiar. You can find additional ASDoc-supported tags in the Flex 2 ASDoc Tags documentation. Besides the @param tag and @private tag shown above, other commonly used tags include @return, @throws, and @see.

The following command (shown here intentionally on multiple lines for clarity in reading but executed on a single line on command line) runs asdoc against the above code (assuming files stored in directory C:\flexExamples\AsDocExample:

In the above example of running asdoc, not all of the available options were used. However, some of the most common options were used above and I explain some of them briefly here.

The -source-path option specifies at which top-level path the asdoc generation tool should look for code to document. The -doc-sources option is used here to specifically instruct asdoc to run against Main.mxml. Specifying a single application-level file in this manner is a workaround for a problem that manifests itself with the error message "The private attribute may be used only on class property definitions" (see Flex Bug SDK-782).

The -footer option allows for a String to be specified that is placed on the bottom of each generated page (in this case a typical copyright statement). The -window-title and -main-title options allow for designation of Strings respectively for the browser window and for the top of the main page in the generated documentation. It is very handy to specify -window-title so that the generic default of "API Documentation" is not used. Even worse, though, is when -window-title is specified with a "bad" String, in which case "Adobe Flex 2 Language Reference" is applied as the browser window title. This is confusing in a tabbed browser because it makes it appear that this if Flex 2 documentation rather than your own application's documentation.

The -output option specifies which directory the generated documentation should be written to and in this case is relative to the current directory.

Based on the -output setting used above, we expect to find our generated documentation in the doc subdirectory. If we access index.html in that directory in our favorite web browser, we will indeed see the generated documentation.

A screen snapshot cannot really do justice to the ASDoc-generated HTML documentation, but here is a screen snapshot in a weak attempt to show what the output looks like:

From the above example, several lessons regarding asdoc can be gleaned:

1. ASDoc does not generate documentation for private methods or for private properties. Unlike Javadoc and it's -private option, ASDoc does not appear to have any mechanism to specify that ASDoc should be generated for private methods and properties.

2. ASDoc syntax is suspiciously similar to Javadoc syntax. This makes it easier for Java developers to work with ActionScript.

3. ASDoc does not generate documentation for MXML tags, though it does generate documentation for constants, properties, methods, and other ActionScript objects that are embedded within the <mx:Script tags. Likewise, any external ActionScript code included with <mx:Script source="... also gets its ASDoc comments processed for documentation generation. Finally, Action classes included within the Script section of the MXML document with the import statement likewise have their ASDoc-style comments included in the generated documentation.

4. The @private tag does keep a public method that would otherwise be documented from being documented.

5. While not called out above, ASDoc only works with ActionScript 3.0 and not with its predecessors such as ActionScript 2.

The ASDoc command-line tool can be a little ornery at times (such as an extra single apostrophe passed to the -window-title option causing it to display "Flex 2 Language Reference" in the browser window). It can also be less user friendly than some would like. Therefore, it is not surprising that several people have worked on Ant tasks for use with ASDoc. The following are some blog entries on these efforts:

I found the blog entry Use ASDoc to Drive New Processes interesting because it outlines two ASDoc command-line options that are not documented in the documentation referenced above. The two additional undocumented options, -keep-xml and -skip-xsl allow greater control of intermediate file creation performed as part of the asdoc documentation generation process. Specifically, these options can be used to respectively retain intermediate XML files generated by ASDoc and to skip transformation of the generated XML documents into HTML output.