ActionScript注释生成工具很多, 但俺们就使用ASDoc.

首先, 总结下ActionScript注释规范:

常用的注释:
@param
@return
@throws
@see
如:

	/**
	 * 解析给定的I18N语言字符串, 并通过fieldStringToLocalizationItem将之转换为LocalizationItem对象,放入到ArrayCollection中.
	 * @example 处理里一串I18N语言字符串
	 *
	 * stringToAC('{zh=简体中文}{zh_tw="繁体中文"}', false);
	 *
	 * @param s:String 待处理的字符串
	 * @param strict:Boolean 是否采用严格机制来处理, 默认为ture,意为如果字符串不合要求则报错; 可指定为False, 忽略错误,完成操作.
	 * @return 处理完后包含有LocalizationItem的ArrayCollection; 如果制定的字串为NULL,则返回一个空的ArrayCollection;
	 * @throws Error 如果strict为true,在检测到字符串不合要求时会throw Error.
	 * @see #fieldStringToLocalizationItem()
	 */
	public static function stringToLocalizationItems(s:String, strict:Boolean = true):ArrayCollection {
....
}

[这个文档写的很粗糙] 经过ASDoc生成后的文档如下:

@see的用法

当需要see顶级类中的函数时
@see Array#pop(); (Method)
@see Array#length; (Property)

需要see本类某函数时,如需要see下本类的 fieldStringToLocalizationItem(fieldString:String, strict:Boolean = true)函数, 则:
@see #fieldStringToLocalizationItem().

关于@see的详细介绍: http://livedocs.adobe.com/flex/3/html/help.html?content=asdoc_7.html#188433
不足之处就是开发工具对注释的支持实在是不敢恭维.

另外总结下ASDoc里重要的配置参数

-source-path, 该path指明了源代码存放的位置

-doc-classes, 需要生成目录的类 , 在使用该变量之前必须已经声明-source-path;

如: asdoc -source-path . -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo 则意味着生成当前目录下,comps\GraphingWidget .as 与comps\GraphingWidgetTwo.as的文档

-doc-sources: 指定某目录, 生成该目录及其子目录下所有.as文件的注释. 可以单独直接使用,也可以配合使用-source-path. 如:

doc-sources E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\workspace\\AIRTest\\com\\insprise

或配合使用:

-doc-sources   com\\insprise

-source-path   E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\workspace\\AIRTest\\com\\insprise

其他信息基本上都是无关紧要不痛不痒的一看明白.

可参照:http://liguoliang.com/2008/10/280/

分析:使用ANT进行自动化配置, 使用ASDoc产生注释

在所在工程中新建一个properties文件,用以保存相关配置, 同时建立一个bulid.xml, 用以提供ANT配置文件.

具体实现:

1:  为便于管理与配置, 将ASDoc的参数放置于一个properties文件中, 在本例中我们取名叫做: asdoc.properties
含如下信息:
FLEX_HOME = E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\FBPlug-in301\\sdks\\3.1.0
asdoc.exe  = E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\FBPlug-in301\\sdks\\3.1.0\\bin\\asdoc.exe
dir.docSource = com\\insprise\\localizationeditor
dir.src  = .
dir.output =  E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\workspace\\AIRTest\\doc
main.title = Test
window.title  =  test
footer  = Insprise Software

以上提供了ASDoc的路径, 源文件的目录, 文档输出目录, 以及文档的网页标题, 文档内标题, 文档页脚等信息.

2: Build.xml配置: [因代码高亮代码有误,导致bulid.xml显示有误,请参照网页源代码自行修正]

ANT运行build.xml之后,将会自动生成文档到输出目录.

ASDoc具体的参数配置可参见:http://liguoliang.com/2008/10/286/

当ANT编译成功后,会出现如下提示[这个是在Eclipse中使用ANT编译后的输出信息]:

Buildfile: E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\src\build.xml

clean_Old_Docs:

   [delete] Deleting directory E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\doc

    [mkdir] Created dir: E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\doc

create_Docs:

     [exec] Loading configuration file E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\FBPlug-in301\sdks\3.1.0\frameworks\flex-config.xml

     [exec] Documentation was created in E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\doc\

main:

BUILD SUCCESSFUL

Total time: 26 seconds