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

2010-12-07 [1196] technology as3 asdoc

转自云の部族

@see标签

@see标记的作用是生成一个参考引用。在一些情况下某些类、属性或者方法在其他地方有进行说明或者引用，这时候我们可以通过此标记来引用此例子来进行说明。其书写格式如下：

@see 引用 [显示文本]

为了更好的理解其含义，我将在原来的print方法中引入getString方法，然后getString方法中则采用@see标记来进行参考引用。

 1/**
 2* 输出信息
 3* @param firstParam 需要输出信息的对象
 4* @param aaaaaaa 输出格式
 5* @return 该函数无返回值
 6* @example 下面例子是通过print函数输出信息。
 7*
 8* var i:int=1;
 9* var demo:Demo=new Demo();
10* demo.print(demo.getString(),"%s");
11*  * */
12public function print(info:Object,format:String):void{
13}
14/**
15* 返回一个字符串
16* @return 返回一个字符串
17* @see #print()
18**/
19public function getString():String{
20return "demo";
21}

生成文档后，输出样式如下：

如图所示，getString方法下多出了一栏See also的信息，在这栏里面就有刚才所写的print方法的引用。可能你会问@see标记中的引用部分应该怎么写呢？其实对于引用类内部方法来说是通过锚点来实现的，所以引用部分就是填写一个锚点（如果要引用到当页的锚点，学个HTML的朋友就知道是用#锚点名称）。其实用ASDoc生成的方法和属性都带有一个锚点的，其规律就是方法的锚点就是方法名称()（一定要加括号），属性的锚点就是属性名称。下图就是的状态栏中就有显示一个方法的锚点

如图所示，Demo.html后面的就是锚点名称了。如果不知道的朋友可以通过生成一份文档来观察一下。那如果要引用其他类的方法呢？呆会再作演示，现在来看一下上例中的See also一栏下面的只是一个纯粹的方法名称，如果想要一些更加详细的说明，可以在应用部分加入提示性文字。我们把上面的例子改一下，代码如下：

 1/**
 2* 输出信息
 3* @param firstParam 需要输出信息的对象
 4* @param aaaaaaa 输出格式
 5* @return 该函数无返回值
 6* @example 下面例子是通过print函数输出信息。
 7* 
 8* var i:int=1;
 9* var demo:Demo=new Demo();
10* demo.print(demo.getString(),"%s");
11* 
12* */
13public function print(info:Object,format:String):void{
14}
15/**
16* 返回一个字符串
17* @return 返回一个字符串
18* @see #print() 具体用法请参考print方法
19**/
20       public function getString():String{
21       return "demo";
22}

然后进行文档生成，效果如下图所示：

可以看到引用部分不再是换成了我们添加的文本了。其中官方文档中还提到一个@see标记的参数是不能包含HTML格式的字符的。为了验证这个说法，我做了一下实验，把刚才的例子中的说明文字加上了一个 <b> 加粗字体的标记，如下所示：

1/**
2* 返回一个字符串
3* @return 返回一个字符串
4* @see #print() 具体用法请参考print方法
5**/
6public function getString():String{
7        return "demo";
8}

然后进行文档生成时出现错误了，其提示说不能使用HTML格式，如下图所示：

对于如果一个类、方法或属性中有多个参考引用的地方我们可以使用多个@see来进行引用，这是ASDoc中所允许的。基本上就@see标记在类内引用就讲到这里，对于如何引用其他类的元素现在来通过例子说明一下。

首先新建一个类，代码如下：

 1package{
 2       public class Demo2 extends Object{
 3              public function Demo2():void{
 4              }
 5             
 6              public function getString():String{
 7                     return "Demo2";
 8              }
 9       }
10}

现在用Demo类中的getString方法来引用Demo2类中的getString方法。代码如下：

1/**
2* 返回一个字符串
3* @return 返回一个字符串
4* @see #print() 具体用法请参考print方法
5* @see Demo2#getString()
6**/
7public function getString():String{
8     return "demo";
9}

然后生成文档，效果如下图所示：

可以看到Demo2的getString()方法被正确引用到了。根据笔者总结，对于@see标记的引用参数的写法应该是(分别对于类、方法和属性)：

  • 包路径.类名称
  • 包路径.类名称#方法名称()
  • 包路径.类名称#属性名称
  • 如果是类内的方法则可以省略包路径.类名称部分。