Using ASDoc – Part 1

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.