Java语言支持三种类型的注释 :
Sr.No. | 评论&说明 |
---|---|
1 | /* text */ 编译器忽略从/*到*/的所有内容. |
2 | //text 编译器忽略从//到行尾的所有内容. |
3 | /**documentation */ 这是文档注释,通常称为 doc注释.准备自动生成的文档时, JDK javadoc 工具使用 doc comments . |
本章是关于解释Javadoc的.我们将看到如何利用Javadoc为Java代码生成有用的文档.
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工具识别以下标签&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.*; /** * <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