JAVADOC注释详解

java注释的分类

1、单行注释：int SUM = 100; //这是一个单行注释

2、多行注释：

*这是一个多行注释
*/

3、文档注释：

/**

*这是一个文档注释

* @return a

java注释和文档注释

作为一个java程序员我们一定都喜欢看官方的开发文档，文档中很详细的包括了类和接口参数方法等信息，并提供了许多类之间的关系等等。java的开发文档是由HTML页面进行展示的，但是用了很久我们才知道，这些文档实际上不是一点一点的写出来的，我们自己也可以进行生成。

安装了 JDK 之后，安装目录下有一个 src.jar 文件或者 src.zip 文件，它们都是以 ZIP 格式压缩的，可以使用 WinZip 解压。解压之后，我们就可以看到分目录放的全是 .java 文件。是了，这些就是 Java 运行类的源码了，非常完整，连注释都写得一清二楚，我们可以对比这里的注释和开发文档，以java.util.List为例：这是官网API截图

接下来再看一下源码信息：

package java.util;

/**
* An ordered collection (also known as a sequence). The user of this
* interface has precise control over where in the list each element is
* inserted. The user can access elements by their integer index (position in
* the list), and search for elements in the list.
*
* Unlike sets, lists typically allow duplicate elements. More formally,
* lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
* such that <tt>e1.equals(e2)</tt>, and they typically allow multiple
* null elements if they allow null elements at all. It is not inconceivable
* that someone might wish to implement a list that prohibits duplicates, by
* throwing runtime exceptions when the user attempts to insert them, but we
* expect this usage to be rare.
*
* The <tt>List</tt> interface places additional stipulations, beyond those
* specified in the <tt>Collection</tt> interface, on the contracts of the
* <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
* <tt>hashCode</tt> methods. Declarations for other inherited methods are
* also included here for convenience.

.....

* @param <E> the type of elements in this list
*
* @author Josh Bloch
* @author Neal Gafter
* @see Collection
* @see Set
* @see ArrayList
* @see LinkedList
* @see Vector
* @see Arrays#asList(Object[])
* @see Collections#nCopies(int, Object)
* @see Collections#EMPTY_LIST
* @see AbstractList
* @see AbstractSequentialList
* @since 1.2
*/

public interface List<E> extends Collection<E> {

.....

}

可以看出来，java的开发文档其实就是在将代码中的注释按照相应的规则整理出来的，这对程序的阅读者和使用者十分关键，由此可见，学会写注释对于一个程序员来说是十分关键的，也能体现一个程序员的水平。

文档和文档注释的格式

文档注释可以用在类，方法，属性上进行说明。文档内部要注意细节问题。

文档的生成格式是HTML，而HTML中的格式标识符并不是javadoc加的，而是我们在写注释的时候写上去的，比如，需要换行的时候，不是敲入一个换行符，而是写一个 ，如果要分段，需要使用

因此，格式化文档，就是在注释中添加HTML相应的标签。

文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。如：
/**
* This is first line. ＜br＞
* This is second line. ＜br＞
This is third line.
*/

编译输出后的HTML源码则是：
This is first line. ＜br＞
This is second line. ＜br＞
This is third line.

*注意，文档说明后面需要紧跟类、接口、方法或属性

文档注释的三个组成部分

第一个部分作为类、接口、方法、属性的简述。简述在文档注释的最前面，简述的末尾需要加上一个点号“.”，就是使用点号来分割文档注释，有的时候点号会出现错误，我们就用作为第二部分的开头进行分割。

第二部分就是注释的详细部分，对属性或方法等进行详细的说明，在格式上没有什么特殊的要求。

第三部分是特殊说明部分，这个部分包括声明作者、版本说明、参数说明、参考说明、返回值说明。抛出异常说明等，这一部分最好和第二部分有一个空行，不然可能会出现错误。

常用的javadoc标记及其使用

1、@see的使用：

@see的句法有三种

①、@see 类名

类名可以根据需要只写出类名，如String，或者写出全名：java.lang.String，但需要注意的是，在用类名的时候需要这个java源文件中import这个类，否则只能用全名。

②、@see#方法名或属性名

如果是属性名，则只需要写出属性名即可，如果是方法名，则需要写出方法名以及参数类型，如果没有参数，也需要写出一对括号。

如：@see #contains(Object)、@see #count()、@see number

③、@see 类名#方法名或属性名

如：@see Object#equals(Object)、@see java.lang.String#toString()

2、@author、@version的使用：

这两个标记分别指明作者和版本号，缺省情况下javadoc自动将其忽略，但命令行开关-author和-version可以修改个功能，使其包含的信息流输出，这两个标记都可以多个使用，但是版本号只有第一个出现的有效。

3、@param、@return和@exception的使用：

这三个标记只能用于方法，@param描述参数，@return描述返回值，@exception描述抛出异常，用法如下：

①、@param 参数名参数说明

每一个@param都只能描述一个方法的参数，可以多次使用。

②、@return 返回值说明

一个方法只能使用一个@return，如果有多个，javadoc会发出警告，并且只有第一个声明的有效。

@exception 异常类名异常说明

@exception可以多次使用，并且异常的类名需要注意在java原文件中是否有导入，如果没有需要写类全名。

如：

/**
 * test 方法的简述，这个方法用于做javadoc的测试.
 * test方法的详细说明，这里是详细说明的第一行 
 * test方法详细说明的第二行
 *
 * @param a firstnum
 * @param b lastnum
 * @exception java.lang.ArithmeticException throw when b is 0
 * @return 返回值为a/b
 */
 public int test(int a,int b) throws java.lang.ArithmeticException{
 return a/b;
 }

*注意：写文档注释的时候应该注意正确的匹配参数，javadoc在一定程度上不会检查我们写的文档注释，如果写错误可能会造成一些困惑

javadoc命令

用法：javadoc [options] [packagenames] [sourcefiles]

选项：

-public 仅显示 public 类和成员
    -protected 显示 protected/public 类和成员 (缺省)
    -package 显示 package/protected/public 类和成员
    -private 显示所有类和成员
    -d ＜directory＞输出文件的目标目录
    -version 包含 @version 段
    -author 包含 @author 段
    -splitindex 将索引分为每个字母对应一个文件
    -windowtitle ＜text＞文档的浏览器窗口标题

javadoc可以给定包列表进行编译，如：javadoc xcg xcg.test

也可以给出源文件列表，如：javadoc xcg/test/JavaDocTest.java

以上两种方式的编译结果不同，用包列表生成的文档被框架分成了三个部分：包列表、类列表和类说明

在eclipse或myeclipse中可以使用file->Export->javadoc可以进行手动输出javadoc，需要注意生成的时候可能会出现错误: 编码GBK的不可映射字符，这时就需要在流程的最后一步加上一句话控制字符：-encoding UTF-8 -charset UTF-8，如：

注释规范

1、注释原则：

①注释形式统一

②注释内容准确简单

2、注释条件：

①基本注释（必须加）：类、接口的注释、构造函数的注释、方法的注释、全局变量的注释、字段/属性的注释

②特殊必须加的注释：典型算法、代码不清晰易懂时加注释、修改代码时需要加注释、在循环分支需要加注释、为他人提供的接口等信息必须加注释。