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程序进行调整。
网友评论