javadoc生成文档的常用标签

在写完JAVA代码后如果单独去维护一份文档感觉非常繁琐,如果我们已经在程序中写上了规范的注释,就可以利用javadoc来自动生成文档。在写注释的时候有几个比较常用的标签,今天在这里记录一下。

为了方便理解,我们先写一个项目,项目中包含两个类:Class1和Class2

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
package info.aviraer.test;

/**
* 这是测试类1
* @author Aviraer
* @version 1.1
*/
public class Class1 {

/**
* 用see标签链接到别的其他类或方法
* @see info.aviraer.test.Class2#method1
*/
public void method1(){

}

/**
* 用param标签标注参数
* 用return标签标注返回值
* @param name 名字
* @return 名字
*/
public String method2(String name){
return name;
}

/**
* 用throws标签标注抛出异常
* @throws Exception 手动抛出异常
*/
public void method3() throws Exception{
throw new Exception("手动抛出异常");
}

/**
* 使用deprecated标签标注不推荐使用的类或方法
* @deprecated
*/
public void method4(){
return;
}
}

1
2
3
4
5
6
7
8
9
10
11
12
package info.aviraer.test;

public class Class2 {

/**
* 这里是Class2的method1
*/
public void method1(){

}

}

这个项目生成的文档如下图,具体效果大家可以参看java官方的文档。

javadoc

mydoc

在以上的两个类中使用了以下7个常用的标签:

  1. @author 用来标注作者
  2. @version 用来标注版本号
  3. @see 用来引用其他类或方法
  4. @param 用来描述参数
  5. @return 用来描述返回值
  6. @throws 用来描述抛出的异常
  7. @deprecated 用来告知当前类或方法不推荐使用