English | 简体中文 | 繁體中文 | Русский язык | Français | Español | Português | Deutsch | 日本語 | 한국어 | Italiano | بالعربية
Java supports three types of annotations. The first two are // and /* */, the third one is called annotation, it is with /** The beginning, with */End.
Documentation comments allow you to embed information about the program in the code. You can use the javadoc tool to generate information and output it to HTML files.
Describes comments that make it easier to record program information.
The javadoc tool recognizes the following tags:
| Tag | Description | Example |
|---|---|---|
| @author | Identifies the author of a class. | @author description |
| @deprecated | Identifies an outdated class or member. | @deprecated description |
| {@docRoot} | Specifies the path to the root directory of the current document. | Directory Path |
| @exception | Marks an exception thrown by a class. | @exception exception-name explanation |
| {@inheritDoc} | Comment inherited from the immediate superclass. | Inherits a comment from the immediate superclass. |
| {@link} | Inserts a link to another topic. | {@link name text} |
| {@linkplain} | Inserts a link to another topic, but the link displays plain text font. | Inserts an in-line link to another topic. |
| @param | Describes a method parameter. | @param parameter-name explanation |
| @return | Describes the return value type. | @return explanation |
| 参见 | Specifies a link to another topic. | @see anchor |
| @serial | Describes a serialized property. | @serial description |
| @serialData | Describes the data written through the writeObject() and writeExternal() methods. | @serialData description |
| @serialField | Describes an ObjectStreamField component. | @serialField name type description |
| @since | Marks when a specific change is introduced. | @since release |
| @throws | Same as the @exception tag. | The @throws tag has the same meaning as the @exception tag. |
| {@value} | Displays the value of a constant, which must be a static attribute. | 显示常量的值，该常量必须是一个静态字段。 |
| 版本 | 指定类的版本 | 版本信息 |
在开始的 /** 之后，第一行或几行是关于类、变量和方法的主要描述。
之后，你可以包含一个或多个各种各样的 @ 标签。每一个 @ 标签必须在一个新行的开始或者在一行的开始紧跟星号(*)。
多个相同类型的标签应该放成一组。例如，如果你有三个 参见 标签，可以将它们一个接一个地放在一起。
下面是一个类的说明注释的示例：
/*** 这个类绘制一个条形图 * 作者 w3codebox * 版本 1.2 */
javadoc 工具将你的 Java 程序源代码作为输入，输出一些包含你程序注释的 HTML 文件。
每个类的信息将在独立的 HTML 文件中。javadoc 也可以输出继承的树形结构和索引。
由于 javadoc 的实现不同，工作也可能不同，你需要检查你的 Java 开发系统的版本等细节，选择合适的 Javadoc 版本。
下面是一个使用说明注释的简单示例。注意每个注释都在它描述的项目前面。
在经过 javadoc 处理之后，SquareNum 类的注释将在 SquareNum.html 中找到。
import java.io;*;
/**
* 这个类演示了文档注释
* 作者 Ayan Amhed
* 版本 1.2
*/
public class SquareNum {
/**
* 此方法返回 num 的平方。
* 这是一个多行描述。您可以使用
* 您可以使用任意多的行。
* 参数 num 要平方的值。
* 返回 num 的平方。
*/
public double square(double num) {
返回 num * num;
}
/**
* 此方法从用户那里接收一个数字。
* 返回输入的双精度值。
* @exception IOException On input error.
* @see IOException
*/
public double getNumber() throws IOException {}}
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* This method demonstrates square().
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
SquareNum ob = new SquareNum();
double val;
System.out.println("Enter value to be squared: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("Squared value is " + val);
}
}As follows, use the javadoc tool to process the SquareNum.java file:
$ javadoc SquareNum.java Loading source file SquareNum.java... Constructing Javadoc information... Standard Doclet version 1.5.0_13 Building tree for all the packages and classes... Generating SquareNum.html... SquareNum.java:39: 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... Generating stylesheet.css... 1 warning $