ActionScript Doc (ASDoc) is a utility that ships with the Flex 3 SDK that generates documentation based on ActionScript code; its very similar to JDoc and JSDoc for Java and JavaScript. While ASDoc does have many handy features, one major feature it lacks is the ability to limit generated documentation to a single directory/package of classes. Here is Adobe’s ASDoc command line guide.
ASDoc supports excludes only by class name. You can use the -doc-sources command line option to specify a single sub directory/package, but then ASDoc will follow dependencies and generate documentation for those. There is an -exclude-dependencies command line option, but you can’t use it in conjunction with -doc-sources. There is also a -doc-classes, but exclude dependencies seems to have no effect.
The solution then is to specifically exclude all classes, by individual name. This would be too tedious to perform by hand, and wouldn’t be sustainable for development in teams.
I found a great article named Compiling Relevant Class in ASDoc at AMP-London.com, that thoroughly explains how to exclude a single directory/package. However, I wanted a script that would exclude all directories/packages but my own from any project. So I reworked their ANT build script and came up with my own.
The following ANT buildscript, which is based heavily on the one the one mentioned above, runs ASDoc on all classes in a single package, and excludes all others.
<project name="AsDocTest" default="main" basedir=".">
<!-- The location of your FlexSDK directory -->
<property name="FlexSDK.dir" location="/Applications/Adobe Flex Builder 3/sdks/3.4.0"/>
<!-- The location of the ASDoc executable -->
<property name="bin.dir" location="${FlexSDK.dir}/bin"/>
<!-- The output directory for your documentation -->
<property name="output.dir" location="${basedir}/asdoc-output"/>
<!-- SWC file library path -->
<property name="swcLibraryPaths" value="libs"/>
<!-- The root to your class package directory -->
<property name="classesRoot" value="${basedir}/src"/>
<!-- the directory/package that you'd like to document, all others will be excluded -->
<property name="includedDirectory" value="/com/edge/" />
<!-- the ant description of this script -->
<target name="main" depends="clean,manifest,asdocme" description="full build of asdocs"/>
<!-- erase all previous asdoc output -->
<target name="clean">
<delete dir="${output.dir}" failOnError="false" includeEmptyDirs="true"/>
<mkdir dir="${output.dir}"/>
</target>
<target name="manifest">
<!-- Get the list of all files, exclude those that we wish to document (not a typo) -->
<fileset id="sources" dir="${basedir}/src">
<exclude name="**${includedDirectory}**"/>
</fileset>
<!-- convert the names of excldued classes to packages with class names -->
<pathconvert property="classes" pathsep=" " refid="sources">
<chainedmapper>
<globmapper from="${basedir}/src/*" to="*"/>
<mapper type="package" from="*.as" to="*"/>
</chainedmapper>
</pathconvert>
<!-- echo the exlcusions for debugging purposes -->
<echo message="manifest = ${classes}"/>
</target>
<!-- Run asdoc -->
<target name="asdocme">
<exec executable="${bin.dir}/asdoc" failonerror="true">
<!-- define the src path of the package directory -->
<arg line="-source-path '${basedir}/src'"/>
<!-- tell asdoc to include all sources under the root -->
<arg line="-doc-sources '${classesRoot}'"/>
<!-- define the output directory --->
<arg line="-output '${output.dir}'"/>
<!-- define the location of any swcs we're using -->
<arg line="-external-library-path=${swcLibraryPaths}"/>
<!-- define the excluded classes (all of them outside our included directory) -->
<arg line="--exclude-classes ${classes} --"/>
</exec>
</target>
</project>