If you’re starting a Flex project and are considering publishing your documentaton with ASDoc then I cannot stress enough that there are a few things you need to consider BEFORE you start your development. I know because I’ve just been through the hell that is trying to compile with a large and complicated project. Here’s some of the things I’ve learnt …

Use ANT and a build-file to generate the compiler options and launch ASDoc.exe. This post is worth reading for the ANT script. This post for instructions on how to install ANT in Flex Builder 3. Don’t bother using any of the GUI tools out there for generating the compiler options. I tried a few of them and the best method was definitely ANT and a decent build script.

Always include the -source-path property in your compiler options even if your build file is in your source folder. If you have used ANT then you’ll probably need to add a key/value pair to the build.properties file and add then add the compiler property in the build.xml file.

The best place for ASDoc help is the Adobe Flex 3 help documentation which can also be viewed online here. You’ll find the ASDoc help in the Application Development section.

Do not use linked libraries in your Flex project. If you want to link to 3rd party frameworks then try and get them as SWC files or create a Flex library project and publish a SWC to include in your project. ASDoc likes SWC files because it doesn’t publish them. 3rd party utility classes will probably have their own published ASDoc files that you can distribute to your client. If you need to publish 3rd party classes then copy and paste them into your source folder and add the source paths as normal. I’m not going into the details of how to add paths … you should read the previous posts on this.

Now this is important and will catch you out if you leave your ASDoc adventure until after your development process … DO NOT embed assets in your classes. This sounds nuts but here’s why …

If you have a class that is in a package like com.project.view.components and your assets folder is in the root of your source folder then the following Embed tag …
[Embed (source="assets/background.png")]
… will compile fine in Flex as it will try to find the file from the scope of your source folder but in ASDoc it assumes the file is com/project/view/components/assets. I found a solution that turns out to be quite a good technique for managing your assets in a Flex project regardless of whether you intend to publish docs. Create an Assets class and put it in the same folder as your assets. Alternatively move your assets into the package folder of your Assets class. Here’s an example of an Assets Singleton that you can use to keep all your Embed references together.

Now, you can reference your assets from anywhere like so …

myImage.source = Assets.getInstance().image1;

I’m guessing there are loads of other quirks I haven’t spotted and there are most likely to be solutions to the problems that I have found. If any one has any other tips and tricks then please leave a comment. In the meantime I hope this helps someone and saves some precious time.