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 e1 and e2
 * such that e1.equals(e2), 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 List interface places additional stipulations, beyond those
 * specified in the Collection interface, on the contracts of the
 * iterator, add, remove, equals, and
 * hashCode methods.  Declarations for other inherited methods are
 * also included here for convenience.

.....

 * @param 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 extends Collection {

.....

}

    可以看出来，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、注释条件：

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

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