« Incremental Compilation from the Command-line | Main | The Article to Send to Your Friends »

The Plan for ASDoc on Labs

Update: Flex now includes ASDoc. The documentation is here.

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

Comments (6)

Will it support generating documentation from AS2 classes as well? The syntax is close enough I suspect it should (except for the differing way of declaring packages)


The tool will not support documenting AS2 classes. It uses the Flex 2 compiler infrastructure, which can not parse AS2.


Does this include the flash packages in the summary lists?

Does it add UIComponent types in the inheritience summary, IE include adobe docs OR does it just doc the structure of the classes you give it.

Said differently, can you give it flash.events.EventDispatcher to add into your documentation?

Any plans on an mxml documenter?

Peace, Mike


This won't include the flash packages in the summary lists. It won't document any non-source packages, so the Flex packages won't be included unless you have the source to them and include them in a source-path.

MXML components will be documented, but there will be a number of limitations on this in the first release.

wow ! finally it's coming :-)

We are trying to standardize the scripting language documentation format. There is JSDoc and ASDoc and others. We've created ScriptDoc.org to bring these all together. I'd like to get in touch with someone at Adobe about their becoming part of this effort.

I can also be reached at paul at aptana dot com.