Flex Library SWC and AS Doc generation - Tips & Tricks

This is just an addition to the already many existing tips on the web. These are few tips that helped me get resolved some of ASDoc errors.

1) CSS – All the paths to images/swf/external assets should be resolved to absolute. Relative paths are recognised by the asdoc/compc tools.
2) build.xml spaces – Sometimes the spaces in the file paths are not resolved; enclose them in quotes.
3) external-library-path – To give you understanding, whatever libraries referenced here are excluded from compiling into swf/asdoc/swc.
4) When creating a library SWC ensure to mention source-path argument, all the files you are referencing should be in the source path. Else the external assets are recognised by the compc.

AS Doc Generation with Ant

Ant has become my favourite tool again after started using it in flex. I remember using while I was working on java stuff. Now I start to compile my flex apps and libraries with Ant, though I use Flex builder. I just ignore the flex builder problems/errors and look up for the Ant tasks console. Because, flex builder can ignore few errors/warnings out of the project scope. Compiling with Ant/command-line is stricter and helps your code keep clean. Here I am going to describe primarily about how to generate AS docs for a flex project, it can be a library project as well. Though, I focus on the Ant build tool, pretty much the commands can be used on the command-line compiler also.

1) Install ANT in your flex builder. If you are not sure how to install, follow this link. http://www.adobe.com/devnet/flex/articles/flex_ant_pt1.html

http://www.adobe.com/devnet/flex/articles/flex_ant_pt2.html I recommend you to go through both the parts of the tutorial as it contains valuable information as how to install ANT and get started.

2) If you are ready with ANT, you should be having two file in the root directory of your project.

a. build.xml

b. build.properties

My build.properties file typically looks like this:

# change this to your Flex SDK directory path

FLEX_HOME=C:/Program Files/Adobe/Flex Builder 3/sdks/3.3.0

# defines the Flex framework files location

FLEX_FRAMEWORK = ${FLEX_HOME}/frameworks/libs

# this points to your project's src directory

# {$basedir} is a default variable that can be used in any Ant script

# and it points to the project's root folder [ Flex_Ant_Tasks ] in this case

SRC_DIR =${basedir}/src

# points to the project's libs directory

LIBS_DIR =${basedir}/libs

# this is the folder we want to publish the swf to

DEPLOY_DIR = ${basedir}/bin-release

#this property defines the doc directory, which will store your created ASDocs later in the article

DOC_DIR =${basedir}/asdocs

# defines the title for your ASDoc pages

DOC_TITLE ="Project Documentation"

# defines the footer for your ASDoc pages

DOC_FOOTER = "Copyright© 2009"

# points to your asdoc.exe for ASDoc creation later

asdoc.exe =${FLEX_HOME}/bin/asdoc.exe

Note this parameter in your build.properties file for storing your AS doc.:

#this property defines the doc directory, which will store your created ASDocs later in the article

DOC_DIR = ${basedir}/asdocs

3) Now in your build.xml , add this bit to ensure that you delete the existing directory and create a new directory for AS docs:

<target name="Create AS Doc DIR">

<delete dir="${DOC_DIR}" />

<mkdir dir="${DOC_DIR}" />

</target>

4) Here comes the main bit code for AS doc generation:

<target name="Create AS Docs" depends="Create AS Doc DIR">

<exec executable="${asdoc.exe}" failonerror="false">

<arg line='-source-path ${SRC_DIR}' />

<arg line='-external-library-path ${LIBS_DIR}' />

<arg line='-doc-classes MyFrameworkClasses' />

<arg line='-warn-level-not-supported=false'/>

<arg line='-main-title ${DOC_TITLE}' />

<arg line='-window-title ${DOC_TITLE}' />

<arg line='-footer ${DOC_FOOTER}' />

<arg line='-output ${DOC_DIR}' />

<arg line='-strict=false' />

</exec>

</target>

The <exec> sets the asdoc.exe file to run AS doc engine from the flex builder directory. This token should have been initialized in the build.properties file. Look into the build.properties file, if not it should be like this:

# points to your asdoc.exe for ASDoc creation later

asdoc.exe =${FLEX_HOME}/bin/asdoc.exe

<arg line='-source-path ${SRC_DIR}' /> - Set the source-path with src directory of your project

<arg line='-external-library-path ${LIBS_DIR}' /> - This is where you set all your external libraries, which are compiled into SWC. AS Docs are not generated for these libraries.

<arg line='-doc-classes MyProjectClasses' /> -(There’s also an alternative command to achieve this.) This line implies which classes should you generate AS doc for. This is the trickier bit and this is how Adobe compiles the framework classes. MyProjectClasses.as file is a dummy class that stores the references for the classes you want to generate. It can be something like this:

/**

* It is a good practice to maintain this class at the root of src directory.

* MyProjectClasses.as

*

*/

package

{

/**

* @private

*/

internal class IBFrameworkClasses

{

import com.classA; classA;

import com.classB; classB;

import com.classC; classC;

import com.classD; classD;

}

}

Specify, all of your classes you want to document here. This seems to be frightening task, but I suggest this approach as it is a onetime task and really helps you maintain all your classes.

Ok, you are not comfortable!! Take this approach...

<arg line='-doc-sources ${SRC_DIR}' /> - This command is simple and straight forward, it documents all the classes in the src directory. I know that is what you want!!! In this approach, ensure that all the class libraries are supplies in SWC format, else you would run into creating documentation for all n number of classes.

Next few commands should be pretty straight forward, labelling the documentation and storing the AS docs in the DOC_DIR.