Java文檔注釋
4.9 文檔注釋
運行javadoc可以生成HTML文檔。
以專用的定界符 /**開始的注釋，可以很容易地生成一個文檔，并且修改時，重新javadoc可以同步。
4.9.1 注釋的插入
javadoc從下面幾個特性中抽取信息：
- 包
- 共有類和接口
- 共有的和受保護的構(gòu)造器及方法
- 共有的和受保護的域
每個 /** . . . */ 文檔注釋在標記之后緊跟著自由格式文本（free-form text)。標記由@開始， 如@author 或@param。
4.9.2 類注釋
類注釋放在import語句之后，類定義之前。
4.9.3 方法注釋
每一個方法注釋必須放所在方法之前，可以使用下面標記：
- @param 變量描述：為當前方法的參數(shù)添加描述
- @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 域注釋
只需要對公有域（通常指的是靜態(tài)常量）建立文檔。
4.9.5 通用注釋
下面的注釋可用在類文檔的注釋中：
- @author 姓名：作者
- @version 文本：對當前版本的描述
- @since 文本：對引入特性的版本的描述
- @deprecate 文本：此標記表示不再使用這個部分
- @see 引用：超鏈接
4.9.6 包和概述注釋
可以將各種注釋用/**. . . */文檔注釋界定。
但是，要生成單獨的文件需要：
- 提供一個以package.html命名的文件。<body>. . . </body>之間的文件會被抽取出來。
- 提供一個以package-info.java的文件。文件中包語句之后，緊跟/**. . . */注釋，不需要其他多余的注釋和代碼。
- 也可以為所以源文件提供一個概述性的注釋，寫在overview.html文件中，這個文件位于所有源文件的父目錄中。
4.9.7 注釋的抽取
假設(shè)HTML文件被放在docDirectory下。執(zhí)行步驟如下：
切換到想要生成文檔的源文件目錄。
-
運行命令。
//如果是一個包 javadoc -d docDirectory nameOfPackage //多個包 javadoc -d docDirectory nameOfPackage1 nameOfPackage2. . . //默認包 Javadoc -d docDirectory *.java
可以使用多種形式的命令對Javadoc程序進行調(diào)整。
