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;
 }
}