Using ASDoc with MXML Files and Included Scripts

The new ASDoc tool in Flex 4 does a great job getting rid of problems documenting with MXML components. You can now document projects that contain references to MXML and you can document the MXML components themselves!

The ASDoc documentation generator tool that ships with Flex is extremely useful but not without its drawbacks. In Flex 3, ASDoc's support for MXML files is missing completely: not only does it produce no documentation for MXML files, it won't even compile if your regular ActionScript classes make any references to MXML components.

A lot of custom Flex components are more efficiently expressed in MXML so I didn't want to give up on MXML components because of a problem with ASDoc. It might be possible to work around this problem using some object-oriented trickery (I think creating Actionscript superclasses might do the trick), however, there's a much better solution.

In Flex 4, Adobe has addressed the limitations with MXML. If you download one of the Flex 4 nightly builds, you'll have the updated ASDoc tool.

The version I used won't choke on source trees with references to MXML and files. Even better, it will produce documentation from comments in the MXML that begin with three hyphens:

<---
      This comment will be found by the new ASDoc tool!
    -->

Check out the MXML spec for more information. Like the Actionscript inline documentation, you have to put these comments in specific places so the documentation generator knows what to do with them.

Unfortunately, there are still some problems with the tool. Scripts that you include with a <mx:Script source="script.as" /> tag aren't handled very well. If you use modifiers/namespaces like public, protected, or static, the compiler's going to complain that they're not members of a class.

C:\src\script.as(288): col: 1 Error: The private attribute may be used
only on class property definitions.
 
private function func():void

There are two ways to get around this. Don't use the "source" attribute to include the script, just paste it directly into your MXML file under a <mx:Script /> tag.

I haven't tried option number two but you should be able to define the members and methods on an Actionscript class, and then create an MXML component as a subclass. Private methods would have to be set to protected.

Still an annoying drawback as I like to separate MXML and AS3 code but this is a huge improvement!

By the way, if you're generating AS3 documentation on windows, this ASDoc batch file example might be of use to you.