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:
[html]
The filter used for convert to binary images

[/html]

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:
[html]

[/html]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:
[html]

[/html]

7. Xml structure example
[html]

[/html]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 ;-)

Share This