Java 简明教程

Java - Documentation using JavaDoc tool

本章重点是解释 Javadoc。我们将了解如何使用 Javadoc 来生成 Java 代码的有用文档。

This chapter is all about explaining Javadoc. We will see how we can make use of Javadoc to generate useful documentation for Java code.

Java 文档可以使用 javadoc 工具生成。目前，它会生成 html 4.0 格式的文档。从 Java 9 开始，我们可以在命令行参数中使用 -html5 选项生成 html 5 格式的文档。

Java documentation can be generated using javadoc tool. It currently generates documentation in html 4.0 format. From java 9 onwards, we can generate documentation in html 5 format by using -html5 option in command line arguments.

What is Javadoc?

Javadoc 是一种附带 JDK 的工具，用于从 Java 源代码（它需要一个预定义格式的文档）中生成 HTML 格式的 Java 代码文档。

Javadoc is a tool which comes with JDK and it is used for generating Java code documentation in HTML format from Java source code, which requires documentation in a predefined format.

以下是一个简单的示例，其中 /…./ 内部的是 Java 多行注释。类似地，// 前面的行是 Java 单行注释。

Following is a simple example where the lines inside /…./ are Java multi-line comments. Similarly, the line which preceeds // is Java single-line comment.

Example

/**
* 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!");
   }
}
Hello World!

你可以在描述部分包含所需的 HTML tags。例如，下面的示例使用 <h1>…​.</h1> 作为页眉，并使用 <p> 用于创建分段符 −

You can include required HTML tags inside the description part. For instance, the following example makes use of <h1>…​.</h1> for heading and <p> has been used for creating paragraph break −

Example

/**
* <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!");
   }
}
Hello World!

The javadoc Tags

javadoc 工具识别以下标记：

The javadoc tool recognizes the following tags −

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

Example - Using Old style java documentation

下述程序使用文档注释中可用的少数几个重要标记。您可以根据您的要求使用其他标记。

Following program uses few of the important tags available for documentation comments. You can make use of other tags based on your requirements.

有关 AddNum 类的文档会生成在 HTML 文件 AddNum.html 中，但同时也会创建具有名称 index.html 的主文件。

The documentation about the AddNum class will be produced in HTML file AddNum.html but at the same time a master file with a name index.html will also be created.

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);
   }
}

让我们编译并运行上述程序，这将生成以下结果 −

Let us compile and run the above program, this will produce the following result −

Sum of 10 and 20 is :30

现在，使用 javadoc 实用程序按如下方式处理上述 AddNum.java 文件 -

Now, process the above AddNum.java file using javadoc utility as follows −

$ 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下载并使用标准样式表。

You can check all the generated documentation here − AddNum. If you are using JDK 1.7 then javadoc does not generate a great stylesheet.css, so we suggest to download and use standard stylesheet from https://docs.oracle.com

Example - Using Old style java documentation

使用 -html5 标志运行 jdk 9 的 javadoc 工具，以生成新类型的文档。

Run the javadoc tool of jdk 9 with -html5 flag to generate new type of documentation.

$ javadoc -html5 AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 21.0.2+13-LTS-58
Building tree for all the packages and classes...
Generating .\AddNum.html...
AddNum.java:32: error: invalid use of @return
   * @return Nothing.
     ^
AddNum.java:16: warning: use of default constructor, which does not provide a comment
public class AddNum {
       ^
Generating .\package-summary.html...
Generating .\package-tree.html...
Generating .\overview-tree.html...
Building index for all classes...
Generating .\allclasses-index.html...
Generating .\allpackages-index.html...
Generating .\index-all.html...
Generating .\search.html...
Generating .\index.html...
Generating .\help-doc.html...
1 error
1 warning

$

它会创建如下所示的文档:

It will create a documentation as shown below:

javadoc documentation