Apache Maven Javadoc Plugin – Using Javadoc Resources

Using Javadoc Resources

The <javadocDirectory/> parameter can be used to include additional resources, like HTML or images, in the generated javadoc. You can then link to these resources in your javadoc comments. By default, all javadoc resources are in ${basedir}/src/main/javadoc directory. Note that you need to set the docfilessubdirs parameter to copy these.

Here is a typical set of resources files used by the Maven Javadoc plugin:

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 Comment File: overview.html

These contain comments about the set of packages. The overview.html is a general documentation that applies to the entire application or set of packages.

For more information, see javadoc - The Java API Documentation Generator, Overview Comment File.

Here is an example of an overview.html file, located in ${basedir}/src/main/javadoc/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>

By default, the Javadoc Plugin includes the ${basedir}/src/main/javadoc/overview.html if it exists. You could also specify a specific overview file with the <overview/> parameter, for instance:

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

Package Comment File: package.html

These contain package comments. The package.html is a brief summary of each packages in the list of all packages.

For more information, see javadoc - The Java API Documentation Generator, Package Comment Files and How to Write Doc Comments for the Javadoc Tool, Package-Level Comments.

Here is an example of a package.html file, located in ${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>

Note: With Javadoc 5.0, this file becomes package-info.java and is preferred over package.html.

For more information, see javadoc - The Java API Documentation Generator, Package Comment Files.

Here is an example of a package-info.java file, located in ${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;

Miscellaneous Unprocessed Files: doc-files

These include images, sample source code, class files, applets, HTML files...

For more information, see javadoc - The Java API Documentation Generator, Miscellaneous Unprocessed Files and How to Write Doc Comments for the Javadoc Tool, Including Images .

In addition to doc-files directories, since 2.6.1, the specific src/main/javadoc/resources directory will be copied to the generated Javadoc resources directory (i.e. apidocs/resources). This is usefull when you want to overwite default Javadoc tool resources, like the default inherit.gif to one with a transparent background (See GIF or PSD).

Here is a sample javadoc comment to use app.png image, located in ${basedir}/src/main/javadoc/org/apache/myapp/doc-files directory:

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
{
}

IMPORTANT NOTE: To allow the copy of unprocessed files, you need to run the Javadoc Plugin with the <docfilessubdirs/> parameter.