The document outlines to goals, conventions, and tips for creating documentation for Sandy 3.0.

• Pick a package to document here!
• Preliminary API documentation is here.

Sandy 3.0, which is the AS3 version of the Sandy library, is documented using Adobe ASDoc API documentation tool. ASDoc automatically generates the documentation from the comments in the source code (ActionScript files), assuming the comments are created correctly. ASDoc is distributed with Flex Builder as well as with the free Flex SDK 2.01 from Adobe.

When writing source code or documenting a package for which it hasn't previously been done, developers should add doc comments that follow the Sandy documentation conventions described here in. The method parameters used in doc comments should follow the Sandy naming conventions. This makes the API documentation consistent and easy to understand.

JavaDoc is a common tool for automatically generating documentation based on the comments in the source code. Different JavaDoc-like documentation tools, such as ASDoc, support different subsets of JavaDoc tags and deal with HTML and white space differently. Read Adobe's ”Creating ASDoc Comments” to learn how to write good comments for ASDoc.

The API documentation should be written primarily for the user of the API, the application programmer, not for the library developers who create and modify Sandy itself. The application programmer should be able to understand and use the Sandy library by reading the API documentation, without having to dive into the source code or understand its internal architecture. Therefore, references to the inner workings of the Sandy engine should be kept at a minimum.

Sandy developers should write normal source comments for the inner functionality of the library, but these will be ignored by the ASDoc tool.

One person is responsible for the documentation of one package at a time. A developer can pick an undocumented package and make it known to the community via the list that he/she intends to document that package.

The developer is then responsible for writing the doc comments for all classes and class members in that package. The developer should change the names of method parameters to satisfy the Sandy naming conventions.

If you do change parameter names, you are also responsible for testing that name changes doesn't introduce bugs ( for example by changing the wrong names or not all instances of a parameter). The actual work on the package can be distributed on a few hands.

The changed code is then committed to the Sandy SVN repository, preferably not more than one commit per day.

The API documentation is generated and published, using ASDoc on the latest subversion. This could be the responsibility of one person for all packages.

Consistent layout makes the comments easier to read in the source code, so this shows the convention used for documenting Sandy.

/**
 * This is the first comment line which serves as 
 * a short description, and ends with a period.
 *
 * <p>To get a second line comment, you enclose it in xhtml paragraph
 * markup. The asterisks to the left, are not part of the doc comment.</p>
 *
 * @tag    value
 * @tag    value
 */
public function theMethod():Void
{}

• The first slash is aligned with the first line of code, the asterisks are all aligned with the first asterisk.

• As for JavaDoc, the doc comment block is immediately followed by the first line of code.

• The first line of the comment, up to the first period, is used as a short description in summary listings. This sentence should give a meaningful but not too verbose description of the variable or method.

• More comment lines are produced, using xhtml paragraph markup. Here you can give a more detailed documentation of item - long description.

For an example, see the Box documentation and doc comments.

The content of a doc comment is there to explain as clearly as possible how to use a method, parameter or property in the public API. Here are some rules of thumb for creating a good API documentation, and some harsh experiences with the ASDoc tool.

1. Don’t state the data type for parameters and return values. ASDoc will pick up the signature of methods and the name: data type pair is there.

2. Don’t start the comments by giving the name of the method/class/proeperty. ASDoc will pick it up and use it as a title of the section in question.

3. Use an extra line feed after the description, and before the @param tags. It makes the comment more legible when reading the code.

4. Using xhtml in the comments: Avoid it if possible. If it really makes the API doc more readable - use it. New lines will often be needed for clarity, so the <p> tag must be used. It must be xhtml, so use it like this: <p>Some content go here</p>

5. Far from all JavaDoc tags are supported by ASDoc, so we have to use only supported tags. Exceptions to this rule are @author, @version and @date, which we keep in class and interface comments.

6. Trying to use unsupported and untested tags may lead to unpredictable error messages.

7. Don't use @param: ( with a colon ). It gives you Error #1083: The prefix “param” for element “param:” is not bound.

8. Don't use the unsupported @description tag. It triggers the seemingly unrelated complaint: Error #1085: The element type “shortDescription” must be terminated by the matching end-tag </shortDescription>”.

9. Don't forget to end the first doc comment line with a period! If you do, the short descriptions in summary lists will be toooo looong

Class documentation

/**
 * The Box class is used for creating a cube or box primitive ( cuboid ).
 * 
 * @author		Thomas Pfeiffer - kiroukou
 * @version		3.0
 * @date 		26.07.2007
 *
 * @example To create a rectilinear box with ( z, y, z ) dimensions ( 50, 100, 150 ),
 * created in 'tri' mode and a with a quality of 2, here is the statement:
 *
 * <listing version="3.0">
 *     var myBox:Box = new Box( "theBox", 50, 100, 150, PrimitiveMode.TRI, 2 );
 *  </listing>
 */
public class Box extends Shape3D implements Primitive3D

• The class doc comment may contain a usage description and code samples. The @usage tag is not supported by ASDoc.

• The <listing> element is interpreted by ASDoc to generate a code listing, giving it a CSS class, that we can use to format the code snippet.

• The @author, @version and @date tags are not used by this version of ASDoc, but should be left in for reference.

• Remember to set the version 3.0 and the date of the comment revision!

Variable documentation

/**
 * Creation mode - number of vertices per face.
 * <p>Possible values are PrimitiveMode.TRI and PrimitiveMode.QUAD
 */
private var _mode : String;

The doc comments for private members of a class are not used for API documentation by default.

• Value constraints may be given here, if any.

Constructor documentation

/**
 * Creates a Box primitive.
 *
 * <p>The constructor will create a complete object with vertices,
 * normals, texture coordinates and faces.<br/>
 * By default, the Box is created centered at the origin of the world coordinate system,
 * and with its edges parallel to world coordinate axes.</p>
 *
 * @param p_sName	a string identifier for this object
 * @param p_nWidth 	width of the Box  ( x direction )
 * @param p_nHeight	height of the Box ( y direction ) 
 * @param p_nDepth	depth of the Box  ( z direction )
 * @param p_sMode 	one of two available face generation modes: 
 *                      "tri" generates faces with 3 vertices, 
 * 			"quad" generates faces with 4 vertices.
 * @param p_nQuality	quality level of creation - the higher, the more faces
 */
public function Box ( p_sName:String, p_nWidth:Number=6, p_nHeight:Number = 6, 
		            p_nDepth:Number = 6, p_sMode:String = "tri",
                            p_nQuality:Number = 1)

• The short description tells what the constructor does.

• There is no need to state that this is a constructor!

• ASDoc recognizes and marks the constructor as such.

• When a longer description is necessary, it is given in one or more xhtml paragraphs.

• Don't state the data type in the @param or @return tag! ASDoc takes care of this

Method documentation

/**
 * Adds a new child to this node. 
 *
 * @param child 	The child node to add
 */
public function addChild( child:Node ):void 

• If the method does something ( a procedure ), the first comment line describes what it does.

• There is no reason to repeat the method name, or state that it is indeed a function/method in the comment.

/**
 * Returns an array containing all the child nodes of this node
 *
 * @return 	The array of child nodes
 */
public function getChildList():Array

• If the only purpose of the method is to get some data from the object ( an accessor ), the description starts with 'Returns'.

Property documentation

/**
 * Enables or disable back face culling.
 *
 * <p>A true value ( the default ) enables the backface culling.</p>
 */
public function get enableBackFaceCulling():Boolean
{
	return m_bBackFaceCulling;
}
/**
 * @private
 */
public function set enableBackFaceCulling( b:Boolean ):void
{
	// Body goes here
}

• ASDoc recognizes a property, and uses only one doc comment for the output. The doc should therefore describe what the property means, and not what the getter or setter does.

• The ASDoc manual states that “By convention, if there is both a setter and a getter, insert a single ASDoc comment before the getter, and mark the setter as @private.”

• Note that the @param and @return tags are not used for properties!

Getting the source to document

Before you start documenting, make sure you have the latest version of the library. You get it from the SVN repository using an SVN client, such as tortoisesvn. The downloaded copy of the SVN tree contains all versions and references to the central repository. Before you start documenting, you need to export the Sandy 3.0 version to a project directory of your choice.

On a windows system, you go climb down the SVN tree until you find Sandy3.0. You right click on the directory you want to export, and select TortoiseSVN/Export and you browse to your project directory and click ok.

This gives you a fresh copy to work on, without any links to the repository. Now you can start writing doc comments, and run the code through the ASDoc tool. If you made changes to the code itself, you make the test runs her too. If something goes wrong, you can do a new export from your local repository.

Once you are satisfied, you can copy ( there is no import ) your classes back to your local copy of the repository and make a commit to the SVN. If you don't have the commit rights, someone else can do the commit.

ASDoc

ASDoc is a part of the free Flex SDK 2.01. On a windows system you will find asdoc.exe in the /bin directory under the SDK install directory. This is not the tool itself, but a launcher for the Java based ASDoc tool, which you will find in the /lib directory. To make the tool work, you must have the Java runtime installed on your machine, and you cannot move asdoc.exe around, as the tool depends on other files in the installation, such as /frameworks/flex-config.xml and template files in the /asdoc directory.

When you have commented a source file, you want to feed it to the ASDoc tool, to check the result. You can do that from the command line, which isn't very hard.

Creating the API documentation

Here is the process on a Windows machine.

Let's say that your Flex SDK installation directory is E:\FLEX3SDK, and the Sandy source tree starts from your documentation project D:\AS3Lib\sandy

Go to the command prompt and change directory to D:\AS3Lib, directly above the sandy tree, and run the command

E:\FLEX3SDK\bin\asdoc -doc-sources sandy -source-path .

This generates documentation for the whole API. If you want to create documentation only for one class, you can do that as well. Note that the tool needs to the -source-path, which in this case is the directory above sandy ( a root directory ).

This is the current directory, so the whole relative path is the dot '.' If you don't give an output directory, the default directory asdoc-output is created for you.

A possible flow of work

• Pick a package to comment
• For each class
  • Write the class comment
  • Rename the constructor parameters if necessary ( optional )
  • Write the constructor comment
• For each public variable
• Write a variable comment
• For each public method and property
  • Rename the parameters if necessary
  • Write the method or property comment
• If you changed any method parameter name, you should make a test run, to see that the class still works.
• When satisfied with the comments on one or more classes, do a commit to the SVN

After one or two commits, someone should regenerate and republish the API documentation.

http://www.flashsandy.org/asdoc ( this document )

http://java.sun.com/j2se/javadoc/writingdoccomments

http://labs.adobe.com/wiki/index.php/ASDoc:Creating_ASDoc_Comments