Use ASDoc to drive new processes

The ASDoc tool that comes with Flex Builder and the Flex 2 SDK generates great looking docs from your ActionScript and MXML code, but it can drive other types of documents, reports, and processes too. All you need are these undocumented command-line parameters...and of course mega programming skills.

Here are some undocumented command-line parameters you can use with the ASDoc tool to make it even more useful.

-keep-xml

ASDoc initially generates an XML file that contains all the metadata and documentation comments from your code. Then it applies XSL stylesheets to that XML to generate all that attractively formatted HTML output. Then it deletes the interim XML file.

If you use the -keep-xml option though it will save the interim XML file, which is named toplevel_classes.xml. The data in this file can be amazingly useful. We have used it many ways at Adobe, including:

• Converting to XMI files for input to UML modeling tools
• Generating code colorizing and hinting files for Flash 9
• Generating test scripts
• Experimenting with Flex-based documentation browsers

Even if your source code has no comments all the basic structural information about your code, covering things like packages, classes, methods, properties, and events, is output to the toplevel_classes.xml file as nice, structured XML.

-skip-xsl

The -skip-xsl parameter stops the ASDoc process before it generates the HTML output. It goes hand in hand with the -keep-xml parameter. When you use them in combination ASDoc will generate the toplevel_classes.xml file and then stop. This parameter isn't necessary, but it speeds up the build process if you don't care about generating the HTML.

-show-actionscript-warnings=false

If your source code generates a lot of warnings, you can use this parameter to stop them from cluttering the console.

The parameters above were added to ASDoc too late to get into the official documentation, but I do recommend you check out that documentation to learn how to run ASDoc and write good doc comments.

If you end up using the ASDoc XML to develop something new and interesting, please let me know!

Comments

[Chris Charlton]

Useful; thank you.

[Ms Organic]

Thanks I was trying to get my head around this stuff

[Chris]

This is great info, Rob, thanks. You mention using this data to generate code hinting, can you provide any guidance on how to do that? Do you have any scripts available? I always do my best to avoid re-inventing...

Also, I am trying to use this info to build a help_toc.xml file for use with a Flash MXP, any chance you can point me towards resources to help with that?

Thanks again!

[Chris]

Well, after much work and pulling of hair, I was able to use the toplevel_classes.xml to generate the help table of contents, actions panel entries and color syntax file required for my extension. I have actually built a very simple AIR app to automate the process.

I plan to make this app available to the public at some point, but currently it is embarrassingly sloppy and contains some company-specific settings.

If anyone is interested or needs guidance with this conversion, drop me a line. chris [] webdeely {dot} com

[Austin Dimmer]

Rob,

Thank you for posting this information, for me it is a lifesaver! I wonder why it is not officially documented anywhere? Do you have any tips about how to generate a local copy of the entire Flex3 Framework documentation? I have a strong need to obtain a copy of the toplevel_classes.xml for the entire Flex 3 Framework. I have been trying for days but keep getting errors from ASDoc when I run it so I am unable to obtain the output. The official flex documentation seems to refer to generating the documentation for the Flex2 SDK (which I also can't get to work, due to some actionscript errors in the source files). I am currently using Ant to call asdoc to generate the documentation. I found the Ant Script on Christopher Herreman's blog which is most helpful in this area. I am able to get the Ant script to run to document simple (Cairngorm, AS3CoreLib) projects and generate the toplevel_classes.xml but when it comes to trying to document the entire Flex framework I am at a loss.

Unfortunately my programming skills are in the early days, so I am sorry to ask for this help, but if you are able to give me any pointers or suggestions about what I need to do to generate the toplevel_classes.xml documenation I would be most obliged. An example Ant build file with the required settings would be excellent, or even better a copy of the toplevel_classes.xml for the flex3 sdk ;-)

Best regards

Austin

[Mathieu]

Hi,

Thanks for your help about ASDOC. I've succesfully get the toplevel_classes.xml from a personal project. You wrote that you have converted it to XMI format to import it in an UML editor. Can you explain how you have made it ?

Thanks

[darnpunk]

Hi there,

It is interesting to see that you mentioned converting the XML to XMI for importing to UML editor. Can you explain how you did it? Is this possible with a tool?

[netjam]

Hello Rob,

Really nice post. It would be really interesting to learn the XML to XMI conversion. Is there any help you can provide on this? Thank you.