Introduction to Javadoc – Javadoc简介

最后修改: 2018年 1月 28日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

Good API documentation is one of the many factors contributing to the overall success of a software project.

良好的API文档是促成一个软件项目整体成功的众多因素之一。

Fortunately, all modern versions of the JDK provide the Javadoc tool – for generating API documentation from comments present in the source code.

幸运的是，所有现代版本的JDK都提供了Javadoc工具–用于从源代码中的注释生成API文档。

Prerequisites:

先决条件。

  1. JDK 1.4 (JDK 7+ is recommended for the latest version of the Maven Javadoc plugin)
  2. The JDK /bin folder added to the PATH environment variable
  3. (Optional) an IDE that with built-in tools

2. Javadoc Comments

2.Javadoc注释

Let’s start with comments.

让我们从评论开始。

Javadoc comments structure look very similar to a regular multi-line comment, but the key difference is the extra asterisk at the beginning:

Javadoc注释结构看起来与普通的多行注释非常相似，但关键的区别在于开头多了一个星号。

// This is a single line comment

/*
 * This is a regular multi-line comment
 */

/**
 * This is a Javadoc
 */

Javadoc style comments may contain HTML tags as well.

Javadoc风格的评论也可以包含HTML标签。。

2.1. Javadoc Format

2.1.Javadoc格式

Javadoc comments may be placed above any class, method, or field which we want to document.

Javadoc注释可以放在我们想要记录的任何类、方法或字段之上。

These comments are commonly made up of two sections:

这些评论通常由两部分组成。

  1. The description of what we’re commenting on
  2. The standalone block tags (marked with the “@” symbol) which describe specific meta-data

We’ll be using some of the more common block tags in our example. For a complete list of block tags, visit the reference guide.

我们将在我们的例子中使用一些比较常见的块状标签。有关块状标签的完整列表，请访问参考指南。

2.2. Javadoc at Class Level

2.2.类级的Javadoc

Let’s take a look at what a class-level Javadoc comment would look like:

让我们来看看一个类级的Javadoc注释是什么样子的。

/**
* Hero is the main entity we'll be using to . . .
* 
* Please see the {@link com.baeldung.javadoc.Person} class for true identity
* @author Captain America
* 
*/
public class SuperHero extends Person {
    // fields and methods
}

We have a short description and two different block tags- standalone and inline:

我们有一个简短的描述和两个不同的块状标签–独立的和内联的。

  • Standalone tags appear after the description with the tag as the first word in a line, e.g., the @author tag
  • Inline tags may appear anywhere and are surrounded with curly brackets, e.g., the @link tag in the description

In our example, we can also see two kinds of block tags being used:

在我们的例子中，我们也可以看到有两种块状标签被使用。

  • {@link} provides an inline link to a referenced part of our source code
  • @author the name of the author who added the class, method, or field that is commented

2.3. Javadoc at Field Level

2.3.字段级的Javadoc

We can also use a description without any block tags like this inside our SuperHero class:

我们也可以像这样在我们的SuperHero类里面使用没有任何块状标签的描述。

/**
 * The public name of a hero that is common knowledge
 */
private String heroName;

Private fields won’t have Javadoc generated for them unless we explicitly pass the -private option to the Javadoc command.

除非我们明确地将-private选项传递给Javadoc命令，否则私有字段将不会为其生成Javadoc。

2.4. Javadoc at Method Level

2.4.方法层面的Javadoc

Methods can contain a variety of Javadoc block tags.

方法可以包含各种Javadoc块标签。

Let’s take a look at a method we’re using:

让我们来看看我们正在使用的一种方法。

/**
 * <p>This is a simple description of the method. . .
 * <a href="http://www.supermanisthegreatest.com">Superman!</a>
 * </p>
 * @param incomingDamage the amount of incoming damage
 * @return the amount of health hero has after attack
 * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 * @since 1.0
 */
public int successfullyAttacked(int incomingDamage) {
    // do things
    return 0;
}

The successfullyAttacked method contains both a description and numerous standalone block tags.

successfullyAttacked方法同时包含一个描述和许多独立的块状标签。

There’re many block tags to help generate proper documentation and we can include all sorts of different kinds of information. We can even utilize basic HTML tags in the comments.

有许多块状标签可以帮助生成适当的文档，我们可以包括各种不同的信息。我们甚至可以在评论中利用基本的HTML标签。

Let’s go over the tags we encounter in the example above:

让我们来看看上面的例子中遇到的标签。

  • @param provides any useful description about a method’s parameter or input it should expect
  • @return provides a description of what a method will or can return
  • @see will generate a link similar to the {@link} tag, but more in the context of a reference and not inline
  • @since specifies which version the class, field, or method was added to the project
  • @version specifies the version of the software, commonly used with %I% and %G% macros
  • @throws is used to further explain the cases the software would expect an exception
  • @deprecated gives an explanation of why code was deprecated, when it may have been deprecated, and what the alternatives are

Although both sections are technically optional, we’ll need at least one for the Javadoc tool to generate anything meaningful.

虽然这两个部分在技术上是可选的，但我们至少需要一个，以便Javadoc工具生成有意义的东西。

3. Javadoc Generation

3.Javadoc的生成

In order to generate our Javadoc pages, we’ll want to take a look at the command line tool that ships with the JDK, and the Maven plugin.

为了生成Javadoc页面，我们要看看JDK附带的命令行工具，以及Maven插件。

3.1. Javadoc Command Line Tool

3.1.Javadoc命令行工具

The Javadoc command line tool is very powerful but has some complexity attached to it.

Javadoc命令行工具非常强大，但也有一些复杂的东西附加在上面。

Running the command javadoc without any options or parameters will result in an error and output parameters it expects.

在没有任何选项或参数的情况下运行javadoc命令，将导致错误并输出它所期望的参数。

We’ll need to at least specify what package or class we want documentation to be generated for.

我们至少需要指定我们希望生成的文档是什么包或类。

Let’s open a command line and navigate to the project directory.

让我们打开一个命令行并导航到项目目录。

Assuming the classes are all in the src folder in the project directory:

假设这些类都在项目目录下的src文件夹中。

user@baeldung:~$ javadoc -d doc src\*

This will generate documentation in a directory called doc as specified with the –d flag. If multiple packages or files exist, we’d need to provide all of them.

这将在一个名为doc的目录中生成文档，如用-d标志指定的那样。如果存在多个软件包或文件，我们需要提供所有这些文件。

Utilizing an IDE with the built-in functionality is, of course, easier and generally recommended.

当然，利用具有内置功能的集成开发环境更容易，一般也推荐使用。

3.2. Javadoc With Maven Plugin

3.2.用Maven插件编写Javadoc

We can also make use of the Maven Javadoc plugin:

我们还可以利用Maven的Javadoc插件。

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

在项目的基础目录下，我们运行命令来生成我们的Javadocs到target/site的一个目录。

user@baeldung:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Maven插件非常强大，可以促进复杂文件的无缝生成。

Let’s now see what a generated Javadoc page looks like:

现在让我们看看生成的Javadoc页面是什么样子的。

overview

概述

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

我们可以看到我们的SuperHero类所扩展的类的树状视图。我们可以看到我们的描述、字段和方法，我们还可以点击链接获得更多信息。

A detailed view of our method looks like this:

我们的方法的详细视图是这样的。

ss javadoc

3.3. Custom Javadoc Tags

3.3.自定义Javadoc标签

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

除了使用预定义的块状标签来格式化我们的文档外，我们还可以创建自定义块状标签。

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of <tag-name>:<locations-allowed>:<header>.

为了做到这一点，我们只需要在我们的Javadoc命令行中加入一个-tag选项，格式为<tag-name>:<location-allowed>:<header>/em>。

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

为了创建一个允许在任何地方使用的名为@location的自定义标签，在我们生成的文档中显示在 “值得注意的地点 “标题下，我们需要运行。

user@baeldung:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

为了使用这个标签，我们可以把它加到Javadoc注释的块状部分。

/**
 * This is an example...
 * @location New York
 * @returns blah blah
 */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

Maven Javadoc插件非常灵活，也允许我们在pom.xml中定义自定义标签。

In order to set up the same tag above for our project, we can add the following to the <tags> section of our plugin:

为了给我们的项目设置上述相同的标签，我们可以在我们的插件的<tags>部分添加以下内容。

...
<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag> 
</tags>
...

This way allows us to specify the custom tag once, instead of specifying it every time.

这种方式允许我们一次性指定自定义标签，而不是每次都指定它。

4. Conclusion

4.结论

This quick introduction tutorial covered how to write basic Javadocs and generate them with the Javadoc command line.

这个快速入门教程涵盖了如何编写基本的Javadoc并通过Javadoc命令行生成它们。

An easier way to generate the documentation would to use any built-in IDE options or include the Maven plugin into our pom.xml file and run the appropriate commands.

生成文档的一个更简单的方法是使用任何内置的IDE选项或将Maven插件纳入我们的pom.xml文件并运行相应的命令。

The code samples, as always, can be found over on GitHub.

像往常一样，代码样本可以在GitHub上找到超过。