ASDoc now works with Flex MXML files

The new Flex 4 SDK is coming along quite nicely over at opensource.adobe.com. All you documentation geeks (there are some of you out there, right?) will be interested in the new ASDoc in MXML feature.

In the past the ASDoc engine could read comments from ActionScript source files, but not from MXML files. That left some big holes in the docs for Flex-based applications.

The new ASDoc engine reads MXML comments and treats them just like ActionScript comment blocks.

Here's an example of how to comment your MXML files:

<?xml version="1.0"?>
<!--- 
   This is the class level comment for the component. 
   This comment supports all ASDoc tags.

   @see mx.container.VBox
-->
<mx:VBox>

 <mx:Script>
  <![CDATA[
  import flash.events.Event;

  /** 
   * For methods, properties, and metadata tags in a Script block,
   * the same commenting rules apply as in an AS file.
   *
   * @eventType com.mydomain.events.EnableChangeEvent
   */
  private function handleChangeEvent(eventObj:Event):void 
  {
   dispatchEvent(eventObj);
  } 
  ]]>
 </mx:Script>

 <!--- 
   This comment describes the following button.
 --> 
 <mx:Button id="awesomeButton" label="Awesome"/>

</mx:VBox>

Note that the XML comment block must start with 3 dashes, not 2 dashes for it to be recognized by ASDoc. For example, this comment block will be processed:

<!--- ASDoc-friendly comment. -->

But this comment block will be ignored:

<!-- Traditional XML comment with 2 dashes, ignored by ASDoc. -->

Have a look at the detailed ASDoc in MXML specification to see more examples.

The good news is that you don't have to wait for the official Flex 4 release to use the new version of ASDoc. It's already available for testing (please let us know if you find any bugs!). Just download a recent nightly build of the Adobe Flex 4 SDK from the Gumbo downloads page. You will find the latest asdoc executable in the bin/ folder.

Comments

[Jeremy Holland]

This post is literally my savior - boss wants every class documented with a big old hunk of commentary at the top, and I was going to have to edit the generated HTML to do it otherwise. THANK YOU!!!

[Jeremy Holland]

Actually, just found what appears to be a small issue ( I may be mistaken - the options may have changed and I'm just not aware of it ). If you declare custom namespaces for external swc libraries in your MXML component, and then use the -external-library-path option to tell ASDoc to ignore it, it still seems to try to look for it when it parses that xml namespace attribute, and fires an error when it can't. Here's my code for reference, as AssetsPanel.mxml:

And here's the error that the new ASDoc returns:

/path/to/component/AssetsPanel.mxml(-1): Error: Type was not found or was not a compile-time constant: *.

If I remove the external item and thus the namespace, it works fine.