Linden's Blog

Linden Liu’s flex series: Tips of Writing ASDoc

Tip 1: The sequence of the @param should be as the order of parameters defined in function.
For example, you defined a function like this public function foo(param1:Type1, param2:Type2, param3:Type3):void. The asdoc should be like this:
/**
* xxxxxxxxxxx description of the function.
* @param param1 xxxxx.
* @param param2 xxxxx.
* @param param3 xxxxx.
* xxxxxxxxxxxxxxxx.
*/
public function foo(param1:Type1, param2:Type2, param3:Type3):void
If parameters are not written in such order, the type of each parameter will misorder.

Tip 2: Every sentence should be ended with a dot “.”, if the asdoc is using the language which dosen’t terminate sentence with “.”.

Tip 3: Keep the special or escape characters in mind. The “&” mark is a logic operator and it is also a escape character in ASDoc just like it in html. So the “&&” is not allowed in ASDoc. If you do that, it will be OK in Flex 3, but it will be caused an error when using Flex4. So It is better to make all escape charaters replaced.

Technorati : asdoc, flex