【转】探索ASDoc:标签篇-@param标签

本文转自：云の部族

ASDoc是adobe官方提供的ActionScript的API文档生成工具，现在已经集成在FlexBuilder3中。笔者这段时间才刚刚接触到这个工具，所以在网站也搜索了一些资料来对这个工具作进一步的了解。不过中文的资料对此工具的介绍和使用也不是太多，经过我几天的努力，对一些国外资料的研究和总结写了以下这篇文章，这篇文章主要是对ASDoc在注释中所使用的标签作了一些深入的研究，现在把我在探索的这个过程中的一些心得分享给大家。

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

 1package{
 2       public class Demo{
 3              private static const const_1:int;
 4              protected static const const_2:String;
 5              public static const const_3:Boolean;
 6             
 7              private static var static_private_variable:int;
 8              protected static var static_protected_variable:String;
 9              public static var static_public_variable:Boolean;
10             
11              private static function static_private_method():void{
12              }
13              protected static function static_protected_method():void{
14              }
15              public static function static_public_method():void{
16              }
17             
18              private var private_variable:int;
19              protected var protected_vairable:String;
20              public var public_variable:Boolean;
21             
22              public function Demo(){
23              }
24             
25              public function public_method():void{
26              }
27             
28              protected function protected_method():void{
29              }
30             
31              private function private_method():void{
32              }
33       }
34}

其包含了所有类相关的定义，运行ASDoc来生成此类文档（在输入命令使需要注意 -source-path 如果不在当前目录时需要自己指定，而且必须使用 -doc-classes 、-doc-namespaces 或者 -doc-sources 来指定那些类、名称空间或者源码）。

笔者发现生成后的文档静态公有的属性会和公有属性组织在一起，而静态受保护属性会和受保护属性组织在一起；方法也如此。同时私有成员是不会体现在文档之中。其实，这些可以根据Flex的帮助文档就可以知道了，为了有一个好的开始，还是先进行了一下这样的测试。接着下来将逐步介绍ASDoc标记的用法以及一些ASDoc的参数使用。

首先，我们一般会对类文件的类和成员以及成员函数做一些解析性说明。那么这个解析性说明应该怎么写呢？如果想给指定的类、成员属性、成员函数加上注释，可以在这些声明的顶部按照下面的格式属性注释：

1/**
2  * 注释内容
3  * */

这样我们在进行一次文档生成操作后，会发现你所添加的注释会在响应的类、属性或者方法下面多出一行说明文字。关于注释的内容可以为任意字符，甚至可以搭配HTML标记来修饰注释内容。（其输出的是HTML当然可以用HTML标记来描述了，呵呵），说完最常用的注释后，接下来说一下被ASDoc所能解析的标记，下面将逐一进行探讨。

@param标签

@param标记是为带参数的函数中的参数作注释用的标记。通过此标记可以生成对应的参数的说明。此标记的书写格式如下：

@param 参数名称 参数说明

从书写格式可以看出来，一个这样的标记仅对应一个方法中的一个参数。如果一个方法中包含多个参数可以用多个@param来进行说明。

现在我们来为Demo写一个函数print，然后我们来生成文档看一下文档格式如何，其中函数定义如下：

1/**
2* 输出信息
3* @param info 需要输出信息的对象
4* */
5public function print(info:Object):void
6{
7}

在命令行输入：

D:\study\asdoc>asdoc -doc-classes Demo -output doc\ -source-path .

其输出格式为：

从例子中可以看出来，在@param标记中写入的内容会被写入Parameters栏中。在官方文档中对@param标记的功能还提到了一点就是，写入的参数名称必须要对应方法签名中的参数名称。也就是说如果有两个参数，必须要按照定义的参数顺序来进行注释。笔者做了一个尝试，就是给一个带两个参数的方法注释时不按照签名定义来进行注释，发现注释变得混乱。同时，也尝试过把@param的paramName部分随便填上一些字符，但是输出的参数名称依旧会按照方法中的参数名称来显示。所以，可以得出一个结论就是paramName可以为任意名称，但注释信息必须要对应签名顺序中的参数，这样ASDoc也能为你把参数名称正确地分配到正确的注释中。如下面例子所示：

1/**
2* 输出信息
3* @param firstParam 需要输出信息的对象
4* @param secondParam 输出格式
5* */
6public function print(info:Object,format:String):void
7{
8}

其输出格式是：

当然，笔者不赞成乱写参数名称的办法，因为这样会养成不好的习惯，同时也会造成程序的可读性降低。所以，应该对应参数名称来写入参数注释。