Javadoc
< Java 编程
| 导航 Javadoc & 注解 主题： |
Java 允许用户使用特定的注释语法来记录类和成员。
文档注释用斜杠-星号-星号和星号-斜杠（即 /** ... */）包围。文档采用 HTML 格式。
|
代码清单 8.1：Example.java
/**
* A class to give an <b>example</b> of HTML documentation.
*/
public class Example {
/** ...Documentation of a member with the type integer named example... */
public int example;
}
|
文档注释放置在注释实体（类、构造函数、方法、字段）的正上方。
在文档注释中，第一部分是用 HTML 格式描述的文本。第二部分是名称以“@”符号开头的特殊属性列表
|
代码段 8.1：文档注释。
/**
* Get the sum of two integers.
* @param a The first integer number.
* @param b The second integer number.
* @return The value of the sum of the two given integers.
*/
public int sum(int a, int b) {
return a + b;
}
|
获取两个整数的总和。- sum 方法的描述。
@param a 第一个整数。- 方法参数 a 的描述属性。
@param b 第二个整数。- 方法参数 b 的描述属性。
@return 给定两个整数的总和的值。- 方法返回值的描述属性。
以下是非详尽的特殊属性列表
| 属性和语法 | 在... 的注释中 | 描述 |
|---|---|---|
| @author 作者 | 类 | 类的作者姓名。 |
| @version 版本 | 类 | 类的版本。 |
| @deprecated 描述 | 类、构造函数、方法、字段 | 将实体标记为已弃用（旧版本），说明原因以及用什么替换它。 如果用此属性标记为已弃用的实体，编译器会发出警告。 |
| @see 引用 | 类、构造函数、方法、字段 | 在“另请参见”部分添加链接。 |
| @param id 描述 | 构造函数和方法 | 描述方法参数。 |
| @return 描述 | 方法 | 描述方法返回值。 |
| @exception 类型 描述 | 构造函数和方法 | 描述抛出指定类型异常的原因（throws 子句）。 |
另请参见 注解，自 Java 5 起。
JDK 提供了一个名为 javadoc 的工具，允许生成良好注释类的文档。不带参数的 javadoc 命令给出命令的完整语法。
例如：对于名为 Example 的类，定义在名为 org.wikibooks.en 的包中，文件名为 C:\ProgJava\org\wikibooks\en\Example.java
|
|
代码清单 8.2：Example.java
package org.wikibooks.en;
/**
* An example class.
*/
public class Example {
/**
Get the sum of two integers.
@param a The first integer number.
@param b The second integer number.
@return The value of the sum of the two given integers.
*/
public int sum(int a, int b) {
return a + b;
}
}
|
可以使用以下命令在特定文件夹（例如 C:\ProgDoc）中生成文档
|
命令 8.1：文档生成
$ javadoc -locale en_US -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.wikibooks.en |
该命令的选项描述如下
-locale en_US- 以美式英语生成文档。
-use- 创建有关类和包使用的页面。
-classpath C:\ProgJava- 编译类（*.class）的路径。
-sourcepath C:\ProgJava- 源代码类（*.java）的路径。
-d C:\ProgDoc- 必须生成文档的路径。
org.wikibooks.en- 要记录的包的名称。可以指定多个包，或一个或多个类名，只记录这些类。
包的描述页面会从名为 package.html 的文件中复制描述文本，该文件应放置在给定的文件夹中。在本例中，应在文件 C:\ProgJava\org\wikibooks\en\package.html 中记录包。
自 Java 5[1] 起，package.html 文件可以用名为 package-info.java 的特殊 Java 文件替换，该文件只包含由文档注释前缀的包声明。
|
|
代码清单 8.3：C:\ProgJava\org\wikibooks\en\package-info.java
/**
* This fake package is used to illustrate the Java wikibook.
* at <i>en.wikibooks.org</i>.
*/
package org.wikibooks.en;
|
