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.