代码形象——javadoc注释规范

javadoc注释规范

备注：本文结合了许多篇文章的内容加上自己的理解和经验，将很多零散的知识点，总结和统一整理与此。

你必须写注释而且按照项目规范来的写注释的理由

而且需要了解的是，java doc编译生成的文档是html格式的，所以，我们就得遵循一些规范，不至于生成的文档杂乱无章。

要注意的是，生成的文档是 HTML 格式，而这些 HTML 格式的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入＜br＞，如果要分段，就应该在段前写入＜p＞。

因此，格式化文档，就是在文档注释中添加相应的 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.

前导的 * 号允许连续使用多个，其效果和使用一个 * 号一样，但多个 * 号前不能有其它字符分隔，否则分隔符及后面的 * 号都将作为文档的内容。

那么，哪些地方需要写注释？

（1）类和接口

（2）构造方法

（3）普通方法（实体类对象的setter、getter方法不用注释）

（4）全局变量

（5）字段、属性

特殊注释

（1）典型算法

（2）在代码不明晰处

（3）在代码修改处加上修改标识注释

（4）在循环和逻辑分支组成的代码中注释

（5）为他人提供的接口必须详细注释

注释的格式、类型

单行注释：//……

块注释：/*……*/

文档注释：/……*/

而javadoc，顾名思义，则是更多的是针对文档注释，本文也将大部分讲文档注释的java规范，那么，我们首先要了解，javadoc里的标记

Tag & Parameter	Usage	Applies to	Since
@author name	Describes an author. 描述作者	Class, Interface
@version version	Provides version entry. Max one per Class or Interface. 版本条目，每个类或接口最多有一个	Class, Interface
@since since-text	Describes since when this functionality has existed. 描述这个功能块从何时有的	Class, Interface, Field, Method
@see reference	Provides a link to other element of documentation. 提供链接到其他文档元素的链接	Class, Interface, Field, Method
@param name description	Describes a method parameter. 描述一个参数	Method
@return description	Describes the return value. 描述返回值	Method
@exception classname description @throws classname description	Describes an exception that may be thrown from this method. 描述该方法可能抛出的异常	Method
@deprecated description	Describes an outdated method. 描述一个过期的方法	Method
{ @inheritDoc}	Copies the description from the overridden method. 从复写方法出拷贝来得描述	Overriding Method	1.4.0
{ @link reference}	Link to other symbol. 连到其他的引用	Class, Interface, Field, Method
{ @value}	Return the value of a static field. 返回一个静态作用域的值	Static Field	1.4.0

下面为参考举例，可在eclipse或myeclipse中设置模板，下文有介绍（注释一定要紧跟者类、方法、属性）

1、类和接口的注释

/ * * @ClassName Test_Singleton.java * @Description TODO * @Author 先 * @Time 2017年3月25日 下午3:12:43 * */ public class Test { //…… }

2、构造方法的注释

/ * * @Title: Test * @Description: TODO */ public Test(){ }

3、方法的注释

/ * * @Title: test * @Description: TODO * @param para1 * @param para2 * @return String */ public String test(Integer para1,String para2){ return para2; }

/ * (说明内容) */ private String name; / * (说明内容) */ private final Integer id;

一些标记的相关使用说明

1、@see

@see 的句法有三种：

@see 类名

@see #方法名或属性名

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

/ * @see java.lang.String * @see #str * @see #str() * @see #main(String[]) * @see java.lang.Object#toString() */ public classTestJavaDoc { private Stringstr; public voidstr(){ } public staticvoid main(String[] args){ } }

生成的文档的相关部分如下图

代码形象——javadoc注释规范

2、@author、@version

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

这两个标记的句法如下：

@author 作者名

@version 版本号

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

/ * @author Fancy * @author Bird * @versionVersion 1.00 * @versionVersion 2.00 */ public classTestJavaDoc {}

生成文档的相关部分如图

代码形象——javadoc注释规范

3. @param、@return 和 @exception

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

@param 参数名参数说明

@return 返回值说明

@exception 异常类名说明

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

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

方法可能抛出的异常应当用@exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 @exception。每个 @exception 后面应有简述的异常类名，说明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的 import 语句确定是写出类名还是类全名。示例如下：

public class TestJavaDoc { / * @param n a switch * @param b excrescent parameter * @return true or false * @return excrescent return * @exception java.lang.Exception throw when switch is 1 * @exception NullPointerException throw when parameter n is null */ public boolean fun(Integer n) throws Exception { switch (n.intValue()) { case 0: break; case 1: throw new Exception("Test Only"); default: return false; } return true; } }

使用 javadoc 编译生成的文档相关部分如下图：

代码形象——javadoc注释规范