ASDoc, ASDocr, documenting your code gotchas

Have you tried to generate documentation out of your code? I bet you did, and I bet that like me you have found many obstacles to succeed. Here I will describe how I finally made it, I hope you will find it useful.

First don’t be masochist and use ASDocr, an AIR application made by Grant Skinner to simplify the whole process.

Setting up of the application is quite simple so I will not describe it here unless it will be beneficial to explain the documentation issues.

1. Your code must be valid without erros (i.e. syntax errors).
2. Your comments must have valid html tags properly opened and closed. This makes a bit problem with Vector class.
3. There MUST be a space after asterisk in the comment.
4. for package description use “-package-description-file=” in asdoc command or in “additional params” field in ASDocr app on “options” tab, pointing to the XML with package descriptions (this works only for Flex SDK 4.1+)
5. If you have an error then try to do it in parts, create source class folder and move there few classes run asdoc if there are errors fix them run again until documentation created, repeat for rest of the classes you wish to document. Some of the errors are pretty general so you can do search and replace which speeds up the process.

Examples of comments that will cause problems while creating documentation.

/**
 *this method is just a dummy test method.
 */
public function myMethod():void
{}
//the documentation will "eat" t that touches asterisk,
//displaying "his method is just a dummy test method.".

/**
 *<p>this method is just a dummy test method.</p>
 */
public function myMethod():void
{}
//the asdoc will throw [FatalError] pointing you to 
//the validation_errors.log which might say: 
//Text for description in <here location of error>
//i.e. com.greladesign.MyClass/myMethod
// is not valid.
//No matching start tag.
//this is same as previous, the asdoc "eats" < becuase 
//of missing space afer asterisk causing "No matching 
//start tag" error.

/**
 * this method is just a dummy test method.
 * @param Vector.<String> passed can't contain null values.
 */
public function myMethod(list:Vector.<String>):void
{}
//the vector syntax causes problems when placed in comments, 
//basically any < or > that is not part of HTML markup used in 
//comment MUST be replaced with entities &lt; and &gt;
//[Fatal Error] :3:4: The element type "String" must be 
//terminated by the matching end-tag "</String>".
//Encountered not well-formed text. 
//Please see <path to>\validation_errors.log for details.
//The error in the log: The element type "String" must be 
//terminated by the matching end-tag "</String>"

//corrected
/**
 * this method is just a dummy test method.
 * @param Vector.&lt;String&gt; passed can't contain null values.
 */
public function myMethod(list:Vector.<String>):void
{}

Sample of package description XML file.

<overviews>
    <packages>
		<package name="com.greladesign.sample">
			<shortDescription><![CDATA[Short description, displayed in all packages table]]></shortDescription>
			<description><![CDATA[Long description, displayed when package is selected]]></description>
		</package>
    </packages>
</overviews>

well that’s it for now, happy coding (and documenting).