使用 Javadoc 资源

< javadocDirectory/>参数可用于在生成的 javadoc 中包含其他资源，例如 HTML 或图像。然后，您可以在您的 javadoc 注释中链接到这些资源。默认情况下，所有 javadoc 资源都在${basedir}/src/main/javadoc目录中。请注意，您需要设置 docfilessubdirs 参数来复制这些。

这是 Maven Javadoc 插件使用的一组典型资源文件：

yourproject
  |-- src
     |-- main
        |-- java
        |  |-- org
        |     |-- apache
        |        |-- myapp
        |         `-- App.java
        |         `-- package-info.java
        |-- javadoc
         `-- overview.html
           |-resources
           |-- org
              |-- apache
                 |-- myapp
                  `-- package.html
                    |-- doc-files
                     `-- app.png

概述注释文件：overview.html

这些包含关于包集的注释。overview.html是适用于整个应用程序或一组包的通用文档。

有关更多信息，请参阅javadoc - Java API 文档生成器，概述注释文件。

这是位于${basedir}/src/main/javadoc/overview.html中的overview.html文件的示例：

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
  <HEAD>
    <TITLE>API Overview</TITLE>
  </HEAD>
  <BODY>
    Short overview of the API.
  </BODY>
</HTML>

默认情况下，Javadoc 插件包含${basedir}/src/main/javadoc/overview.html（如果存在）。您还可以使用<overview/>参数指定特定的概览文件，例如：

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.3.2</version>
        <configuration>
          ...
          <overview>${basedir}/overview.html</overview>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </reporting>
  ...
</project>

包注释文件：package.html

这些包含包注释。package.html是所有包列表中每个包的简要总结。

有关更多信息，请参阅javadoc - Java API 文档生成器、包注释文件和如何为 Javadoc 工具编写文档注释、包级注释。

这是一个package.html文件的示例，位于${basedir}/src/main/javadoc/org/apache/myapp/package.html：

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
  <HEAD>
    <TITLE>Core Package</TITLE>
  </HEAD>
  <BODY>
    This is the core package of the application
    @since 1.0
  </BODY>
</HTML>

注意：在 Javadoc 5.0 中，此文件变为package-info.java并且优先于package.html。

有关更多信息，请参阅javadoc - Java API 文档生成器，包注释文件。

这是一个package-info.java文件的示例，位于${basedir}/src/main/java/org/apache/myapp/package-info.java：

/**
 * This is the core package for the application
 * @since 1.0
 */
package org.apache.myapp;

其他未处理的文件：doc-files

这些包括图像、示例源代码、类文件、小程序、HTML 文件......

有关更多信息，请参阅javadoc - Java API 文档生成器、杂项未处理文件和如何为 Javadoc 工具编写文档注释，包括图像。

除了doc-files目录，从 2.6.1 开始，具体的src/main/javadoc/resources目录将被复制到生成的 Javadoc 资源目录（即apidocs/resources）。当您想要覆盖默认的 Javadoc 工具资源时，这很有用，例如默认的inherit.gif到具有透明背景的资源（参见GIF或PSD）。

这是使用app.png图像的示例 javadoc 注释，位于${basedir}/src/main/javadoc/org/apache/myapp/doc-files目录中：

package org.apache.myapp;

/**
 * The main Class launches the application.
 * <img src="doc-files/app.png" alt="Example of the application GUI"/>
 */
public class App
{
}

重要提示：要允许复制未处理的文件，您需要使用<docfilessubdirs/>参数运行 Javadoc 插件。