January 5, 2007
by Eashwar Natarajan
AS Commenting Guidelines
As for our current project requirements, I have been fiddling around with ASDOCs. Trying to get it working and implemented into our project and after almost a few days of fighting with it. Here’s what I have 😉 . Apart from setting up the ASDocs, the developer’s are required to follow a specific commenting/coding pattern to take full advantage of ASDocs. Though ASDocs is still in its pre-beta stages, i think its pretty good to implement in any live project. Here, I am going to first take you step by step through the commenting patterns used by ASDocs. In my next post, I shall explain how to setup ASDocs to work with the Flex Builder. I’ll try to have a sample implementation ready with code snippets :).
1. Typical Class Comment
/**
* First sentence of a multi-paragraph main
description.
* <p>Second paragraph of the description.</p>
* @author "name"
*/
2. Standard Function comment
/**
* Typical format of a simple multiline documentation
* comment. This text describes the myFunction
* function, which is declared below.
* @langversion ActionScript 3.0
* @playerversion Flash 8
*
* @param param1 Describe param1 here.
* @param param2 Describe param2 here.
*
* @see someOtherFunction
*/
public function myFunction(param1:String,
param2:Number):void {}
PS: Only public function comments are included by AsDocs.
3. Getter Setter Property – Takes the comment of the getter/setter function to be the comment of the property. Marks “readonly” if getter method alone is present and “read-write” if getter and setter are implemented.
4. MetaData Tags – When Events are defined, comments are be added before the Event Tag. For Example
/**
* login event is dispatched after the login button
* is pressed.
* @eventType mx.events.DynamicEvent
*/
[Event(name="login",type="mx.events.DynamicEvent")]
For another example see propertySheet.as
5. @see, @example Tag – @see adds a “See Also ” text and indicates the related method to look in to. This tag can be used in class, method comments. @example Tag adds an example usage to a class/ method comment.
/**
* Conforms to Singleton Design Pattern.
* @author Eashwar N
* @see http://en.wikipedia.org/wiki/Singleton_pattern
* @example The following code gets the value
of DeviceTime
* <listing version="3.0" >
* CurrentDeviceTimeHolder.getInstance()
.DeviceTime
* </listing>
*/
7. To copy a comment from the base class method @inheritDoc tag can be used. In case there is no such relation @copy Tag can be used.
8. It can render a variety of html tags – <div>,<span>,<listing>,<img>,<table>
Note: Comments inside // and /**/ are ignored by the AsDoc.
Flexed 
Recent Comments