Richard Leggett on New Media

This relates to using ASDoc to generate documentation for a Flex or AIR project that uses conditional compilation (read more and see tip at end).

Conditional Compilation

Just for some background, the Flex compiler supports what is known as conditional compilation. This allows you to set one or more constants via a compiler flag which is then made accessible from anywhere in your code. This may be a boolean, a string, a number and so on. Within your code you can read this value and switch between using certain methods, or execute blocks of code depending on the value it contains.

Follow up:

Here’s a quick example of some code that would read the constant injected by the compiler argument: -define+=CONFIG::DEBUG,true. I first run a static block of code only if it is set, and switch between two different methods that have the same name depending on whether it is true:

Code:

Generally the main reason to use this is to switch to toggle between creating a debug and release build. In Adobe AIR apps it is especially useful because you can insert things like webservice URLs depending on whether it’s a debug release, or a public release. Unlike web apps your initial configuration is generally compiled into your AIR application before it goes out to customers, so this offers a more dynamic way to customise the build for various environments without causing the programmer extra work (particularly if you are using ANT to compile your app).

ASDOC Fails

So when you go to generate your documentation, asdoc will probably choke on all of your conditionals, it doesn’t automatically get the compiler flags. The answer is to specify an additional flex/air-config.xml file which contains this information. Below is a sample ANT task that I use to generate my documentation for an AIR project that uses a Flex Library project and a bunch of external SWCs.

XML:

You should see in the property tag for “asdoc.config” I’ve added an extra AIR config file to the standard Flex SDK one, and this contains the following XML:

XML:

Now asdoc knows about our conditional compiler arg, and it should compile your documentation without problems.

Note: As an aside you may experience problems using conditional compilation in projects that use a Flex Library project. In this case the code inside the library project will not have access to your compiler flags, so you must also set the compiler flag for the library project itself.

Tip! If you are passing multiple values using -define in the compiler arguments field for your project make sure you do use SINGLE quotes (’ not “), and use = not +=, e.g. -define=CONFIG:debug_url="myURL” -define=CONFIG:release_url,"releaseURL". The docs only show double quotes being used but these will not allow multiple arguments due to escaping when in Flex Builder.