Java语言支持三种类型的注释 :
| Sr.No. | 评论&说明 |
|---|---|
| 1 | /* text */ 编译器忽略从/*到*/的所有内容. |
| 2 | //text 编译器忽略从//到行尾的所有内容. |
| 3 | /**documentation */ 这是文档注释，通常称为 doc注释.准备自动生成的文档时， JDK javadoc 工具使用 doc comments . |
本章是关于解释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> ....用于标题和< p>已被用于创建段落和减去;
示例
/***Hello, World!
* The HelloWorld program implements an application that* simply displays "Hello World!" to the standard output.** 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工具识别以下标签&minus ;
| 标签 | 描述 | 语法 |
|---|---|---|
| @ author | 添加类的作者. | @author name-text |
| {@ code} | 以代码字体显示文本而不将文本解释为HTML标记或嵌套的javadoc标记. | {@ code text} |
| {@ docRoot} | 表示相对路径从任何生成的页面到生成的文档的根目录. | {@ docRoot} |
| @ deprecated | 添加评论表示不再使用此API. | @deprecated deprecatedtext |
| @ exception | 使用类名和说明文本向生成的文档添加投掷子标题. | @ exception class-name description |
| { @inheritDoc} | 从最近的可继承类或可实现的接口继承注释. | 从立即继承注释超级. |
| {@ link} | 插入带有可见文本标签的内联链接，指向引用类的指定包，类或成员名称的文档. | {@link package.class＃member label} |
| {@ linkplain} | 与{@link}相同，但链接的标签除外以纯文本显示而不是代码字体. | {@ linkplain package.class＃member label} |
| @ param | 在"参数"部分添加一个带有指定参数名称的参数，后跟指定的描述. | @param参数名称描述 |
| @ return | 添加带有描述文本的"返回"部分. | @ return description |
| @ see | 添加"另请参阅"使用指向引用的链接或文本条目标题. | @参见参考 |
| @ serial | 用于默认可序列化字段的doc注释. | @ serial field-description |包括|排除 |
| @ serialData | 记录由writeObject()或writeExternal()方法. | @ serialData data-description |
| @ serialField | 记录一个ObjectStreamField组件. | @serialField field-name field-type field-description |
| @ since | 使用指定的自动文本向生成的文档添加"Since"标题. | @自发布以来 |
| @ throws | @throws and @exception标签是同义词. | @throws class-name description |
| {@ value} | 在静态字段的doc注释中使用{@value}时，它会显示该常量的值. | {@ value package.class #field} |
| @version | 使用-version选项时，将指定版本文本的"Version"子标题添加到生成的文档中. | @ version version-text |
示例
以下程序使用了一些可用于文档注释的重要标记.您可以根据您的要求使用其他标签.
有关AddNum类的文档将在HTML文件AddNum.html中生成，但同时具有名称索引的主文件.html也将被创建.
import java.io.*;/***Add Two Numbers!
* The AddNum program implements an application that* simply adds two given integer numbers and Prints* the output on the screen.** Note: 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.javaLoading source file AddNum.java...Constructing Javadoc information...Standard Doclet version 1.7.0_51Building 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