Including Images in Javadoc with NetBeans

There are times when it is useful to include images and other non-source files in the documentation generated with Javadoc. The Javadoc tool documentation refers to these types of non-Java source files as Miscellaneous Unprocessed Files and states that they should be placed in a doc-files subdirectory within the package directory to which the non-source file applies.

When using Javadoc directly or via direct use of Ant, these doc-files subdirectories are copied into the generated Javadoc documentation directories and are available to the HTML pages that make up the generated documentation. Unfortunately, the Javadoc mechanism provided by NetBeans 6.1 and NetBeans 6.5 for a standard NetBeans Java Application project does not support this unprocessed file copying directly. Fortunately, this is easy to address.

This issue of NetBeans Ant-based Javadoc generation target not copying non-source files is discussed in the Sun Forum on the Javadoc Tool in the javadoc not copying from doc-files directories thread. In that forum, two postings recommend adding an alternate Ant target or overriding the NetBeans-built Ant target for generating Javadoc to support this copying. These are both useful approaches, but I think the easiest approach is to simply take advantage of NetBeans's hook for additional Javadoc tool arguments.

NetBeans generates a target with name -javadoc-build in the generated build-impl.xml file that resides in the project's nbproject directory. This target invokes the Ant core javadoc tag to run the Javadoc tool. This target uses a nested fileset tag to specify that all Java files (**/*.java) should have documentation generated. Because **/*.java is specified, only Java files have documentation generated.

One really easy way to have non-Java files copied to the generated Javadoc documentation is to take advantage of the additionalparam attribute of the Javadoc tag. I often use this attribute to specify the -linksource argument in Javadoc generation, but it can be used to specify that all directories and files under the source directory get copied by specifying the -sourcepath argument. For example, if the source directory is specified with a property like ${src.dir}, one can set additionalparam=-sourcepath ${src.dir}. NetBeans allows the additionalparam option for Javadoc to be easily specified by setting the ${javadoc.additionalparam} property in the project.properties file in the same nbproject directory.

The javadoc.additionalparam property is very useful in the NetBeans development environment when one needs to override settings of its Javadoc generation that do not provide their own property-based handles.