Flex帮助文档制作（ASDoc——注释篇1）
之前写了使用ASDoc打包自己的帮助文档，后又写了如何将打包好的html文档改成chm格式的，今天记录一下使用ASDoc写注释的时候需要注意的部分参数。
首先我们先来看一个没有任何注释的类。类定义如下：
package moter { import flash.events.EventDispatcher; [Event(name="succeedCallback", type="flash.events.Event")] public class Demo extends EventDispatcher { private static const static_const_private:int=0; protected static const const_protected:String=""; public static const const_public:Boolean=true; private static var static_private_variable:int; protected static var static_protected_variable:String; public static var static_public_variable:Boolean; private var _private_variable:int; protected var protected_vairable:String; public var public_variable:Boolean; private const const_private:int=0; protected const const_protected:String=""; public const const_public:Boolean=true; public function Demo(str:String) { } public function get private_variable():int { return _private_variable; } public function set private_variable(value:int):void { _private_variable = value; } private static function static_private_method():void { } protected static function static_protected_method():void { } public static function static_public_method():void { } public function public_method():void { } protected function protected_method():void { } private function private_method():void { } } }
其几乎包含了所有类相关的定义，运行ASDoc来生成此类文档（此步骤在《Flex帮助文档制作（ASDoc——html篇）》里面有详细讲解）。
追梦（笔名）发现生成后的文档静态公有的属性会和公有属性组织在一起，而静态受保护属性会和受保护属性组织在一起；方法也如此。同时私有成员是不会体现在文档之中。（我们所谓的字段其实都变成了属性来标记，正真的set get属性也放在了属性里面）
首先，我们一般会对类文件的类和成员以及成员函数做一些解析性说明。那么这个解析性说明应该怎么写呢？如果想给指定的类、成员属性、成员函数加上注释，可以在这些声明的顶部按照下面的格式属性注释：
（在flash builder里，按Ctrl+Shift+D可以很方便地添加AsDoc注释）
（注意注释的文字和*之间必须有空格，不然第一个位置的任何文字会被忽视）
（注意我的ASDoc是通过公司的包汉化了的，有想要的可以留言）
源代码：
/** * 公有字段 */ public var public_variable:Boolean;
效果：
这样我们在进行一次文档生成操作后，会发现你所添加的注释会在响应的类、属性或者方法下面多出一行说明文字。关于注释的内容可以为任意字符，甚至可以搭配HTML标记来修饰注释内容。（其输出的是HTML当然可以用HTML标记来描述了，呵呵），说完最常用的注释后，接下来说一下被ASDoc所能解析的标记，下面将逐一进行探讨。
1、@author 用户名
此标记用于标记类的创始人，使用快捷键生成系统胡默认把用户名设定为你的计算机的用户名(如：administor)，网上某资料说可以通过如下三步修改：
Step1：打开C:\Program Files\Adobe\Adobe Flash Builder 4\FlashBuilder.ini。
Step2：在后面加入一行：-Duser.name=heguang。
Step3：注意要加在任何-vmargs语句后面，且等号没有空格。
但是我试了却没有用，反而弄的我的flash builder的空间需要修改，出错了。有知道的朋友请告诉我一声哦！
源代码：
/** * 实例类 * @author liuyayun */ public class Demo extends EventDispatcher
效果：
实例类可以显示出来，下面的标记不能显示，估计也就是用来标记一下的吧！
2、@param标记
@param标记是为带参数的函数中的参数作注释用的标记。通过此标记可以生成对应的参数的说明。此标记的书写格式如下：
@param 参数名称 参数说明
从书写格式可以看出来，一个这样的标记仅对应一个方法中的一个参数。如果一个方法中包含多个参数可以用多个@param来进行说明。如下是一个例子：
源代码：
/** * 方法的说明 * @param name 第一个参数说明 * @param age 第二个参数说明 */ public function public_method(name:String,age:Number):void { }
效果：
从例子中可以看出来，在@param标记中写入的内容会被写入Parameters栏中。在官方文档中对@param标记的功能还提到了一点就是，写入的参数名称必须要对应方法签名中的参数名称。也就是说如果有两个参数，必须要按照定义的参数顺序来进行注释。追梦做了一个尝试，就是给一个带两个参数的方法注释时不按照签名定义来进行注释，发现注释变得混乱。同时，也尝试过把@param的paramName部分随便填上一些字符，但是输出的参数名称依旧会按照方法中的参数名称来显示。所以，可以得出一个结论就是paramName可以为任意名称，但注释信息必须要对应签名顺序中的参数，这样ASDoc也能为你把参数名称正确地分配到正确的注释中。
当然，笔者不赞成乱写参数名称的办法，因为这样会养成不好的习惯，同时也会造成程序的可读性降低。所以，应该对应参数名称来写入参数注释。
3、@example标记
@example是可以为某个类、方法或者属性加一个说明性的例子，从而让自己的代码更加容易理解。其书写格式为：
@example 例子的说明性文字
<listing version=”3.0”>
例子的代码
</listing>
从格式中可知，例子的代码是写在<listing />标记之中的（version=”3.0”可有可无，只是版本号），下面通过一个例子来说明一下，还是以public_method函数为例：
源代码：
/** * 方法的说明 * @param name 第一个参数说明 * @param age 第二个参数说明 * @example 例子说明 * <listing> * //初始化一个Demo对象 * var demo:Demo=new Demo("追梦"); * //调用方法public_method * demo.public_method("追梦的远远",22); * ... * </listing> */ public function public_method(name:String,age:Number):void { }
效果：
从上图可见，在@example后面的文字输出在Example的下面，此文字是用来对例子的一个说明。然后写在<listing />标记中的代码就放在一个灰色的矩形框中。根据官方的帮助说明，在个框是带水平滚动条的，所以当内容超出一定长度后就会显示水平的滚动条。追梦对此也作出了验证，发现确实能够出现水平滚动条，至于高度则由内容的高度决定，但不会出现垂直滚动条。需要注意的是注释里面大家很容易出现for循环，就不能避免使用<或则>等，我们的本意是注释里面使用比较，但是ASDoc会把这些识别为标签，这样就会出现错误，我的办法是使用中文的《或》来标示小于等于，你们有别的办法请告诉我，互相学习。
4、@return标记
@return针对一个方法的返回值进行说明。也就是说此标记是用于方法中的注释的。其中其书写格式如下：
@return 说明文字
下面看一下例子：
源代码：
/** * 获取名字 * @return 返回名字 */ public function getName():String { return "追梦的远远"; }
效果：
从上图可见，我们在注释中并没有在@return中写明返回值的类型，但是在生成的文档中确能够显示返回值类型，这其实是ASDoc能够自动识别方法返回值的类型，所以并不需要我们指定。那对于无返回值的方法（也就是返回值类型为void的方法）如果加上这个标记没有效果。
5、@see标记
@see标记的作用是生成一个参考引用。在一些情况下某些类、属性或者方法在其他地方有进行说明或者引用，这时候我们可以通过此标记来引用此例子来进行说明。其书写格式如下：
@see 引用 [说明文本]
看如下例子：
源代码：
/** * 获取名字 * @see MyCeShi#getNameById()[文字说明] * @return 返回名字 */ public function getName():String { return "追梦的远远"; }
效果：
如图所示，getName方法下多出了一栏另请参见（See also）的信息，在这栏里面就有刚才所写的getName方法的引用。可能你会问@see标记中的引用部分应该怎么写呢？其实对于引用类内部方法来说是通过锚点来实现的，所以引用部分就是填写一个锚点（如果要引用到当页的锚点，学个HTML的朋友就知道是用#锚点名称）。其实用ASDoc生成的方法和属性都带有一个锚点的，其规律就是方法的锚点就是方法名称()（一定要加括号），属性的锚点就是属性名称。
对于如果一个类、方法或属性中有多个参考引用的地方我们可以使用多个@see来进行引用，这是ASDoc中所允许的。
根据追梦的总结，对于@see标记的引用参数的写法应该是(分别对于类、方法和属性)：
包路径.类名称
包路径.类名称#方法名称()
包路径.类名称#属性名称
如果是类内的方法则可以省略包路径.类名称部分。
6、@private标记
此标记的作用是，当你的部分类、方法或属性不想公开给其他人看到的时候，可以在相应的地方加上此标记。那么ASDoc将不会生成此部分的文档说明。其书写格式如下：
@private
源代码：
/** * @private * 获取名字 * @see MyCeShi#getNameById()[文字说明] * @return 返回名字 */ public function getName():String { return "追梦的远远"; }
生成文档后就看不到此方法的说明了。不再体现在文档中。
这些应该是常用的几个参数，其他参数有时间再总结吧！
