Java 教程

Java 控制语句

面向对象编程

Java 内置类

Java 文件处理

Java 错误和异常

Java 多线程

Java 同步

Java 网络编程

Java 集合

Java 接口

Java 数据结构

Java 集合算法

高级 Java

Java 杂项

Java API 和框架

Java 类参考

Java 有用资源

Java - 使用 JavaDoc 工具生成文档

上一页
下一页

本章主要讲解 Javadoc。我们将了解如何使用 Javadoc 为 Java 代码生成有用的文档。

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

什么是 Javadoc？

Javadoc 是一个随 JDK 提供的工具，用于从 Java 源代码生成 HTML 格式的 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!");
   }
}

输出

Hello World!

您可以在描述部分包含所需的 HTML 标签。例如，以下示例使用 <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!");
   }
}

输出

Hello World!

Javadoc 标签

Javadoc 工具识别以下标签 -

标签 描述 语法
@author 添加类的作者。 @author name-text
{@code} 以代码字体显示文本，而不将其解释为 HTML 标记或嵌套的 javadoc 标签。 {@code text}
{@docRoot} 表示从任何生成的页面到生成的文档根目录的相对路径。 {@docRoot}
@deprecated 添加一条注释，指示不再应使用此 API。 @deprecated deprecatedtext
@exception 在生成的文档中添加一个“Throws”小标题，其中包含类名和描述文本。 @exception class-name description
{@inheritDoc} 从最近的可继承类或可实现接口继承注释。 从直接父类继承注释。
{@link} 插入一个内联链接，该链接具有指向指定包、类或引用的类的成员名称的文档的可见文本标签。 {@link package.class#member label}
{@linkplain} 与 {@link} 相同，只是链接的标签以纯文本而不是代码字体显示。 {@linkplain package.class#member label}
@param 在“参数”部分添加一个参数，该参数后跟指定的 parameter-name 和描述。 @param parameter-name description
@return 添加一个“返回值”部分，其中包含描述文本。 @return description
@see 添加一个“另请参见”标题，其中包含指向引用的链接或文本条目。 @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-text。 @since release
@throws @throws 和 @exception 标签是同义词。 @throws class-name description
{@value} 当 {@value} 用于静态字段的文档注释中时，它会显示该常量的值。 {@value package.class#field}
@version 当使用 -version 选项时，在生成的文档中添加一个“版本”小标题，其中包含指定的 version-text。 @version version-text

示例 - 使用旧版 Java 文档

以下程序使用了文档注释中的一些重要标签。您可以根据需要使用其他标签。

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

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

Sum of 10 and 20 is :30

现在，使用 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 下载并使用标准样式表

示例 - 使用旧版 Java 文档

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

$ 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

$

它将创建一个如下所示的文档

Documentation
打印页面

上一页
下一页
广告