📅 最后修改于: 2020-11-15 04:35:56 🧑 作者: Mango
Java语言支持三种类型的注释-
| Sr.No. | Comment & Description |
|---|---|
| 1 |
/* text */ The compiler ignores everything from /* to */. |
| 2 |
//text The compiler ignores everything from // to the end of the line. |
| 3 |
/** documentation */ This is a documentation comment and in general its called doc comment. The JDK javadoc tool uses doc comments when preparing automatically generated documentation. |
本章都是关于解释Javadoc的。我们将看到如何利用Javadoc为Java代码生成有用的文档。
Javadoc是JDK附带的工具，用于从Java源代码生成HTML格式的Java代码文档，而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标记。例如，以下示例将
用于创建段落中断-
/**
* 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工具可识别以下标签-
| Tag | Description | Syntax |
|---|---|---|
| @author | Adds the author of a class. | @author name-text |
| {@code} | Displays text in code font without interpreting the text as HTML markup or nested javadoc tags. | {@code text} |
| {@docRoot} | Represents the relative path to the generated document’s root directory from any generated page. | {@docRoot} |
| @deprecated | Adds a comment indicating that this API should no longer be used. | @deprecated deprecatedtext |
| @exception | Adds a Throws subheading to the generated documentation, with the classname and description text. | @exception class-name description |
| {@inheritDoc} | Inherits a comment from the nearest inheritable class or implementable interface. | Inherits a comment from the immediate surperclass. |
| {@link} | Inserts an in-line link with the visible text label that points to the documentation for the specified package, class, or member name of a referenced class. | {@link package.class#member label} |
| {@linkplain} | Identical to {@link}, except the link’s label is displayed in plain text than code font. | {@linkplain package.class#member label} |
| @param | Adds a parameter with the specified parameter-name followed by the specified description to the “Parameters” section. | @param parameter-name description |
| @return | Adds a “Returns” section with the description text. | @return description |
| @see | Adds a “See Also” heading with a link or text entry that points to reference. | @see reference |
| @serial | Used in the doc comment for a default serializable field. | @serial field-description | include | exclude |
| @serialData | Documents the data written by the writeObject( ) or writeExternal( ) methods. | @serialData data-description |
| @serialField | Documents an ObjectStreamField component. | @serialField field-name field-type field-description |
| @since | Adds a “Since” heading with the specified since-text to the generated documentation. | @since release |
| @throws | The @throws and @exception tags are synonyms. | @throws class-name description |
| {@value} | When {@value} is used in the doc comment of a static field, it displays the value of that constant. | {@value package.class#field} |
| @version | Adds a “Version” subheading with the specified version-text to the generated docs when the -version option is used. | @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.
*
* @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下载并使用标准样式表。