Using Javadoc Resources

The <javadocDirectory/> parameter can be used to include Javadoc resources like HTML or images. By default, all javadoc resources are in ${basedir}/src/main/javadoc directory.

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>2.8.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.