如何写java文档注释
时间：2019-04-29 03:17:54 来源:igfitidea点击:
在软件编程中，生成源代码文档很重要，因为：
我们将对包含许多类或模块的复杂Java项目有一个清晰的了解；
在以后，我们将能够理解所做的操作，以便我们可以修改、添加或删除它。
对于Java应用程序，文档通常以HTML格式以归档文件或.chm的形式提供。
为了获得高效的源代码文档，JavaDoc项目是使用JDK（Java开发工具包）中的工具javadoc.exe文件根据源代码注释自动生成的 .
要生成JavaDoc文档，必须根据某些规则定义源代码注释：
JavaDoc注释块以
/**开始JavaDoc注释块以
*/结尾；按照惯例，JavaDoc注释的行以
*开头；在生成JavaDoc文档时，忽略注释开头的*或空格；
注释是为方法或类生成文档；
因为Javadoc文档是HTML格式的，所以注释可以包含用于格式化内容的HTML标记（例如 <br> 表示移动到下一行）
对于类或方法的特殊属性，有一些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文件：
/**
* Java class example
* The class illustrates how to write comments used to generate JavaDoc documentation
*
* @author theitroad
* @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注释。
如果我们编写此方法：
public int add2(int val1, int val2)
{
return val1+val2;
}
然后在 Source源菜单中点击 Generate Element Comment生成元素注释（Alt+Shift+J）。它将自动生成一个注释块：
/**
* @param val1
* @param val2
* @return
*/
public int add2(int val1, int val2)
{
return val1 + val2;
}
