javadoc注释规范

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

4、属性、字段、全局变量的注释

/** * (说明内容) */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){   }}

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

2、@author、@version

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

这两个标记的句法如下：   

@author 作者名  

@version 版本号   

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

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

生成文档的相关部分如图

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 编译生成的文档相关部分如下图：

那么，我们该怎么在eclipse或myeclipse中设置这些标记模板呢？

设置注释模板的入口： Window->Preference->Java->Code Style->Code Template

下面是每个comment的设置模板，个人也可以自定义，但是团队开发的话，就需要统一遵循一个

1、文件(Files)注释标签：

2、类型(Types)注释标签（类的注释）：

3、字段(Fields)注释标签：

4、构造方法（constructor）标签：

5、方法( Methods)标签：

6、覆盖方法(Overriding Methods)标签：

7、代表方法(Delegate Methods)标签：

8、getter方法标签：

9、setter方法标签：

另外附上维基百科的java doc规范链接https://en.wikipedia.org/wiki/Javadoc

希望对读者有帮助！转载请注明出处！