ASDoc: Javadoc for ActionScript

The Flex 2 SDK provides ASDoc, a Javadoc-like tool that generates HTML documentation from special comments in the ActionScript code. ASDoc shares many characteristics with Javadoc including comment syntax (/** @param */ and such), primary output format (HTML), and command-line usage.

The following code sample (Main.mxml) shows some simple code with ASDoc comments that will be used in this blog entry to demonstrate use of ASDoc.

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
                width="500" height="300">

  <mx:Script>
  <![CDATA[
  /*
   * To compile solely this Flex application from the command line, use
   *    mxmlc -strict=true Main.mxml
   *
   * To run asdoc against this code, use command like the following
   * (but on a single line):
   *    asdoc -source-path C:\flexExamples\AsDocExample
   *          -doc-sources Main.mxml
   *          -footer "<em>Copyright &#169; 2007 Dustin Marx</em>"
   *          -window-title "Dustin ASDoc Example"
   *          -main-title "Dustin's ASDoc Example"
   *          -output doc
   *
   * This application is intended to demonstrate ASDoc.
   */

  /**
   * 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 protected method and demonstrates asdoc documentation for a
   * protected method.
   *
   * @param aString String to be traced.
   */
  protected function protectedMethod(aString:String):void
  {
    trace( "protectedMethod(String) received " + aString );
  }

  /**
   * This is a private method and demonstrates asdoc documentation for a private
   * method.
   *
   * @param aString String to be traced.
   */
  private function privateMethod(aString:String):void
  {
    trace( "privateMethod(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";

  /** A protected property String. */
  protected var protectedProperty:String = "A Protected Property";

  /** A private property String. */
  private var privateProperty:String = "A Private Property";

  /** A public property which won't have ASDoc generated for it.
   *
   * @private
   */
  public var publicHiddenProperty:String = "A Public But Not ASDoc-ed Property";

  /** A public constant. */
  public const PI_ROUGH:Number = 3.14159265;

  /** A protected constant. */
  protected const DEFAULT_WIDTH:int = 50;

  /** A private constant. */
  private const DEFAULT_HEIGHT:int = 100;
  ]]>
  </mx:Script>

  <mx:Panel id="mainPanel">
    <mx:Label text="ASDoc will NOT generate documentation for MXML." />
    <mx:Label text="Run asdoc against this code and then view generated HTML." />
  </mx:Panel>

</mx:Application>

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:

asdoc -source-path C:\flexExamples\AsDocExample
      -doc-sources Main.mxml
      -footer "<em>Copyright &#169; 2007 Dustin Marx</em>"
      -window-title "Dustin ASDoc Example"
      -main-title "Dustin's ASDoc Example"
      -output doc

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:

* Adobe Labs Flex Ant Tasks

* Adobe Labs Flex Ant Tasks Discussion

* Christophe Herreman's ASDoc Ant Task

* Ruben Swieringa's ASDoc Generation in Ant

* Flexed: ANT Task to Generate ASDoc


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.


Finally, three other useful and relevant resources on ASDoc are ASDoc: What Comments Get Used and Where Do They Go?, ActionScript Comment Guidelines, and How To Document Your Code with ASDoc.