 ------
 Using Javadoc Resources
 ------
 Vincent Siveton
 ------
 2009-09-10
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Using Javadoc Resources

 The {{{../javadoc-mojo.html#javadocDirectory}\<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 {{{http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#overviewcomment}
 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 {{{../javadoc-mojo.html#overview}\<overview/\>}} parameter, for instance:

+-----+
<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${project.version}</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 {{{http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#packagecomment}
 javadoc - The Java API Documentation Generator, Package Comment Files}} and
 {{{http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments}
 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 {{{http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#packagecomment}
 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 {{{http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#unprocessed}
 javadoc - The Java API Documentation Generator, Miscellaneous Unprocessed Files}} and
 {{{http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#images}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 {{{../images/inherit.gif}GIF}} or {{{../images/inherit.psd}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
 {{{../javadoc-mojo.html#docfilessubdirs}\<docfilessubdirs/\>}} parameter.
