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