Using ASDoc with ANT and Eclipse

Using ASDoc can be fairly confusing at first since there is not much documentation out there. I will go over several things I learned from using it with ANT in Eclipse. I will not cover the syntax of in-code comments as that part is documented well; I will cover the specifics of using ASDoc with ANT build scripts. There are a couple different ways to document code with ASDoc depending on how much of it needs to be documented and if any of it needs to be hidden. Documenting it all by setting ASDoc down in the root source folder is pretty straightforward. Picking and choosing which classes get documented can be a little more subtle.

documenting all classes

First I will create a properties file outside the build file to reduce clutter when specifying individual class names later on. The contents of build.properties:

flex3dir = C:/tools/sdk/flex_sdk_3
flex3bindir = ${flex3dir}/bin
asdoc = ${flex3bindir}/asdoc.exe
classesdir = ${basedir}/src
docsdir = ${basedir}/docs
title = Test ASDoc API

This assumes that the root of your source code is in the src folder located inside your base directory which is declared in the build.xml file and your flex sdk is located in C:/tools/sdk/flex_sdk_3 (Which is not the default directory so it will need to be changed). Contents of build.xml:

<project name="TestASDoc" basedir=".">
    <property file="build.properties"/>
        <target name="generateDocs">
		<delete includeemptydirs="true">
			<fileset dir="${docsdir}" includes="**/*" />
		</delete>
		<exec executable="${asdoc}" spawn="true">
			<arg line="-doc-sources '${classesdir}'
				-output '${docsdir}'
				-main-title '${title}'
				-window-title '${title}'
				-footer 'www.website.com'"/>
		</exec>
	</target>
</project>

This code will document all classes and namespaces in the "src" folder with the given window title and footer.

documenting limited classes

There are two ways to go about this depending on the amount of classes we need to document compared to the total number of classes. We can directly tell ASDoc which classes to document by specifying each one, or we can go about documenting all classes as above and then tell ASDoc to exclude certain classes. I will cover the former first.

First we need to make a couple changes to the build.xml file. It should look like this:

<project name="TestASDoc" basedir=".">
	<property file="build.properties"/>
	<target name="generateDocs">
		<delete includeemptydirs="true">
			<fileset dir="${docsdir}" includes="**/*" />
		</delete>
		<exec executable="${asdoc}" spawn="true">
			<arg line="-source-path ‘${classesdir}’
				-doc-classes ‘${classes}’
				-output ‘${docsdir}’
				-main-title ‘${title}’
				-window-title ‘${title}’
				-footer ‘www.website.com’”/>
		</exec>
	</target>
</project>

We removed the -doc-sources command and added -source-path with the same parameter. Then we added -doc-classes which is what will do the work of selecting classes to document. Now we have to declare those classes in build.properties. Our example directory is set up like this:

We only want to document Ball.as and Throw.as. So, we need to add those two classes to a variable named “classes” in build.properties. Here is the updated code:

flex3dir = C:/tools/sdk/flex_sdk_3
flex3bindir = ${flex3dir}/bin
asdoc = ${flex3bindir}/asdoc.exe
classesdir = ${basedir}/src
docsdir = ${basedir}/docs
title = Test ASDoc API
classes = com.test.Ball’ ‘com.test.actions.Throw

Note the single quotes and single space in between the classes, this is integral to getting each class documented and is the trickiest part of this procedure.

To exclude Ball.as and Throw.as and document the rest we can use the same build.properties file and just change build.xml to:

<project name="TestASDoc" basedir=".">
	<property file="build.properties"/>
	<target name="generateDocs">
		<delete includeemptydirs="true">
			<fileset dir="${docsdir}" includes="**/*" />
		</delete>
		<exec executable="${asdoc}" spawn="true">
			<arg line="-doc-sources ‘${classesdir}’
				-exclude-classes ‘${classes}’
				-output ‘${docsdir}’
				-main-title ‘${title}’
				-window-title ‘${title}’
				-footer ‘www.website.com’”/>
		</exec>
	</target>
</project>

We use the -doc-sources command once again. Paired with the -exclude-classes command, we succeed in documenting only Bounce.as and Kick.as.