Creating ASDocs with ANT & Flash Builder Part 2. Writing AsDoc Comments.

2. Project Documentation Process for Ant on standalone Flash Fuilder 4.5. Common Glossary and Output.

This tutorial covers the documentation process for Ant on Adobe® Flash Builder 4.5. You will be presented with the most common ASDoc comments, their purpose and output in the generated documentation, and examples of documentation page templates and their customization process.

This is Part 2 of the Ant and Flash Builder 4.5 tutorial. If you have not yet installed and setup Ant on the standalone version of Flash Builder you can refer to Part 1. There you can get a step-by-step instruction on how to install and setup Ant.

Once you have installed and properly setup Ant on Flash Builder, it’s time to write some ASDoc comments in ActionScript® . When you generate the documentation later this code will be recognized by the Ant documentation tool and included in the generated project documentation. If you are thorough in your comments and update them along with the project’s development process, you will end up with one well written and detailed documentation and you will never forget what each class is used for.

Good to know:

•  Adobe’s help documentation is very detailed and shows all the best practices regarding the documentation process. It contains AsDoc comment examples and their formatting for all types of ActionScript classes.You can visit their documentation here.

This post is an addition which will help you instantly see what the result of the most common AsDoc comments looks like in the generated documentation. I will also cover a few mistakes that are common and if not minded can slow down your workflow or be the cause for errors which can go unnoticed by the documentation tool.

•  There is a list of HTML tags you can use to format you AsDoc comments. Bear in mind that this list of tags is limited, and that while in some sections of an AsDoc comment you can use them, in other places they are not accepted and can produce an error.
A summary of these HTML elements can be found here

•  There are two types of AsDoc comments: ActionScript comments and MXML comments.

Examples:

ActionScript comments are declared to start with  /**  character sequence and the end is declared by */. Read the example below:

[as3] /**
* The first sentence would be used to describe
* the class. Next sentences only show in the
* class’ detail view.
*/
[/as3]

An example of an AsDoc comment used to describe a class.
output:


Above is a list of classes and their short descriptions generated by the documentation tool. The short description on the right is the first sentence in your AsDoc comment for that class.

Below is a view of the same class’ Detail Page.

• Commenting Functions:

[as3]/**
* AsDoc comment for the

onViewClick

* method. HTML tags can be used
* here.
* @param evt Parameter tags are
* descriptions of the parameters this
* method can take in.
*/
override protected function onViewClick(evt:MouseEvent):void{
switch(evt.currentTarget){[/as3]

output:

Above is a snapshot of a Class Detail View page generated by the documentation tool.

MXML AsDoc comments:

[code]Comments start with the character.[/code]

This comment is placed after the xml ecoding declaration and does not require a CDATA block. You can use the same comment structure when you are commenting MXML components such as buttons, DataGrids, etc.

Here is an example of invalid implementation of the <h1>Header 1</h1> tag used where it does not belong. The text encapsulated in the wrong tag is simply omitted in the output. If these errors are not corrected you would end up with unreadable documentation.

This is an MXML AsDoc comment.
output:

Above is a snapshot of a Class Detail View page generated by the documentation tool.

Errors

My advice is when you start a new project always setup your documentation along with the project. There is nothing worse than an already built project that you have to create documentation for. When you are put in a situation where you have to document an already created project prepare to be patient and expect errors.
Here are a few common things that would cause a Build fail:

• Improperly imported classes or classes that have not been imported at all. Even though Flash Builder will run your project, and build successfully, the documentation tools will fail at that obstacle.

• Undeclared in the build file external resources and related projects. If you have read Part 1 of this tutorial, you must now know about the “-source-path”, “-doc-sources”, “-external-library-path”, and my personal favorite “-exclude-classes”. Declare all external resources because they are mentioned in your project’s code and the documentation tool would look for them, but will not find them unless you specify their paths in your buildFile.xml.

• Be careful where you place your build-file. You cannot modify the example build-file you will find in the Ant folder, but you can copy and customize it. I place my build-files directly in this location: /Applications/Adobe Flash Builder 4/sdks/4.1.0/ant/yourBuildFile.xml.

• Spark and Halo do not always mix when it comes to documentation. Below is an example of what happens when you have halo for a project theme but you have used a spark component. 
Ant build Error.

I will keep adding to this list every time I meet a new issue regarding documentation generation.

Next is Part 3 of this tutorial, where I will cover template customization. This way your documentation can take on a view and feel closer to that of your project, and I promise you good presentation always pays!

Happy coding!

About Curious Minds
We are a web development firm in New York and Chicago, providing development resources and consulting for websites and mobile apps since 2004.