首页 > 代码库 > Java的文件注释

Java的文件注释

以下内容引用自http://wiki.jikexueyuan.com/project/java/documentation.html:

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 class HelloWorld {    public static void main(String[] args) {        // Prints Hello, World! on standard output.        System.out.println("Hello World!");    }}

可以将需要的HTM 标签包括在描述部分内,比如,下面的例子利用<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标签是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-descriptionincludeexclude
@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.*;/*** <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.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$

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

Java的文件注释