Java 简明教程
Java - Documentation using JavaDoc tool
本章重点是解释 Javadoc。我们将了解如何使用 Javadoc 来生成 Java 代码的有用文档。
Java 文档可以使用 javadoc 工具生成。目前,它会生成 html 4.0 格式的文档。从 Java 9 开始,我们可以在命令行参数中使用 -html5 选项生成 html 5 格式的文档。
What is Javadoc?
Javadoc 是一种附带 JDK 的工具,用于从 Java 源代码(它需要一个预定义格式的文档)中生成 HTML 格式的 Java 代码文档。
以下是一个简单的示例,其中 /…./ 内部的是 Java 多行注释。类似地,// 前面的行是 Java 单行注释。
Example
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}
Hello World!
你可以在描述部分包含所需的 HTML tags。例如,下面的示例使用 <h1>….</h1> 作为页眉,并使用 <p> 用于创建分段符 −
Example
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}
Hello World!
The javadoc Tags
javadoc 工具识别以下标记:
Tag |
Description |
Syntax |
@author |
添加类的作者。 |
@author name-text |
{@code} |
以代码字体显示文本,不将文本解释为 HTML 标记或嵌套 javadoc 标记。 |
{@code text} |
{@docRoot} |
代表从任意已生成页面到已生成文档根目录的相对路径。 |
{@docRoot} |
@deprecated |
添加注释,表明此 API 不应再被使用。 |
@deprecated deprecatedtext |
@exception |
向生成的文档中添加*Throws*小标题,其中包括类名和描述文本。 |
@exception class-name description |
{@inheritDoc} |
*nearest*从可继承类或可实现接口继承注释。 |
继承直接父类的注释。 |
{@link} |
插入使用可见文本标签的内联链接,该标签指向引用类指定的包、类或成员名称的文档。 |
{@link package.class#member label} |
{@linkplain} |
与 {@link} 相同,只是链接的标签以普通文本显示,而不是代码字体。 |
{@linkplain package.class#member label} |
@param |
将带有指定参数名称并后跟指定说明的参数添加到“参数”部分。 |
@param parameter-name description |
@return |
添加带有说明文本的“返回值”部分。 |
@return description |
@see |
添加带有指向参考的链接或文本项的“另请参见”标题。 |
@see reference |
@serial |
用于默认可序列化字段的文档注释中。 |
@serial field-description |
include |
exclude |
@serialData |
记录 writeObject( ) 或 writeExternal( ) 方法写入的数据。 |
@serialData data-description |
@serialField |
Documents an ObjectStreamField component. |
@serialField field-name field-type field-description |
@since |
将带有指定 since-text 的“Since”标题添加到生成的文档中。 |
@since release |
@throws |
@throws 和 @exception 标记是同义词。 |
@throws class-name description |
{@value} |
当在静态字段的文档注释中使用 {@value} 时,它会显示该常量的值。 |
{@value package.class#field} |
@version |
Example - Using Old style java documentation
下述程序使用文档注释中可用的少数几个重要标记。您可以根据您的要求使用其他标记。
有关 AddNum 类的文档会生成在 HTML 文件 AddNum.html 中,但同时也会创建具有名称 index.html 的主文件。
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}
让我们编译并运行上述程序,这将生成以下结果 −
Sum of 10 and 20 is :30
现在,使用 javadoc 实用程序按如下方式处理上述 AddNum.java 文件 -
$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$
您可以在此处 AddNum 查看所有生成的文档。如果您正在使用 JDK 1.7,那么 javadoc 不会生成一个很好的*stylesheet.css*,因此我们建议您从 https://docs.oracle.com下载并使用标准样式表。
Example - Using Old style java documentation
使用 -html5 标志运行 jdk 9 的 javadoc 工具,以生成新类型的文档。
$ javadoc -html5 AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 21.0.2+13-LTS-58
Building tree for all the packages and classes...
Generating .\AddNum.html...
AddNum.java:32: error: invalid use of @return
* @return Nothing.
^
AddNum.java:16: warning: use of default constructor, which does not provide a comment
public class AddNum {
^
Generating .\package-summary.html...
Generating .\package-tree.html...
Generating .\overview-tree.html...
Building index for all classes...
Generating .\allclasses-index.html...
Generating .\allpackages-index.html...
Generating .\index-all.html...
Generating .\search.html...
Generating .\index.html...
Generating .\help-doc.html...
1 error
1 warning
$
它会创建如下所示的文档: