Make yourself some ASDoc!

Commenting evolution...

When I started out with programming I looked at commenting my code as unnecessary job. But back then, I worked with small programs. Then I was in a situation when I couldn't remember what classes are for what, and what some methods are doing. So I started commenting my code with simple line comments (//) or block comments (/**/). That was good enough for couple of years. Code was good, my methods, variables and classes were labeled. I wrote myself some kind of standard for code commenting. After that I wanted to have some documentation for my code. Then I opened Excel and wrote 3 columns. One was for methods name, second was for class name, and third was for method description. Now, I'm in stage when I don't have time or the motivation for double writing comments. That led me to discovery of ASDoc.

What is ASDoc?

Most simple explanation is that it is a tool for making documentation of your comments which are written in specific formatting. You comment your code with some explanation, some tags, and ASDoc will generate html documentation.

ASDoc formatting and tags

Formatting

It is really simple to format your comments for ASDoc. It's basically like writing block comments except you have one character more. One simple example is this:

/**
* Your description goes here.
*
* @tag Tag description goes here.
*/

Like I said before, your comments consist of explanation and tags. Important thing is that your first sentence have to describe your complete code (method, class, function or variable). I'll explain this on example. Let's say you commented your public function. That function will be visible in your documentation. Under your class there will be list of function on top. In that list you will find your function and short explanation which is exactly your first sentence. Sentence ends with period followed by  delimiter (space, tab, line break).

You can have as much sentences as you like, and all of them will show in detailed description of the code you commented.

Note:
Notice asterisk (*) and one white space is before every new line. It is common practice to put it like this. It will make your code more readable for you and needed for ASDoc tool to parse your comment.
Also I like to save some space and organize things, so when not needed, I write one line comments like this:

/**My one line description*/

Tags

Except describing your part of code, you can give it some "special abilities", called tags. Tags will put your tag explanation in special place and have it specially formatted in generated documentation. That will make your documentation more readable and more structured.

Note:
In section below, I gave a link to what Adobe calls "complete list of ASDoc tags". It isn't complete list! The best way to find tags which you want is to go to Adobe documentation, find some piece of documentation you like, then go to Flash classes (where you installed Flash) and open that class in which you found that piece of documentation, and read out that tag and it's formatting.

Read more

Creating ASDoc comments
Documenting ActionScript elements
Complete list of tags

FlashDevelop integration

If you don't know what FlashDevelop is, check out FlashDevelop - essential developing environment.
Since I like working with FlashDevelop, I wanted to integrate documentation generation in it.

First you have to download and install FlexSDK if you don't have it. This is needed since ASDoc is now part of Flex SDK.

Next you have to configure your FlashDevelop to connect to ASDoc in FlexSDK. Read tutorial here.
(don't forget to remove line breaks and " in tag)

That's it. Now when you are done writing your comments, just select ASDOC button from toolbar and your documentation is generated.

Note:
One other thing is that you have to have proper folder structure for generating you documentation. My folder structure is on the picture. This is needed because when you choose to generate ASDoc it will create separate folder in which it will store all documents needed for your documentation. In src I put my source code, in deploy goes final product, and in root is my FD file. Then when I click on ASDOC button  to generate documentation, it will create doc folder in the same directory as your FD file. If you follow their tutorial and input their code in Toolbar.xml, it states path to your source code folder. I find this structure as the best way of keeping your files neatly organised. If you still choose to have your own structure, just replace -doc-sources path in Toolbar.xml.

Final thought

Well ASDoc made my life easier. Now when I work on a project, I have complete description of my classes in one place. It really ensures you if you need to return to some project after a while.