java 文件备注_Java的文件注释

Java语言支持三种注释形式：

注释描述

/*text*/

编译器忽略/*到*/的所有东西

//text

编译器忽略从//到一行末尾的所有东西

/**

documentation

*/

这是文档注释并且通常而言它被叫做doc comment。JDK javadoc工具当准备自动准备生成文件时使用doc comment

一、什么是Javadoc？

Javadoc是JDK附带的一个工具，它被用来生成从需要预定义格式的文档的Java源代码至HTML格式的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 classHelloWorld {public static voidmain(String[] args) {// Prints Hello, World! on standard output.

System.out.println("Hello World!");

}

}

可以将需要的HTM 标签包括在描述部分内，比如，下面的例子利用

...

来定义头部和

被用来创建段落间隔：

/***

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.

*

*

*@authorZara Ali

*@version1.0

*@since2014-03-31*/

public classHelloWorld {public static voidmain(String[] args) {//Prints Hello, World! on standard output.

System.out.println("Hello World!");

}

}

二、Javadoc标签

Javadoc标签是Javadoc认可的关键字，它定义了下面信息的类型。

Javadoc工具认可下面的标签：

标签描述语法

@author

添加类的作者

@author name-text

{@code}

不把文本转换成HTML标记和嵌套的Java标签而用代码字体展示它

{@code text}

{@docRoot}

表示从任何生成页面到生成文档的根目录的相对路径

{@docRoot}

@deprecated

添加一个注释暗示API应该不再被使用

@deprecated deprecated-text

@exception

用类名和描述文本给生成的文档添加一个副标题

@exception class-name description

{@inheritDoc}

从最近的可继承的类或可实现的接口继承注释

Inherits a comment from the immediate surperclass.

{@link}

用指向特定的包，类或者一个引用类的成员名的文档的可见文本标签插入在线链接

{@link package.class#member label}

{@linkplain}

和{@link}相同，除了链接的标签用纯文本标示而不是代码字体

{@linkplain package.class#member label}

@param

给“参数”区域添加一个有特定参数名且后跟着特定描述的参数

@param parameter-name description

@return

添加一个有描述文本的“Returns”区域

@return description

@see

添加带有链接或者指向引用的文本入口的标题“See Also”

@see reference

@serial

在默认的序列化字段的文本注释中使用

@serial field-description

include

exclude

@serialData

记录由writeObject( )或writeExternal( )方法所写的数据

@serialData data-description

@serialField

记录一个ObjectStreamField成分

@serialField field-name field-type field-description

@since

给生成的文档添加一个带有特定since文本的"Since"标题

@since release

@throws

@throw和@exception标签是同义词

@throws class-name description

{@value}

当{@value}被用在一个静态字段的文本注释中，它展示了那个常量的值

{@value package.class#field}

@version

当-version选项被使用时用特定的version文本给生成的文本添加一个“Version”副标题

@version version-text

示例：

下面的程序使用一些重要的标签来做文档注释。可以基于需求利用其它的标签。

关于AddNum类的文档将由HTML文件AddNum.html创建，但是同时一个名为index.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.

*

*@authorZara Ali

*@version1.0

*@since2014-03-31*/

public classAddNum {/*** 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.

*@paramnumA This is the first paramter to addNum method

*@paramnumB This is the second parameter to addNum method

*@returnint This returns sum of numA and numB.*/

public int addNum(int numA, intnumB) {return numA +numB;

}/*** This is the main method which makes use of addNum method.

*@paramargs Unused.

*@returnNothing.

*@exceptionIOException On input error.

*@seeIOException*/

public static void main(String args[]) throwsIOException

{

AddNum obj= newAddNum();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 version1.7.0_51

Building treeforall the packages and classes...

Generating/AddNum.html...

AddNum.java:36: warning - @return tag cannot be used in method with void returntype.

Generating/package-frame.html...

Generating/package-summary.html...

Generating/package-tree.html...

Generating/constant-values.html...

Building indexforall the packages and classes...

Generating/overview-tree.html...

Generating/index-all.html...

Generating/deprecated-list.html...

Building indexforall classes...

Generating/allclasses-frame.html...

Generating/allclasses-noframe.html...

Generating/index.html...

Generating/help-doc.html...1warning

$

如果正在使用JDK 1.7那么Javadoc不生成stysheet.css，所以建议从http://docs.oracle.com/javase/7/docs/api/stylesheet.css下载并使用标准的stylesheet。