blog.joa-ebert.com – Blog of Joa Ebert

There was one great tool to create a documentation for AS2. It was called BLDoc from Bline-Express. The only problem with this tool is that it does not work with Actionscript3. So I started working on a AS3 documentation tool called AS3toXML because it is only analyzing the code and creates a Xml without any nice visual output. That will be the next tool I will create. XMLtoHTML or something like that. Now back to the first application which is nearly finished.

I need your whishes and suggestions!

Yeah, thats true! I want you to help me to have a powerful tool to create Actionscript3 documentations. So here we go. I will post feature lists and Xml output. I wish you to use the comment function to tell me about possible mistakes since I do not know very much about Xml. I want you to tell me how things can be done better and feature requests.

Updated:

• Tags like @deceprated. I should have got all common tags now. If you know a tag you would like go ahead and leave a comment
• Support for the new namespace feature that AS3 offers (access of class members can be public/private/internal/protected or defined by namespace)
• Design changes. @see, @link, @throws and @req (requires) are now using same layout as multi-tags that can be used several times
• Fixed code-analyzer to work with very screwed code and multiline declarations/values

Pending:

• XSLT to format the output since the XMLtoHTML application is also finished now
• Support for meta-tags (still need a list of all that tags)

1. Supported tags

• @summary
• @example
• @version
• @throws
• @author
• @param
• @return

2. Supported files

• Classes lead to a class tag
• Interfaces will result in a interface tag
• Functions inside a package will be directly attached to a package

3. Supported items for documentation

• Functions
• Variables
• Classes/Interfaces

Do you want to comment on a package? Is this needed and where to put such a documentation? I think this is a main problem. A brief overview about a package could be useful. I am not sure.

4. Variable example
Input:
[as] /**
* The filter used for convert to binary images
* @see de.je2050.imageprocessing.filters.binarization.Threshold
*/
public static var threshold: IFilter = new Threshold;[/as]

Output:

The filter used for convert to binary images

5. Function example
Input:
[as] /**
* Input BitmapData is taken and a new image will be created with respect
* to the size of the BitmapData object. After that loadBitmapData gets
* called to copy all channels.
*
* @example Image.fromBitmapData( bitmap, ImageFormat.RGB, false );
*
* @param bitmap BitmapData object which will be used for new Image
* @param format May be any kind of de.je2050.imageprocessing.core.ImageFormat
* @param convertToGrayscale If your BitmapData source is not already a grayscale image you
* can convert it by setting convertToGrayscale true.
*
* @return new de.je2050.imageprocessing.core.Image with information from given BitmapData
*
* @see #loadBitmapData
* @see de.je2050.imageprocessing.core.ImageFormat
*
* @summary Returns a new Image that contains all information about given BitmapData source
*/
public static function fromBitmapData( bitmap: BitmapData, format: int, convertToGrayscale: Boolean = false ): Image
{
// …
}[/as]

Output:

<!--[CDATA[BitmapData object which will be used for new Image]]--> <!--[CDATA[May be any kind of de.je2050.imageprocessing.core.ImageFormat]]--> <!--[CDATA[If your BitmapData source is not already a grayscale image you
can convert it by setting convertToGrayscale true.]]-->      <!--[CDATA[Input BitmapData is taken and a new image will be created with respect
to the size of the BitmapData object. After that loadBitmapData gets
called to copy all channels.]]-->
<!--[CDATA[Image.fromBitmapData( bitmap, ImageFormat.RGB, false );]]-->
<!--[CDATA[new de.je2050.imageprocessing.core.Image with information from given BitmapData]]-->
<!--[CDATA[Returns a new Image that contains all information about given BitmapData source]]-->

6. Class example
Input:
[as]package de.je2050.imageprocessing.filters.convolution
{
import flash.filters.ConvolutionFilter;
import de.je2050.imageprocessing.core.Image;
import de.je2050.imageprocessing.filters.NativeFilter;

public class Convolution extends NativeFilter
{
public function Convolution()
{
//…
}

override public function toString(): String
{
//…
}
}
}[/as]

Output:

7. Xml structure example

Now it is your turn. Do not be shy and post your whishes and suggestions. Thanks so far for your interest! And do not forget to spread this post ;-)