When creating a new application on Flash Builder 4 it’s a good dev practice to write documentation for it. Having a well organized and up to date documentation for each project can be helpful when introducing a new developer to the team, and when wrapping up a project for a client. It has also helped me multiple times when I have been working on big applications with multiple custom classes.
Keeping up and creating a well structured documentation can sometimes be just as time-consuming as writing the application itself. That is why I use the ANT plugin for Adobe® Flash Builder 4.5. It can generate documentation structure similar to the one used for the Adobe Flex Language Reference (if you have used Adobe’s online Help/Docs/Manual), which makes it a great ASDoc tool to have when making project documentation.
For clarity, I have split this post into three parts. Part one focuses on the Ant plugin installation for Adobe® Flash Builder 4.5 and how to setup an Ant build-file.xml for your documentation project. Part 2 is the actual project documentation process for Ant on standalone Flash Fuilder 4.5. Common Glossary and output. Part 3 will cover the documentation template customization.
Good to know:
ASDoc: A command-line tool for generating API language reference documentation for your project based on specific comments that exist inside your classes.
ANT: Ant (Another Neat Tool) is a scripting tool plugin for standalone Flash Builder 4. It helps developers by automating many tasks regarding application code management. Link to ANT Manual: http://ant.apache.org/manual/index.html
build file: This is an XML file used by Ant. Consists of tags with XML-based syntax which list targets and dependencies in a script file, which is invoked from a command prompt or (as in this case) by the Ant plugin for stndalone Flash Builder 4.5.
Adobe® Flash Builder 4: Currently Adobe® Flash® Builder® 4.5 software, formerly Adobe Flex® Builder®, is an Eclipse™ based development tool for rapidly building expressive mobile, web, and desktop applications using ActionScript® and the open source Flex framework. – Adobe Website / Flash Builder 4.5
1. Ant on Flash Builder.
If you already have integrated Ant with Flash Builder skip this part.
1. Paste URL below in the ‘Work with:’ field. http://download.eclipse.org/releases/galileo
2. Narrow your search by typing ‘Eclipse Java’.
3. Select the Eclipse Java Development Tools check box in the list.
4. Finish the installation process and restart Flash Builder.
If your installation was successful you will see the the ANT view in Flash Builder’s ‘Other Views’ menu.
2. Generating ASDocs with Ant.
Once Ant is installed on Flash Builder you can go in FB’s ‘External Tools Configurations’ and create a new Ant Build configuration. To get to the ‘External Tools Configurations’ dialog select Run>External Tools>External Tools Configurations.
Next select the Ant Build configuration type and click on the ‘New’ button (top left) to create a new Ant configuration.
You can give your new Ant configuration a new name by typing in the ‘Name’ field in the configuration settings dialog.
The next step is to create a custom build file for your project and define its path in the configuration settings.
Ant’s build-files are written in XML. Each build-file must contain one project and at least one (default) target. Here is an example of a generic build-file. Tag explanations can be found here.
<?xml version="1.0"?> <project name="Flex Ant Tasks" default="main" basedir="."> <target name="main" depends="clean, jar" /> <target name="compile"> <mkdir dir="classes" /> <javac srcdir="src" destdir="classes"/> </target> <target name="jar" depends="compile"> <jar destfile="lib/flexTasks.jar"> <fileset dir="." includes="flexTasks.tasks" /> <fileset dir="classes" includes="**/*.class"/> <fileset dir="." includes="templates/**" /> </jar> </target> <target name="clean"> <delete dir="classes" /> <delete file="lib/flexTasks.jar" /> <delete> <fileset dir="src" includes="**/*~" defaultexcludes="false" /> </delete> </target> <!-- - - - - - - - - - - - - - - - - - target: name - - - - - - - - - - - - - - - - - --> <target name="generateDocs" description="Generate Project Documentation"> <echo>Generating Docs</echo> <exec executable="/Applications/Adobe Flash Builder 4/sdks/4.0.0/bin/asdoc" failOnError="true"> <arg line="-source-path '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/src' '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/libs'"/> <arg line="-doc-sources '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/src'"/> <arg line="-external-library-path '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/libs'"/> <arg line="-exclude-classes 'com.rng.data.customClass' 'com.rng.data.customClass2'"/> <arg line="-templates-path '/Applications/Adobe Flash Builder 4/sdks/4.0.0/asdoc/CM_templates'"/> <arg line="-main-title 'Project Documentation Title'"/> <arg line="-output '/Users/YourUsername/Documents/Adobe Flash Builder 4/YourDocumentedProject/outputFile'"/> </exec> </target> </project>
Depending on the complexity of the project you need to document, you might have to include other related projects and/or their resources. The arguments (lines 31-37 above) would give you a good example of how to do that and more.
Once you have customized your build-file remember the location where you saved it and navigate or type in the path to the file in your new Ant project’s settings view. (image below)
Now save your configuration settings and click on the ‘Targets’ tab in your configuration dialog.
Save your settings and you done with Part 1 !
If you already have written out any ASDoc comments inside your Flash Builder project work-file you can click ‘Run’ (bottom right of Configurations window). Pressing ‘Run’ will start documentation generation and you can follow its progress in the ASDoc progress console.
Next Week, Part 2 writing ASDoc Comments, Common Errors, and Exporting.