1. 首页
  2. 博客
  3. 如何写java文档注释

如何写java文档注释

在软件编程中，生成源代码文档很重要，因为：

  1. 我们将对包含许多类或模块的复杂Java项目有一个清晰的了解；

  2. 在以后，我们将能够理解所做的操作，以便我们可以修改、添加或删除它。

对于Java应用程序，文档通常以HTML格式以归档文件或.chm的形式提供。

为了获得高效的源代码文档，JavaDoc项目是使用JDK（Java开发工具包）中的工具javadoc.exe文件根据源代码注释自动生成的 .

要生成JavaDoc文档，必须根据某些规则定义源代码注释：

  1. JavaDoc注释块以/**开始

  2. JavaDoc注释块以*/结尾；

  3. 按照惯例，JavaDoc注释的行以*开头；

  4. 在生成JavaDoc文档时，忽略注释开头的*或空格；

  5. 注释是为方法或类生成文档；

  6. 因为Javadoc文档是HTML格式的，所以注释可以包含用于格式化内容的HTML标记（例如 <br> 表示移动到下一行）

  7. 对于类或方法的特殊属性，有一些Javadoc标记：

JavaDoc标签 含义 描述
@see 关联类的名称 Class, method
@author 作者 Class
@version 版本 Class
@param 输入的参数 Method
@return 返回值 Method
@exception 产生的异常 Method
@throws 抛出异常 Method
@deprecated 将元素定义为已弃用 Class, method
@since 从哪个API版本开始包含此方法（类） Class, method

@deprecated 用于编译器生成警告信息。

为了提高效率，可以使用IDE、NetBeans（右键单击项目名称，然后选择Generate JavaDoc）或Eclipse（）生成JavaDoc文档，而无需使用javadoc.exe文件以及命令行。

比如，对于MyClass.java文件：

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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
/**
* Java class example
* The class illustrates how to write comments used to generate JavaDoc documentation
*
* @author igiftidea
* @version 1.2.0
*/
public class MyClass {
/**
*
* Simple method.
* <br />
* The method prints a received message on the Console
*
* @param message String variable to be printed
* @see MyClass
* @deprecated
* @since version 1.00
*/
public void MyMethod(String message)
{
System.out.printf(message);
}
/**
*
* Simple method example.
* The method prints a received message on the Console
*
* @param message String variable to be printed
* @since version 1.00
*/
public void printMessage(String message)
{
System.out.printf(message);
}
/**
*
* Simple method example.
* <br />
* The methods adds 2 numbers and return the result
*
* @param val1 the first value
* @param val2 the second value
* @return sum between val1 and val2
* @since version 2.00
*/
public int add(int val1, int val2)
{
return val1+val2;

通过在Netbeans 或者Eclipse中生成JavaDoc（右键单击项目名称，然后选择generate javadoc）。

使用Eclipse自动生成文档注释

如果我们使用Eclipse进行开发，IDE还可以为类或方法自动生成JavaDoc注释。

如果我们编写此方法：

1
2
3
4
public int add2(int val1, int val2)
{
return val1+val2;
}

然后在 Source源菜单中点击 Generate Element Comment生成元素注释（Alt+Shift+J）。它将自动生成一个注释块：

1
2
3
4
5
6
7
8
9
10
11
12
/**
* @param val1
* @param val2
* @return
*/
public int add2(int val1, int val2)
{
return val1 + val2;
}

原文链接：https://codingdict.com/

热门标签