Deitte.com

We're hoping to release ASDoc, the Flex and AS3 documentation tool, to labs within the next month. As Matt Chotin already let the cat out of the bag on flexcoders, I figured I could get away with a post on this not-guaranteed-but-that's-what-we're-planning release.

ASDoc is the tool that was used to create the language reference. Current output from this tool looks very similar to the language reference. I'll give a little idea in this post on how the tools is used, but you'll have to wait until an actual release of the tool to get the full details.

The HTML files are created by entering a list of classes, sources or namespaces, as well as additional parameters for controlling the look of the output.

Creating comments in code follow the conventions shown in the Flex source. Here's an example of documenting a function:

/** 
 * This is the typical format of a simple multiline (single paragraph) main description 
 * for the myFunction function, which is declared in the ActionScript code below. 
 * Note the leading asterisks and single white space following each asterisk. 
 * 
 * @param param1 Param1 description. 
 * @param param2 Param2 description.
 * @return Return value described here.  
 */
  public function myFunction(param1:String, param2:Number):Boolean

Comments can be added to public class definitions, public function definitions (including getters and setters), public class-level variables, Event metadata, Style metadata, and Effect metadata. All other comments are ignored. There's a lot of tags, like @param and @return, that can be used to provide meta information to ASDoc. Some of the most popular are @author, @default, @private (no parameters, to hide a function/var/class), @see, @throws (two parameters, name and description).

This is the project for labs that I mentioned a few posts ago that I am working on. It's coming along well, with the integration into the core of the Flex compiler being surprisingly simple but with lots of time being spent on making the details work right.

Update: ASDoc is now out. See here for details