探索ASDoc 标签篇.docxVIP

探索ASDoc:标签篇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 varstatic_private_variable:int;protected static varstatic_protected_variable:String;public static varstatic_public_variable:Boolean;private static function static_private_method():void{}protected static function static_protected_method():void{}public static function static_public_method():void{}privatevarprivate_variable:int;protectedvarprotected_vairable:String;publicvarpublic_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，然后我们来生成文档看一下文档格式如何，其中函数定义如下：/*** 输出信息* @param info 需要输出信息的对象* */public function print(info:Object):void{}在命令行输入：D:\study\asdocasdoc -doc-classes Demo -output doc\ -source-path .其输出格式为：从例子中可以看出来，在@param标记中写入的内容会被写入Parameters栏中。在官方文档中对@param标记的功能还提到了一点就是，写入的参数名称必须要对应方法签名中的参数名称。也就是说如果有两个参数，必须要按照定义的