Java文档注释

4.9 文档注释

运行javadoc可以生成HTML文档。

以专用的定界符 /**开始的注释，可以很容易地生成一个文档，并且修改时，重新javadoc可以同步。

详细文档注释

4.9.1 注释的插入

javadoc从下面几个特性中抽取信息：

包
共有类和接口
共有的和受保护的构造器及方法
共有的和受保护的域

每个 /** . . . */ 文档注释在标记之后紧跟着自由格式文本（free-form text)。标记由@开始，如@author 或@param。

4.9.2 类注释

类注释放在import语句之后，类定义之前。

4.9.3 方法注释

每一个方法注释必须放所在方法之前，可以使用下面标记：

@param 变量描述：为当前方法的参数添加描述
@return 描述：可进行多行描述
@throws 类描述：此方法可能抛出异常

/**
* Raises the salary of an employee.
* @param byPercent the percentage by which to raise the salary (e.g. 10 means 10%)
* @return the amount of the raise
*/
public double raiseSalary(double byPercent)
{
 double raise = salary * byPercent / 100;
 salary += raise;
 return raise;
}

4.9.4 域注释

只需要对公有域（通常指的是静态常量）建立文档。

4.9.5 通用注释

下面的注释可用在类文档的注释中：

@author 姓名：作者
@version 文本：对当前版本的描述
@since 文本：对引入特性的版本的描述
@deprecate 文本：此标记表示不再使用这个部分
@see 引用：超链接

4.9.6 包和概述注释

可以将各种注释用/**. . . */文档注释界定。

但是，要生成单独的文件需要：

提供一个以package.html命名的文件。<body>. . . </body>之间的文件会被抽取出来。
提供一个以package-info.java的文件。文件中包语句之后，紧跟/**. . . */注释，不需要其他多余的注释和代码。
也可以为所以源文件提供一个概述性的注释，写在overview.html文件中，这个文件位于所有源文件的父目录中。

4.9.7 注释的抽取

假设HTML文件被放在docDirectory下。执行步骤如下：

运行命令。

//如果是一个包
javadoc -d docDirectory nameOfPackage

//多个包
javadoc -d docDirectory nameOfPackage1 nameOfPackage2. . . 

//默认包
Javadoc -d docDirectory *.java

可以使用多种形式的命令对Javadoc程序进行调整。

【Java补充】 Java文档注释