大家好，欢迎来到IT知识分享网。
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 {
//……
}
IT知识分享网
2、构造方法的注释
IT知识分享网/**
*
* @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、属性、字段、全局变量的注释
IT知识分享网/**
* (说明内容)
*/
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
希望对读者有帮助！转载请注明出处！
免责声明：本站所有文章内容,图片，视频等均是来源于用户投稿和互联网及文摘转载整编而成，不代表本站观点，不承担相关法律责任。其著作权各归其原作者或其出版社所有。如发现本站有涉嫌抄袭侵权/违法违规的内容,侵犯到您的权益，请在线联系站长,一经查实,本站将立刻删除。 本文来自网络,若有侵权，请联系删除，如若转载，请注明出处：https://yundeesoft.com/7595.html
