极客教程Java 文档注释
Java语言支持三种类型的注释—
| 序号 | 注释和描述 |
|---|---|
| 1 | /* 文本 */ 编译器会忽略从/到/之间的所有内容。 |
| 2 | //文本 编译器会忽略从//到行尾的所有内容。 |
| 3 | \** documentation **/这是一个文档注释，通常被称为 文档注释 。在准备自动生成的文档时， JDK javadoc 工具会使用文档注释。 |
本章节的目的是解释Javadoc。我们将看到如何使用Javadoc为Java代码生成有用的文档。
什么是Javadoc
Javadoc是一个随JDK提供的工具，用于从Java源代码生成以HTML格式的Java代码文档，该文档需要按预定义格式撰写。
以下是一个简单的示例，其中/…./内的行是Java的多行注释。同样，前面带有//的行是Java的单行注释。
示例
/**
* 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!");
}
}
您可以在描述部分内包含所需的HTML标签。例如，以下示例使用<h1>....</h1>作为标题，<p>用于创建段落分隔 –
示例
/**
* <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!");
}
}
javadoc标签
javadoc工具认识以下标签 –
| 标签 | 描述 | 语法 |
|---|---|---|
| @author | 添加类的作者。 | @author name-text |
| {@code} | 以代码字体显示文本，不解释文本为HTML标记或嵌套的javadoc标签。 | {@code text} |
| {@docRoot} | 表示生成的文档根目录相对路径与任何生成页面的关系。 | {@docRoot} |
| @deprecated | 添加一个注释，表示此API不再应该使用。 | @deprecated deprecatedtext |
| @exception | 在生成的文档中添加一个 Throws 子标题，包含类名和描述文本。 | @exception class-name description |
| {@inheritDoc} | 从最近的可继承类或可实现接口继承注释。 | 从直接的父类继承注释。 |
| {@link} | 插入一个内联链接，可见文本标签指向被引用类的指定包、类或成员名称的文档。 | {@link package.class#member label} |
| {@linkplain} | 与{@link}相同，只是链接的标签以纯文本显示，而不是代码字体。 | {@linkplain package.class#member label} |
| @param | 在”Parameters”部分添加一个具有指定参数名称和指定描述的参数。 | @param parameter-name 描述 |
| @return | 添加一个带有描述文本的“返回”部分。 | @return 描述 |
| @see | 添加一个带有链接或文本条目的“参见”标题，指向引用。 | @see 引用 |
| @serial | 用于默认可序列化字段的文档注释中。 | @serial 字段描述 | 包括 | 排除 |
| @serialData | 记录writeObject()或writeExternal()方法写入的数据。 | @serialData 数据描述 |
| @serialField | 记录ObjectStreamField组件。 | @serialField 字段名 字段类型 字段描述 |
| @since | 在生成的文档中添加“Since”标题，并添加指定的Since-text。 | @since release |
| @throws | @throws和@exception标签是同义词。 | @throws class-name description |
| {@value} | 当在静态字段的文档注释中使用{@value}时，它会显示该常量的值。 | {@value package.class#field} |
| @version | 当使用-version选项时，向生成的文档添加具有指定version-text的“Version”子标题。 | @version version-text |
示例
以下程序使用了一些用于文档注释的重要标签。根据您的需求，您可以使用其他标签。
关于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);
}
}
现在，使用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/javase/7/docs/api/stylesheet.css