May 11, 2009 rory 0
Compiling Relevant Classes in ASDOC
I have spent some time getting asdocs to work the way i want t to. There is not much information on the net about this tool yet and so i thought it might be nice to share what i have learnt.
The task i was assigned was to generate html documentation for any given project, thats pretty simple. The twist was to only document the classes relevant to the project. With a library full of source and swc format classes this became quit a struggle. My solution was to make an ant script that performs the following functions.
Create a manifest of all classes in the lib path
The classes in our the lib directory are in source format (they are all *.as files). These classes are not important to the documentation, we do not need to generate asdocs for the Tweener library for example, as this documentation already exists elsewhere. By default asdocs will document any class which has been used in a project. If we use a Tweener class, asdocs will document this class being used along with all the components of the tweener library that this tweener class references, this is a lot of irrelevant information. For this reason i generate a list of all the classes in the lib directory, this list will be passed to the asdoc tool which will exclude them from documentation. The ant code is as follows;
<property name="libraryFolder" value="lib"/>
<target name="manifest">
<fileset id="sources" dir="${libraryFolder}">
<include name="**/*.as"/>
</fileset>
<pathconvert property="classes" pathsep=" " refid="sources">
<chainedmapper>
<globmapper from="${basedir}/${libraryFolder}/*" to="*"/>
<mapper type="package" from="*.as" to="*"/>
</chainedmapper>
</pathconvert>
<echo message="manifest = ${classes}"/>
</target>
Here we are generating a string of classes which include their package paths, for example;
Here you can see the class Facade.as from the PureMVC framework, note that the file extension is omitted. This string should be identical to the one inside the .as file after package with the addition of the class name. Make sure you do not start the string with lib.puremvc.as3… as this will not compile due to the fact that the sting does not match what is written in the class file itself.
Exclude the classes in the manifest
This is a simple task with one catch. Firstly the argument to the asdocs tool which excludes classes from compilation looks like this.
This argument uses the ‘classes’ property which is generated by the manifest target as the list of classes to exclude. The catch is that you have to set the ‘-source-path’ of asdocs to your lib folder otherwise asdoc will not be able to locate the source files.
Add swc locations to asdoc with ‘+=’
I encountered trouble with asdoc losing its default reference to the flex SDK when i assigned external libraries without the += syntax, particularly when i was experimenting with the compc tool. Just remember that you must specify the locations of all swc files used by your source and the source in your library. This should be done in this manner.
Here i am specify in the folder named ’swc’ in my base directory.
Use ‘-lenient’ compilation
In SDK 4.x asdoc supports the ‘-lenient’ tag, this tells asdocs to ignore badly formatted HTML, i found this to be a very useful addition. An error log is created when errors are encountered so you can fix them should you choose to, asdocs will tell you the location.
Set asdocs ‘-doc-classes’ to the main file
The slightly ambiguous ‘-doc-classes’ tag is the tag you should use to generate documentation for all the classes used in your project. You only have to specify one class and asdocs will trawl through the project hierarchy from here documenting the classes you have used and ignoring those you have not. If you are using asdocs to write documentation for an application just point the ‘-doc-classes’ to the ‘Main.as’ file in your src folder. Otherwise if you are compiling a library of your work you have the option of listing the files you want to be compiled and using the ‘-doc-classes’ tag or simply using pointing ‘-doc-sources’ at the location of your “would be” library. Either way it is important to point ‘-source-path’ to your src folder just as we did fr the lib folder, again this is important as it matches the physical locations of source files to the locations they define in their package deceleration. My asdoc target looks like this,
<exec executable="${bin.dir}/asdoc" failonerror="true">
<arg line="-source-path ‘${basedir}/src’ ‘${basedir}/${libraryFolder}’"/>
<arg line="-doc-classes ‘${mainFileName}’ "/>
<arg line="-external-library-path+=lib"/>
<arg line="-external-library-path+=lib/swc"/>
<arg line="-external-library-path+=swc"/>
<arg line="-exclude-classes ${classes}"/>
<arg line="-lenient"/>
<arg line="-main-title ‘ASDocs loves socks’"/>
<arg line="-window-title ‘ASDocs Window’"/>
<arg line="-output ‘${Output.dir}’"/>
</exec>
</target>
Here is a working buildfile for the last project i used this method on, to use it you should only have to set the properties at the top of the file and change the locations of the swc library folders in the asdoc target to be relavent to your project.
<!– location of FlexSDK –>
<property name="FlexSDK.dir" location="/Applications/Adobe Flex Builder 3/sdks/4.0.0.6449"/>
<!– location of ASDocs folder–>
<property name="bin.dir" location="${FlexSDK.dir}/bin"/>
<!–no spaces in output folder name CHOOSE NEW FOLDER OR FILES WILL BE OVERWRITEN–>
<property name="Output.dir" location="${basedir}/asdocs"/>
<!–Main file, this will become the root from which asdocs searches for files
, dont type the fileextension (.as or .mxml)–>
<property name="mainFileName" value="Main"/>
<!–the location of the lib folder relative to the project directory–>
<property name="libraryFolder" value="lib"/>
<!–paths to folder containing swc used in the project, again relative to the project directory–>
<property name="swcLibraryPaths" value="’${basedir}/lib’ ‘${basedir}/lib/swc’ ‘${basedir}/swc’"/>
<!– Main –>
<target name="main" depends="clean,manifest,asdocme" description="full build of asdocs"/>
<!–Deletes the output dir if it already exists and then creates a new one–>
<target name="clean">
<delete dir="${Output.dir}" failOnError="false" includeEmptyDirs="true"/>
<mkdir dir="${Output.dir}"/>
</target>
<!–
Creates a manifest of the lib file, all files found in theis dir are to be excuded from the asdocs
–>
<target name="manifest">
<fileset id="sources" dir="${libraryFolder}">
<include name="**/*.as"/>
</fileset>
<pathconvert property="classes" pathsep=" " refid="sources">
<chainedmapper>
<globmapper from="${basedir}/${libraryFolder}/*" to="*"/>
<mapper type="package" from="*.as" to="*"/>
</chainedmapper>
</pathconvert>
<echo message="manifest = ${classes}"/>
</target>
<target name="asdocme">
<exec executable="${bin.dir}/asdoc" failonerror="true">
<arg line="-source-path ‘${basedir}/src’ ‘${basedir}/${libraryFolder}’"/>
<arg line="-doc-classes ‘${mainFileName}’ "/>
<arg line="-external-library-path+=lib"/>
<arg line="-external-library-path+=lib/swc"/>
<arg line="-external-library-path+=swc"/>
<arg line="-exclude-classes ${classes}"/>
<arg line="-lenient"/>
<arg line="-main-title ‘ASDocs loves socks’"/>
<arg line="-window-title ‘ASDocs Window’"/>
<arg line="-output ‘${Output.dir}’"/>
</exec>
</target>
</project>
