java文档注释的基本认识

Java 程序员都应该知道，JDK 开发最好的帮助信息就来自 SUN 发布的 Java 文档。它分包分类地提供了各方法、属性的帮助信息，具有详细的类树信息、索引信息等，并提供了许多相关类之间的关系，如继承、实现接口、引用等。

Java 文档全是由一些 html 文件组织起来的，在 SUM 的站点上可以下载它们的压缩包。其实这些文档我们可以自己生成。

安装了 JDK 之后，安装目录下有一个 src.jar 文件或者 src.zip 文件，它们都是以 ZIP 格式压缩的，可以使用 WinZip 解压。解压之后，我们就可以看到分目录放的全是 .java 文件，这些就是 Java 运行类的源码了，非常完整，连注释都写得一清二楚。

仔细比对一下 .java 源文件中的文档注释 (/** … /) 和 Java 帮助文档的内容，你会发现它们就是一样的。再仔细一点，你会发现 .java 源文件中的注释还带有一些 HTML 标识，如 ＜B＞、＜BR＞、＜Code＞ 等，在 Java 文档中该出现这些标识的地方，已经按标识的的定义进行了排版。

Javadoc标记是插入文档注释中的特殊标记，它们用于标识代码中的特殊引用。javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成。记住了，三个部分——@、标记类型、专用注释引用。虽然 @ 和 标记类型之间有时可以用空格符分隔，但是推荐将它们紧挨着写，以减少出错机会。

常用的标签如下：

• @author    作者标识
• @version    版本号
• @date  创建时间
• @param    说明方法的参数
• @return    对函数返回值的描述
• @throws    构造函数或方法会抛出的异常
• @exception    同@throws
• @deprecated    标识过期API（为了保证兼容性，仍可用，但不推荐用）
• @since     API在什么程序的什么版本后开发支持。
• @see    引用，查看相关的内容，如类，方法，变量等，必须顶头写
• {@link 包.类#成员}    引用，同@see，但可写在任意位置
• {@value}    对常量注释，如果其值包含在文档中，通过改标签引用常量的值
• {@code}   如果文档注释中涉及到代码，就需要使用这个标记将代码解析成文本 {@code codeContent}
• @inheritDoc    用于继承父类中的Javadoc，父类的文档注释，被继承到了子类

1、@see 的使用

@see 的句法有三种： 

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

第二个句法中没有指出类名，则默认为当前类。所以它定义的参考，都转向本类中的属性或者方法。而第三个句法中指出了类名，则还可以转向其它类的属性或者方法。 

如果是属性名，则只需要写出属性名即可；如果是方法名，则需要写出方法名以及对应的参数类型，没有参数的方法，需要将括号也写出，比如@see #toString()。

2、@author、@version 说明类

这两个标记分别用于指明类的作者和版本。缺省情况下 javadoc 将其忽略，但命令行开关 -author 和 -version 可以修改这个功能，使其包含的信息被输出。这两个标记的句法如下： 

@author 作者名 
@version 版本号 

其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效，生成的文档中只会显示第一次使用 @version 指明的版本号。如下例 

/** 
* @author Fancy 
* @author Bird 
* @version Version 1.00 
* @version Version 2.00 
*/ 
public class TestJavaDoc { 
} 

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

这三个标记都是只用于方法的。@param 描述方法的参数，@return 描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下： 

@param 参数名 参数说明 
@return 返回值说明 
@exception 异常类名 说明

 每一个 @param 只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用 @param 来描述。 

一个方法中只能用一个 @return，如果文档说明中列了多个 @return，则 javadoc 编译时会发出警告，且只有第一个 @return 在生成的文档中有效。 

方法抛出的异常应当用 @exception 描述。由于一个方法可能抛出多个异常，因此可以有多个 @exception。每个@exception 后面应有简述的异常类名，说明中应指出抛出异常的原因。

4、方法或者类的文字描述

通常，描述都会直接写在文档注释的前几行。

写在类上的文档标注一般分为三段：

• 第一段：概要描述，通常用一句话或者一段话简要描述该类的作用，以英文句号结束
• 第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
• 第三段：文档标注，用于标注作者，创建时间，参阅类等信息

方法上的描述也可以按照这种方式，可以用HTML标签来分段或者分行。比如：

​/** 
* show 方法的简述.
* <p>show 方法的详细说明第一行<br> 
* show 方法的详细说明第二行 
* @param b true 表示显示，false 表示隐藏 
* @return 没有返回值 
*/