Javadoc注释

    java注释文档(javadoc)，是便于提取注释的工具。通过javadoc,文档与代码建立了链接，不再是彼此分离的。大大方便了文档的维护工作。

    javadoc执行之后会输出要提个HTML文件，可以用浏览器查看。这样改工具就使得我们只需创建和维护单一源文件，不需要单独写文档。

语法

    javadoc文档以"/**"开头，"*/"结尾。

示例

   

/** A class comment */
public class Documentation1 {
  /** A field comment */
  public int i;
  /** A method comment */
  public void f() {}
} 

    注意Javadoc只能为public和protected成员进行文档注释，private和包访问成员的注释会被忽略掉 ,这点要注意。

    javadoc可以内嵌HTML标签，如在pre标签之间写代码:

/**
* 
* System.out.println(new Date());
* 
*/

    当然也可以写普通HTML:

/**
* You can even insert a list:
* 

* 
 Item one
* 
 Item two
* 
 Item three
* 
*/

常用javadoc标签

javadoc中又一些特殊的文档标签，用"@"开头的命令，有一些特殊的作用。

如果学习JDK源码，这些会发现这些文档注解经常出现

1.@see:引用其他类,链接到其他文档，格式如下:

    @see classname

    @see fully-qualified-classname

    @see fully-qualified-classname#method-name

    使用后会出现"See Also"条目

2.{@link package.class#member}

    与@see相似，只能用于行内作为超链接标签。不会出现"See Also"

3.{@docRoot}

    链接到文档根路径

4.{@inheritDoc}

    从这个类的父类中继承相关文档到当前文档注释

5.@version

    包含版本信息说明。格式:

    @version version-information

6.@author

    作者信息。格式:

    @author author-information

7.@since

    指定代码最早使用版本

8.@param

    用于方法文档中，说明参数含义。格式:

    @param parameter-name description

9.@return

    用于方法文档中，说明返回值含义。格式:

    @return description

10.@throws

    对异常进行说明。格式:

    @throws fully-qualified-class-name description

11.@deprecated

    指出该特性已经被改进或者被新特性取代，建议用户不要使用这些旧特性，因为将来可能会被删除。

    使用带有此标记的方法，编译器会发出警告。

    现在该注释已经被@Deprecated注解替代