Java基础语法：JavaDoc

---

一、简介

• JavaDoc是一种将注释生成HTML文档的技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
• 也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

---

二、注释标签

常用标签列表：

1. 作者：@author
2. 版本号：@version
3. 需要使用的JDK最早版本：@since
4. 参数：@param
5. 返回值：@return
6. 抛出的异常：@throws

注意：

• 注释标签必须在JavaDoc注释中使用。
• JavaDoc注释可以用在类、变量和方法上。
• JavaDoc注释在开始的'/**'之后，第一行或几行是关于类、变量和方法的主要描述。
• 之后，你可以包含一个或多个各种各样的注释标签。每一个注释标签必须在一个新行的开始,或者在一行的开始紧跟星号后面。
• 多个相同类型的标签应该放成一组。例如，如果你有三个'@param'标签，可以将它们一行接一行的放在一起。

示例：

/**
 * 这是一个方法
 *
 * @author conyoo
 * @version 1.0
 * @since 1.8
 * @param parameter 一个参数
 * @return 一个返回值
 * @throws Exception 一个异常
 */
public String test(String parameter) throws Exception {
    return parameter;
}

---

三、javadoc命令

• 开发者可以在命令行中使用'javadoc'命令，来生成JavaDoc文档。
• 'javadoc'命令既可以处理包，也可以处理java源文件。

语法：javadoc [options] [packagenames] [sourcefiles] [@files]

注意：

• 设置编码参数'-encoding'和字符集参数'-charset'为'UTF-8'，可以解决中文乱码问题。
• 'javadoc'命令不递归作用于子包，所以处理包时不允许对包名使用通配符，必须列出希望建立文档的每一个包。
• '[@files]'：为了简化javadoc命令，你可以把需要建立文档的文件名和包名放在一个或多个文本文件中。

示例：

D:\workspace\demo\src\com\cnblogs\www\example>javadoc -encoding UTF-8 -charset UTF-8 HelloWorld.java

---