flashbuilderadobe flash builder 怎样自动生成注释?

flash builder怎样使用as文件

没明白你什么意思？ flash builder本身就是as编译软件，你可以建立工程再新建AS文件，也可以直接打开AS文件。

如果你要使用AS类文件就要建立此类的实例 不明白你的意识

adobe flash builder 怎样自动生成注释?

ASDoc是adobe官方提供的ActionScript的API文档生成工具，现在已经集成在FlexBuilder3中。

笔者这段时间才刚刚接触到这个工具，所以在网站也搜索了一些资料来对这个工具作进一步的了解。

不过中文的资料对此工具的介绍和使用也不是太多，经过我几天的努力，对一些国外资料的研究和总结写了以下这篇文章，这篇文章主要是对ASDoc在注释中所使用的标签作了一些深入的研究，现在把我在探索的这个过程中的一些心得分享给大家。

首先在这里要先介绍一下API文档生成形式格式和结构，为了了解ASDoc的生成形式，在第一个例子中将不采用任何ASDoc标记来注释类。

类定义如下： package{ public class Demo{ private static const const_1:int; protected static const const_2:String; public static const const_3:Boolean; private static var static_private_variable:int; protected static var static_protected_variable:String; public static var static_public_variable:Boolean; private static function static_private_method():void{ } protected static function static_protected_method():void{ } public static function static_public_method():void{ } private var private_variable:int; protected var protected_vairable:String; public var public_variable:Boolean; public function Demo(){ } public function public_method():void{ } protected function protected_method():void{ } private function private_method():void{ } } } 其包含了所有类相关的定义，运行ASDoc来生成此类文档（在输入命令使需要注意-source-path如果不在当前目录时需要自己指定，而且必须使用-doc-classes、-doc-namespaces或者-doc-sources来指定那些类、名称空间或者源码）。

笔者发现生成后的文档静态公有的属性会和公有属性组织在一起，而静态受保护属性会和受保护属性组织在一起；方法也如此。

同时私有成员是不会体现在文档之中。

其实，这些可以根据Flex的帮助文档就可以知道了，为了有一个好的开始，还是先进行了一下这样的测试。

接着下来将逐步介绍ASDoc标记的用法以及一些ASDoc的参数使用。

首先，我们一般会对类文件的类和成员以及成员函数做一些解析性说明。

那么这个解析性说明应该怎么写呢？如果想给指定的类、成员属性、成员函数加上注释，可以在这些声明的顶部按照下面的格式属性注释： 这样我们在进行一次文档生成操作后，会发现你所添加的注释会在响应的类、属性或者方法下面多出一行说明文字。

关于注释的内容可以为任意字符，甚至可以搭配HTML标记来修饰注释内容。

（其输出的是HTML当然可以用HTML标记来描述了，呵呵），说完最常用的注释后，接下来说一下被ASDoc所能解析的标记，下面将逐一进行探讨。

@param标记 @param标记是为带参数的函数中的参数作注释用的标记。

通过此标记可以生成对应的参数的说明。

此标记的书写格式如下： @param 参数名称 参数说明 从书写格式可以看出来，一个这样的标记仅对应一个方法中的一个参数。

如果一个方法中包含多个参数可以用多个@param来进行说明。

现在我们来为Demo写一个函数print，然后我们来生成文档看一下文档格式如何，其中函数定义如下： public function print(info:Object):void{ } 在命令行输入：D:studyasdoc>asdoc -doc-classes Demo -output doc -source-path . 其输出格式为： 从例子中可以看出来，在@param标记中写入的内容会被写入Parameters栏中。

在官方文档中对@param标记的功能还提到了一点就是，写入的参数名称必须要对应方法签名中的参数名称。

也就是说如果有两个参数，必须要按照定义的参数顺序来进行注释。

笔者做了一个尝试，就是给一个带两个参数的方法注释时不按照签名定义来进行注释，发现注释变得混乱。

同时，也尝试过把@param的paramName部分随便填上一些字符，但是输出的参数名称依旧会按照方法中的参数名称来显示。

所以，可以得出一个结论就是paramName可以为任意名称，但注释信息必须要对应签名顺序中的参数，这样ASDoc也能为你把参数名称正确地分配到正确的注释中。

如下面例子所示： public function print(info:Object,format:String):void{ } 其输出格式是： 当然，笔者不赞成乱写参数名称的办法，因为这样会养成不好的习惯，同时也会造成程序的可读性降低。

所以，应该对应参数名称来写入参数注释。

@example标记 @example是可以为某个类、方法或者属性加一个说明性的例子，从而让自己的代码更加容易理解。

其书写格式为： @example 例子的说明性文字 例子的代码 从格式中可知，例子的代码是写在标记之中的，下面通过一个例子来说明一下，还是以print函数为例： public function print(info:Object,format:String):void{ } 其输出格式为： 从上图可见，在@example后面的文字输出在Example的下面，此文字是用来对例子的一个说明。

然后写在标记中的代码就放在一个灰色的矩形框中。

根据官方的帮助说明，在个框是带水平滚动条的，所以当内容超出一定长度后就会显示水平的滚动条。

笔者对此也作出了验证，发现确实能够出现水平滚动条，至于高度则由内容的高度决定，但不会出现垂直滚动条。

如下图所示： @return标记 @return针对一个方法的返回值进行说明。

也就是说此标记是用于方法中的注释的。

其中其书写格式如下： @return 说明文字 下面往类中来添加一个新的方法getString来进行说明： public function getString():String{ return "demo"; } 用ASDoc来进行生成文档，其格式如下图所示： 从上图可见，我们在注释中并没有在@return中写明返回值的类型，但是在生成的文档中确能够显示返回值类型，这其实是ASDoc能够自动识别方法返回值的类型，所以并不需要我们指定。

那对于无返回值的方法（也就是返回值类型为void的方法）如果加上这个标记会怎么样呢？下面我们看看这个例子： public function print(info:Object,format:String):void{ } 其输出格式为： 从图中可见，即使我们写上了@return标记，当ASDoc检测到该方法是无返回值时，他会自动过滤掉@return所作的说明。

@see标记 @see标记的作用是生成一个参考引用。

在一些情况下某些类、属性或者方法在其他地方有进行说明或者引用，这时候我们可以通过此标记来引用此例子来进行说明。

其书写格式如下： @see 引用 [显示文本] 为了更好的理解其含义，我将在原来的print方法中引入getString方法，然后getString方法中则采用@see标记来进行参考引用。

public function print(info:Object,format:String):void{ } public function getString():String{ return "demo"; } 生成文档后，输出样式如下： 如图所示，getString方法下多出了一栏See also的信息，在这栏里面就有刚才所写的print方法的引用。

可能你会问@see标记中的引用部分应该怎么写呢？其实对于引用类内部方法来说是通过锚点来实现的，所以引用部分就是填写一个锚点（如果要引用到当页的锚点，学个HTML的朋友就知道是用#锚点名称）。

其实用ASDoc生成的方法和属性都带有一个锚点的，其规律就是方法的锚点就是方法名称()（一定要加括号），属性的锚点就是属性名称。

下图就是的状态栏中就有显示一个方法的锚点 如图所示，Demo.html后面的就是锚点名称了。

如果不知道的朋友可以通过生成一份文档来观察一下。

那如果要引用其他类的方法呢？呆会再作演示，现在来看一下上例中的See also一栏下面的只是一个纯粹的方法名称，如果想要一些更加详细的说明，可以在应用部分加入提示性文字。

我们把上面的例子改一下，代码如下： public function print(info:Object,format:String):void{ } public function getString():String{ return "demo"; } 然后进行文档生成，效果如下图所示： 可以看到引用部分不再是换成了我们添加的文本了。

其中官方文档中还提到一个@see标记的参数是不能包含HTML格式的字符的。

为了验证这个说法，我做了一下实验，把刚才的例子中的说明文字加上了一个加粗字体的标记，如下所示： public function getString():String{ return "demo"; } 然后进行文档生成时出现错误了，其提示说不能使用HTML格式，如下图所示： 对于如果一个类、方法或属性中有多个参考引用的地方我们可以使用多个@see来进行引用，这是ASDoc中所允许的。

基本上就@see标记在类内引用就讲到这里，对于如何引用其他类的元素现在来通过例子说明一下。

首先新建一个类，代码如下： package{ public class Demo2 extends Object{ public function Demo2():void{ } public function getString():String{ return "Demo2"; } } } 现在用Demo类中的getString方法来引用Demo2类中的getString方法。

代码如下： public function getString():String{ return "demo"; } 然后生成文档，效果如下图所示： 可以看到Demo2的getString()方法被正确引用到了。

根据笔者总结，对于@see标记的引用参数的写法应该是(分别对于类、方法和属性)： 包路径.类名称 包路径.类名称#方法名称() 包路径.类名称#属性名称 如果是类内的方法则可以省略包路径.类名称部分。

@private标记 此标记的作用是，当你的部分类、方法或属性不想公开给其他人看到的时候，可以在相应的地方加上此标记。

那么ASDoc将不会生成此部分的文档说明。

其书写格式如下： @private 下面来看一个例子，下面例子中把getString方法在生成文档是排除掉。

代码如下： public function getString():String{ return "demo"; } 生成文档后就看不到此方法的说明了。

不再体现在文档中。

@default标记 此标记是对属性、样式或者效果进行默认值说明。

其书写格式如下： @default 值 下面通过例子进行说明，在Demo类中加入属性name，然后应用@default标记，代码如下： public var name:String; 生成文档后，效果如下： 说明中多出了一行The default value is Demo。

@copy标记 @copy的作用能够把一个引用位置的注释复制到指定的位置。

但仅复制引用位置的主注释、@param标记以及@return标记内容。

通常此标记用在没有继承关系的类之间。

如果有继承关系的类中可以使用@inheritDoc代替，其书写格式如下： @copy 引用 语法中的引用参数更@see的一样，可以参考@see标记的用法。

下面用Demo2类中的getString方法引用Demo类中的getString方法，代码如下： public function getString():String{ return "Demo2"; } 生成文档后效果如下图： 可以看到他把Demo类的getString方法的注释信息拷贝过来了。

对于如果还有其他附加信息可以加上相应的标记，例如要加上一个例子，这时候可以往注释中加入@example。

在官方文档的例中有写到引用类内方法的例子，但笔者试了一下直接用#方法名()的方法填入引用参数，结果发现并没有拷贝出来，后来填写上完整的引用位置后才能够正常拷贝。

@eventType标记 @eventType是一个定义事件类型的标记。

此标记有两种写法，分别是： @eventType 包路径.类名称.常量 @eventType 事件名称 其中第一种写法是用于Event元数据标签的注释。

通过此标记可以于一个关联了事件名称的常量做绑定。

ASDoc在生成文档时就会自动在事件部分引用此常量。

第二种写法则是用于一个常量的注释。

此种方法是让常量指定与事件相关的名称（也就是对应Event元数据中的name参数）。

这里需要注意的是，如果你只在Event元数据标记的注释中写上了@eventType，但没有在常量中采用二种写法来对常量指定事件名称的话，那么在注释中也是没有办法将事件类型关联到指定常量的。

下面通过一个例子来说明一下，此标签的作用。

首先需要定义为类一个事件，然后定义一个DemoEvent的事件类，最后用@eventType使事件能够和事件的常量相关联。

代码如下： [Event(name="init",type="fi.events.DemoEvent")] …… public class Demo{ …… } package fi.events{ import flash.events.Event; public class DemoEvent extends Event{ public static const INIT:String="init"; public function DemoEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false){ super(type,bubbles,cancelable); } } } 然后生成文档，其效果如下图所示： 可见图中有一项叫DemoEvent.type property的信息，这一项就是@eventType所起的作用。

同时由代码可以知，常量和Event元数据都必须要用@eventType来进行注释的。

不过笔者发现此标记存在一点问题，就是假如我的DemoEvent类的包路径是events的话，那么生成的文档在引用events.DemoEvent时，路径上会多加一个events的包路径从而导致定位不正确。

只有带两层包时此标记才能正常。

@inheritDoc标记 此标记与@copy功能相同，不同的是其主要是用于把基类的一些注释信息拷贝到子类的重写方法、属性或者实现的接口注释中。

此标记也只能拷贝主要注释、@param和@return标记内容。

其他标记不会被复制。

其书写格式如下： @inheritDoc 下面声明一个继承于Demo的子类SubDemo，然后重写一下getString方法，我们观察一下带@inheritDoc和不带@inheritDoc的情况是怎么样的，代码如下： package{ public class SubDemo extends Demo{ public function SubDemo(){ } override public function getString():String{ return "sub"; } } } 生成文档如下图所示： 现在加上此标记，来生成文档，代码如下： package{ public class SubDemo extends Demo{ public function SubDemo(){ } override public function getString():String{ return "sub"; } } } 效果如下图： 可以发现基类的注释拷贝到子类中去了。

如果你的注释中包含@inheritDoc标记，那么ASDoc将使用一下的搜索顺序来查找信息： 1. 由当前类实现的接口（排名不分先后）和这些接口所有的基接口。

2. 当前类的直接基类。

3. 直接基类的所实现的接口及这些接口所有的基接口 4. 重复步骤2和3，直到到达Object类。

@ internal标记 @internal标记能够附加一些隐藏信息在注释中，这些信息并不体现在输出的文档中。

其书写格式如下： @internal 文本信息 请观察下面例子： package{ public class SubDemo extends Demo{ public function SubDemo(){ } override public function getString():String{ return "sub"; } } } 可以看到并没有出现@internal标记中的文字信息。

@throws标记 @throws标记是用来注释一个方法中可以引起的异常。

其书写格式如下： @throws 包路径.类名称 异常描述 下面通过加入一个新的类Exception其继承于Error类，然后在SubDemo的getString方法中写入@throws标记，代码如下： package{ public class Exception extends Error{ public function Exception(message:String = "", id:int = 0){ super(message,id); } } } package{ public class SubDemo extends Demo{ public function SubDemo(){ } override public function getString():String{ return "sub"; } } } 生成文档后，其效果如下： 发现多了一栏Throws信息。

@includeExample标记 此标记是引入一个外部示例文本到ASDoc输出中。

ASDoc将从由ASDoc工具的-examplespath参数指定的基于类的包名或者目录来搜索示例文件。

例如，你将示例路径参数设置为c:eamples。

然后为mx.controls.Button类添加一个示例。

他发生在c:exmples目录下的mxcontrolsdirectory里面，即是c:examplesmxcontrols directory。

你可以进一步用@includeExample标记来指定文件的位置。

例如，你指定的@includeExample标记如下所示： @includeExample buttonExample/ButtonExample.mxml ASDoc将从c:examplesmxcontrolsuttonExample目录下进行查找此示例。

如果在一个类注释中插入此标记，这个例子将显示在输出的HTML文档的最后面，如果你在一个类的元素中插入此标记，那么示例将出现在该元素的详细说明中。

其书写格式如下： @includeExample 示例文件路径 下面来通过示例看一下生成的文档样式如何，先建立一个示例文件example.txt，然后在SubDemo中运用@includeExample来引入此文件，代码如下： example.txt文件内容 //这是一个例子文件 var demo:Demo=new Demo(); SubDemo类 package{ public class SubDemo extends Demo{ public function SubDemo(){ } override public function getString():String{ return "sub"; } } } 上面步骤完成后，接下来要生成文档了，这时候要注意的是，asdoc中要指定一下-examples-path这个参数，如果不指定的话就会提示找不到外部示例文件。

最终命令行内容如下：asdoc -source-path . -doc-classes Demo Demo2 fi.events.DemoEvent SubDemo Exception -output doc/ -examples-path . 生成后效果如下图所示： 从图中可以看出在类说明部分会多出了一行叫View the examples的超级链接。

点击后就会定位到第二幅图的位置了。

这也正对应了上面所说的，如果在类中写入此标记，那么示例将会放置到帮助的最后面。

至于类元素中运用此标志就不详细说明了。

大家可以自己尝试一下。

@exampleText标记 此标记是使用在一个通过@includeExample标记引入外部的示例文件中。

其书写格式如下： @exampleText 说明文本 通过此标记可以在例子的前面或者后面加上一个对例子的注释说明。

其中外部例子是支持例子前后加注释的，所以标记也限定了加入ASDoc注释的位置，只能是例子的第一行前面或者例子的最后一行后面。

如果加入到中间的话，那么后面的所有文本都会被ASDoc所丢弃。

下面的例子来说一下其用法，首先在原来@includeExample的例子基础上往example.txt加上注释代码，如下所示： //这是一个例子文件 var demo:Demo=new Demo(); demo.getString(); 然后生成文档，效果如下图所示： @since标记 此标记是在一个类或者元素中添加一个Since单元。

其书写格式如下： @since 文本 此标记中的文本不会输出到文档中。

所有的标签都介绍完毕了，呵呵～希望对大家有所帮助，也希望ASDoc能让大家的代码在注释方面变得更加统一规范。