API Overview

------ 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}\}} 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: These contain comments about the set of packages. The 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 file, located in <$\{basedir\}/src/main/javadoc/overview.html>: +-----+ API Overview Short overview of the API. +-----+ By default, the Javadoc Plugin includes the <$\{basedir\}/src/main/javadoc/overview.html> if it exists. You could also specify a specific file with the {{{../javadoc-mojo.html#overview}\}} parameter, for instance: +-----+ ... org.apache.maven.plugins maven-javadoc-plugin ${project.version} ... ${basedir}/overview.html ... ... ... +-----+ * Package Comment File: These contain package comments. The 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 file, located in <$\{basedir\}/src/main/javadoc/org/apache/myapp/package.html>: +-----+ Core Package This is the core package of the application @since 1.0 +-----+ <>: With Javadoc 5.0, this file becomes and is preferred over . 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 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: 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 directories, since 2.6.1, the specific directory will be copied to the generated Javadoc resources directory (i.e. ). This is usefull when you want to overwite default Javadoc tool resources, like the default to one with a transparent background (See {{{../images/inherit.gif}GIF}} or {{{../images/inherit.psd}PSD}}). Here is a sample javadoc comment to use image, located in <$\{basedir\}/src/main/javadoc/org/apache/myapp/doc-files> directory: +-----+ package org.apache.myapp; /** * The main Class launches the application. * Example of the application GUI

*/ public class App { } +-----+ <>: To allow the copy of unprocessed files, you need to run the Javadoc Plugin with the {{{../javadoc-mojo.html#docfilessubdirs}\}} parameter.