What is ANT?
You can do about anyting with ANT by creating an ANT Script (xml) that tells ANT what to do. ANT can do anyting with files (copy, paste, move, duplicate, extract zip files, etc) and with ANT you can execute applications which you would normally use through the command line (or Terminal on a Mac).

ASDoc ANT Script
Ok, back to the ASDoc ant script. Click “File -> New -> File” and create a file called asdocbuild.xml. Paste this code into the xml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?xml version="1.0" encoding="utf-8"?>
<project name="ASDoc build" default="createdocs">
 
	<property file="asdoc.properties"/>
 
	<target name="createdocs">
		<exec executable="${asdoc.dir}/asdoc" failonerror="true">
			<arg line="-doc-sources 'src/'"/>
			<arg line="-main-title 'Undercore, a Flash and Flex development framework'"/>
			<arg line="-window-title 'Undercore'"/>
			<arg line="-output 'docs'"/>
		</exec>
	</target>
</project>

Some explanation of what happens in the xml file above: Obviously it’s an xml file (line 1).  The project tag defines the projectname of the build and the default target to execute, in this case the target on line 5 called createdocs. This node contains an exec node which tells ANT to execute a command line statement with the arguments contained in the exec tag. This is the actual asdoc execution.

Before it executes any of the targets, it loads a properties file. You can define variables in a properties file, such as ${asdoc.dir} which is defined as asdoc.dir in the property file. This is the properties file content:

asdoc.dir=/Applications/Adobe Flex Builder 3 Plug-in/sdks/3.2.0/bin

Just create a file named asdoc.properties and paste the code above in it. Your project should look something like this:

Now right-click the asdocbuild.xml file and choose Run As -> Ant Build. Your documentation’s being created.

To conveniently call the asdoc.exe command from every folder on your system you have to add the path to the folder asdoc.exe is in to the PATH system variable. Here’s how: Go to your Control Panel and click System. Go to the Advanced tab and click Environment Variables. In the System Variables list locate the Path variable. If it doesn’t exist create it. Doubleclick the variable to edit the value and add the location of your Flex bin folder, in my case it is: “d:\Program Files\Adobe\Flex Builder 2\Flex SDK 2\bin”. Don’t replace any of the other values in the variable, the value of the variable is semicolon-separated, so just add the path at the end of the value. Now click OK OK and reboot. After the reboot you should be able to just enter this in the command line: c:\asdoc, and ASDoc should respond with a beautiful error.

I hate typing in a command prompt (I don’t like typing at all), so I create a batch file to call ASDoc so I can create and recreate my documentation again and again. I place the batch file in the root of my project, so here’s what my project looks like:

1

asdoc -source-path . -doc-sources . -output asdoc -external-library-path=lib -main-title "My work API documentation" -window-title "My work API documentation"

Some explanation about the switches in this command:

• asdoc: this calls the asdoc command
• -source-path: Enter a dot to tell ASDoc that the current folder is the source path
• -doc-sources: Enter a dot to tell ASDoc to document all of the sources in the current Folder
• -output asdoc: This is the name of the Folder in which the documentation will be generated
• -external-library-path: If you use external swc’s, ASDoc wants to know about them, so enter the Folder in which they are located. In my project above I’ve used Away3D and Tweener, they are located in the lib folder
• -main-title: The title at the top of the document
• -window-title: The title the browser window displays

Note that the -external-library-path is an undocumented switch, I’ve spent an hour to get ASDoc to work properly with external libraries. Using -library-path won’t work, you’ll replace the Flex Framework by doing that, so ASDoc will say something like “Hey, what’s a UIComponent?”.

Everything should work fine, but with ASDoc you’re never sure. Just run the batch file from the command line and see what happens.

By the way: don’t use unsupported tags in your code. The @description tag for instance is not supported, which will result in ASDoc throwing a useless xml parser error.

Good luck, you’re on your own now…