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

  • 本站文章除注明转载外,均为本站原创或者翻译。
  • 本站文章欢迎各种形式的转载,但请18岁以上的转载者注明文章出处,尊重我的劳动,也尊重你的智商;
  • 本站部分原创和翻译文章提供markdown格式源码,欢迎使用文章源码进行转载;
  • 本博客采用 WPCMD 维护;
  • 本文标题:【转】探索ASDoc:标签篇-@see标签
  • 本文链接:http://zengrong.net/post/1196.htm

转自云の部族


@see标签

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

@see 引用 [显示文本]

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

/**
* 输出信息
* @param firstParam 需要输出信息的对象
* @param aaaaaaa 输出格式
* @return 该函数无返回值
* @example 下面例子是通过print函数输出信息。
*
* var i:int=1;
* var demo:Demo=new Demo();
* demo.print(demo.getString(),"%s");
*  * */
public function print(info:Object,format:String):void{
}
/**
* 返回一个字符串
* @return 返回一个字符串
* @see #print()
**/
public function getString():String{
return "demo";
}

生成文档后,输出样式如下:

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

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

/**
* 输出信息
* @param firstParam 需要输出信息的对象
* @param aaaaaaa 输出格式
* @return 该函数无返回值
* @example 下面例子是通过print函数输出信息。
* 
* var i:int=1;
* var demo:Demo=new Demo();
* demo.print(demo.getString(),"%s");
* 
* */
public function print(info:Object,format:String):void{
}
/**
* 返回一个字符串
* @return 返回一个字符串
* @see #print() 具体用法请参考print方法
**/
       public function getString():String{
       return "demo";
}

然后进行文档生成,效果如下图所示:

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

/**
* 返回一个字符串
* @return 返回一个字符串
* @see #print() 具体用法请参考print方法
**/
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方法。代码如下:

/**
* 返回一个字符串
* @return 返回一个字符串
* @see #print() 具体用法请参考print方法
* @see Demo2#getString()
**/
public function getString():String{
     return "demo";
}

然后生成文档,效果如下图所示:

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

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