java基础 - 注释标签的使用

以前写代码的时候喜欢使用多行注释书写注释，大致的看到默认的标签的英文单词，就依照英文单词的表面意思书写注释，今天我仔细查阅的资料后，才发现，之前写的都是错误的，为此，我特意将此记录下来，时刻提醒自己，不要犯相同的错误

1.@see：引用其他类

@see 标签允许用户引用其他类的文档，javadoc会在其生成HTML文件中，通过@see标签链接到其他的文档。

格式：

@see classname

@see fully-qualified-classname

@see fully-qualified-classname#method-name

这些标签都会在文档中生成一个具有超链接的“See Also”条目。但是javadoc不会检查链接有的有效性。

2.{@link package.class#member label}

该标签与@see很相似，只是它用于行内，并且是用“label”作为超链接文本而不是用“See Also”

3.{@docRoot}

该标签生产到文档根目录的相对路径，用于文档树结构页面的显示超链接

4.{@inheritDoc}

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5.@version

该标签的格式如下：

@version version-information

本标签用于书写版本信息

6.@author

该标签格式如下：

@author author-information

本标签用于书写作者信息

7.@since

该标签允许你指定程序代码最早使用的版本，可以在html文档中看到它被用来指定所有的jdk版本情况

8.@param

该标签用于方法中，格式如下：

@param parameter-name description

parameter-name 是方法列表中的标示符，description 是可延续数行的文本

9.@return

该标签用于方法文档中，格式如下：

@return description

其中description用于描述返回值的含义，可以延续数行

10.@throws

此标签针对可能出现的抛出的异常进行描述说明，格式如下：

@throws fully-qualified-class-name description

fully-qualified-class-name为异常的类的名字及路径，description为异常说明

11.@deprecated

该标签用于指出一些旧特性已经由新特性所取代，建议用户不要再使用这些旧特性，因为在不久的将来他们很可能被删除，如果使用此标签，则会引起编译器发出警告，在javase5中，此标签已经被@Deprecated注解所替代

 

 

综上所述，来看一下具体示例吧：

 package net.test.test;
import java.io.IOException;
import com.me.mapping.Mapping;
/**
 * {@docRoot}
 * @author Dike Li
 * @since JDK 1.6
 * @version 1.0
 */
public class Test implements Mapping{
 
 /**
  * @throws IOException 
  * @see com.me.Entity.Entity
  */
 public void testLabel() throws IOException{
  
 }
 
 /**
  * @see com.me.Entity.Entity#getName
  */
 public void testSeeMethod(){
  
 }
 
 /**
  * {@link net.test.test.Test#testLink}
  */
 public void testLink(){
  
 }
 
 /**
  * {@inheritDoc}
  */
 @Override
 public void add() {
  // TODO Auto-generated method stub
  
 }
 
 /**
  * 返回相加的值
  * @param value1 参数1
  * @param value2 参数2
  * @return 返回相加的值
  * @deprecated 此方法已经被替换
  */
 public String back(String value1,String value2){
  return value1 + value2;
 }
}