Compiling documentation with Ant and asdoc

Posted 21 August 2009 by Russ in Adobe Flex. Tags: Ant, asdoc.

Documenting code for asdoc

Documenting your code for asdoc is easy and there’s plenty of help available on this and I’d suggest starting with the Flex help.

Installing Ant

You can run asdoc from the command line but I found it much easier to install Ant in Flex Builder, which is as simple as this:

1. In Flex Builder go to Help > Software Updates > Find and Install
2. Click on the option to Search for new features to install
3. Make sure The Eclipse Project Updates is selected and then hit Finish
4. Expand the tree Eclipse 3.3.2 or newer, select Eclipse Java Development Tools and install
5. Restart Flex Builder and then go to Window > Other Views
6. Expand the Ant directory, click on the Ant icon and hit OK
7. You should now have an Ant panel, though the position of it may vary according to your perspective settings (mine is alongside Console at the bottom)

Create a symbolic link to asdoc

A copy of asdoc lives in each SDK directory so if you’re using 3.3.0, you’ll find it at /Applications/Adobe Flex Builder 3/sdks/3.3.0/bin/asdoc. We’ll be using Ant to build our documentation and giving it the path to the asdocs progrm but asdoc has a problem with spaces in pathnames, which although not a problem on Windows, is a pain on Mac as the path above has spaces in it and attempting to use this in Ant throws an error. I first tried the approach in this excellent article but still had the same problem so instead I created a symbolic link (shortcut) to asdoc in my hard disc root.

You can do this in a number of ways, the easiest of which is perhaps using this little plugin.

Once you’ve created your symobolic link, name it something obvious with no funny characters. Mine is flex-sdk-330. When you click on this symbolic link in the Finder you’ll see the contents of the 3.3.0 directory and inside that, the bin directory and asdoc program. So far so good.

Create the Ant files

To compile our documentation we need an XML file called build.xml and a properties file called build.properties so we create these in the root of our Flex Project. If Ant has installed properly you’ll probably see a little Ant icon on your file.

The build.properties file

The properties file contains a set of values that the XML file will use.

We start with a reference to the symbolic link we created earlier.

# Path to SDK
SDK_PATH = /flex-sdk-330

Then we add something very important: the path to the Flash player we are using for this project. Setting the target player in Flex Builder will only tell the Flex compiler to target a specific player but Ant won’t know about that so if you’re targetting version 10, make sure you reference the version 10 player here.

One problem you may find if you don’t do this is you end up with compile errors. One that I got tripped up by was an error to do with the FileReference class. This was changed in Flash player 10 to include the ability to load files from the user’s environment without the need to load them to a server first. If you get errors to do with FileReference, make sure you have this set correctly.

# Path to target Flash Player library (relative to the SDK_PATH
PLAYER_PATH = /frameworks/libs/player/10/playerglobal.swc

The next property is where you reference any SWC library files your project uses. In the example I’m providing for download below I’m not including any so this is just blank:

# Paths to libraries to include
# LIBRARIES = ./libs/SomeLibrary.swc ./libs/SomeOtherLibrary.swc
LIBRARIES = 

Next comes the path the the source files for the project, which are typically in the src directory:

# Source files
SOURCE = ./src

The next two settings are used for the documentation output – the TITLE appears in the title of the documents and the FOOTER text appears at the bottom of each page.

# Title for the documentation
TITLE = Compiling Documentation with Ant and asdoc

# Text to add to the footer of each page
FOOTER = Compiled using Ant and asdoc (build.xml and build.properties)

Finally we have a location to output our documentation to, in this case a directory called docs in the Flex Project:

# Output location
OUTPUT_PATH = ./docs

The build.xml file

Now we have our properties file we can go ahead and use them in our XML file. The properties file is referenced right at the outset and then we include a path to the flexTasks.jar file (note the properties throughout this file are called in as follows ${PROPERTY}).

<?xml version="1.0" encoding="utf-8"?>
<project name="Compiling Documentation with Ant and asdoc" default="Clean and Build" basedir=".">

	<property file="./build.properties" />

	<!-- Path to Flex Ant Tasks (info at http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks) -->
	<taskdef resource="flexTasks.tasks" classpath="${SDK_PATH}/ant/lib/flexTasks.jar" />

Next we have our default Ant task which simply calls the two other tasks in the file Clean, and Build.

	<target name="Clean and Build" description="Calls the Clean and Build tasks">
		<antcall target="Clean" description="Calls the Clean task" />
		<antcall target="Build" description="Calls the Build task" />
	</target>

This is followed by a simple task that deletes the existing documentation if there is any:

	<target name="Clean" description="Deletes the existing documentation and recreates the directory">
		<delete dir="${OUTPUT_PATH}" failOnError="true" includeEmptyDirs="true" />
		<mkdir dir="${OUTPUT_PATH}"/>
		<echo>Clean task completed successfully</echo>
	</target>

And finally the task that will build our documentation:

	<target name="Build" description="Builds the documentation">
		<exec executable="${SDK_PATH}/bin/asdoc" failonerror="true">
			<arg line="-load-config ${SDK_PATH}/frameworks/flex-config.xml" />
			<arg line="-doc-sources ${SOURCE}" />
			<arg line="-source-path ${SOURCE}" />
			<arg line="-external-library-path ${SDK_PATH}/${PLAYER_PATH}" />
			<arg line="-include-libraries ${LIBRARIES}" />
			<arg line="-window-title '${TITLE}'" />
			<arg line="-footer '${FOOTER}'" />
			<arg line="-output ${OUTPUT_PATH}"/>
		</exec>
		<echo>Build taks completed successfully</echo>
	</target>

</project>

Compile the documentation

Now everything is set up we simply need to drag the build.xml file onto the Ant panel and double-click on it or hit the Play button in the Ant panel.

If everything is set up correctly we should get a couple of confirmation messages in the Console panel and the documentation will be created in a /docs directory in the root of our Flex Project.

Download an example project

To see an example in action you can download and edit the source code here. This should work if you follow the steps above but obviously can be modified as required.