ASDoc aint easy...

I think that is an understatement. The majority of the flash community (my opinion) doesn't work directly with command-line compilers. In fact I think it is safe to say that most of us work indirectly with command-line compilers. That is why we use an Integrated Development Environment (IDE) like the Adobe Flash IDE, Flex Builder, Eclipse or FlashDevelop.

Having said that I do feel we need to be grateful here as ASDoc in particular is one of Adobe's internal tools that have surfaced as being quite popular in the flash community. All the others available were either too expensive or didn't quite work. Only problem is, everyone wants to use it but there seem to be little documentation on it which makes loads of people lose their hair way too early. Unless you use Flex Builder, this is not a straight forward process (or so I've heard). 

The tool

Very cool stuff from Adobe. It's no secret we can use their nifty tool ASDoc to generate our own project class documentation, but up till now the support for MXML has been a little on the thin side. That is until now. There isn't much info on this yet but in my quest for perfect class documentation, and that means including MXML files, I have found a functional and design specification for ASDoc in MXML. You gotta love open source. A little searching showed the new ASDoc compiler is available in the new release of Flex 4.  So I download a nightly build for free. Nice. Write an Ant script. Run it. Errors. Not so nice.

Getting it to work

If you are using the Flash IDE or FlashDevelop this section is probably not for you. Only because I don't know how to run Ant scripts using these IDEs. Not even sure if you can. I use Ant to run command-line compilers as it makes things a lot easier. You can download Ant for free but I use it through my IDE which is Eclipse, so won't be able to assist in running a script standalone.

At first I managed to get it to generate without too much difficulties. The log file with errors is quite descriptive of what the problem is. The compiler errors on the other hand is like a politician, artfully vague. So after making sure I don't have any & signs lurking in my comments and my html tags are closed, I was able to generate some cool docs. Only problem was it didn't include any MXML files. Which kinda defeats the purpose.

MXML problem

I had a problem with my MXML files not being found. The error was something like Error: Definition <classname> could not be found. I should probably add that I instantiated my MXML inside an Actionscript class. Another error I got was Error: Type was not found or was not a compile-time constant: <classname>. The Ant script I used looked like this extract (will provide the working version at the end):

<target name="compile">
	<echo message="Generating new docs..." />
	<exec executable="${asdoc.dir}" failonerror="true" >
		<arg line="-doc-sources ${srcpath.dir}" />
		<arg line="-window-title "${title}"" />
		<arg line="-output ${output.dir}" />
		<arg line="-external-library-path=${basedir}/swc" />
		<arg line="-left-frameset-width 300" />
	</exec>
</target>

After doing some searching I found that I need to add the argument -source-path to tell the ASDoc compiler to include my source folder to the path that will be searched. So I did and then I got the obscure error that looked a little something like this:

     [echo] Generating new docs...
     [exec] Loading configuration file C:\flex_sdk_4.0.0.3988\frameworks\flex-config.xml
     [exec] java.lang.StringIndexOutOfBoundsException: String index out of range: -28

After doing some more digging I found the manifest file. The manifest file is an XML file that lists the full package of your cusotm MXML components. This will be used by the compiler should it come across a custom component it can't find. Here is what the manifest file looks like:

<?xml version="1.0"?>
<componentPackage>
           <component id="ClassName" class="com.full.package.ClassName" />
</componentPackage>

All we need to do now is tell the ASDoc compiler to use this manifest file and we do it like so:

<arg line="-namespace comp ${basedir}\ant\Manifest.xml"/>
<arg line="-doc-namespaces comp"/>

Complete ant script

You will have to update the example Ant script properties to suit your environment:

<?xml version="1.0" encoding="UTF-8"?>
<project name="asdoc" default="main" basedir="..">

    <property name="title" value="Project Title" />
	<property name="flexsdk.dir" location="C:\flex_sdk_4.0.0.3988" />
	<property name="asdoc.dir" location="${flexsdk.dir}\bin\asdoc.exe" />
	<property name="srcpath.dir" location="${basedir}\src" />
	<property name="output.dir" location="${basedir}\html_docs" />
	<property name="externallib.dir" location="${basedir}/swc" />
	<property name="manifest.file" location="${basedir}\ant\Manifest.xml" />

	<target name="clean">
		<echo message="Removing old docs folder..." />
		<delete dir="${output.dir}" failOnError="false" includeEmptyDirs="true"/>
		<mkdir dir="${output.dir}"/>
	</target>	

	<target name="compile">
		<echo message="Generating new docs..." />
		<exec executable="${asdoc.dir}" failonerror="true">
			<arg line="-source-path ${srcpath.dir}"/>
			<arg line="-namespace comp ${manifest.file}"/>
			<arg line="-doc-namespaces comp"/>
			<arg line="-window-title ${title}"/>
			<arg line="-output ${output.dir}"/>
			<arg line="-external-library-path=${externallib.dir}" />
			<arg line="-left-frameset-width 300" />
		</exec>
	</target>
	
	<target name="main" depends="clean,compile" description="Complete build of ASDocs"/>
	
</project>

All that is required now is to run it. To run the Ant script in Eclipse do the following:

• Window -> Show view -> Ant
• In the Ant view click on the little icon with the ant and plus sign
• Select the Ant script and click on the green play button

Resources

• ASDoc help