Images in Javadoc-Generated Files in NetBeans

Goal

As the main source of documentation in your projects, you will be using javadoc to extract comments from your Java source and to convert them into semi-beautiful .html documents.  Ideally, you would like to have images to accompany your descriptions.  For example, here is a javadoc comment that references an image:

/**
 * This program illustrates the use of decorators in the design of a Java
 * application.  Look at the following image:
 <br/>
 <img src="doc-files/myfig.jpg"/>
 <br/>

Problem

Images are not handled properly in the integration of javadoc and NetBeans.  In general, images that are to be referenced in javadoc documents are to be placed in a subdirectory named doc-files/ of the directory containing Java source:

package/
	a.java
	b.java
	c.java
	...
	doc-files/
		image1.gif
		image2.jpg
		...

When 'javadoc -d xxx package/*' is executed, a directory xxx is created to contain the javadoc files AND the contents of the package/doc-files directory is copied into xxx/doc-files.  For some reason, this doesn't happen when javadoc is run in NetBeans.

Solution

A way to fix this is to edit the nbproject/build-impl.xml file in each NetBeans project for which you use images in your javadoc files.  Find the entry for the "-javadoc-build" task and add the yellow lines below.

<target depends="init" name="-javadoc-build">
   <mkdir dir="${dist.javadoc.dir}"/>
   <javadoc ...>
   ...
   </javadoc>

   <mkdir dir="${dist.javadoc.dir}/doc-files"/>
   <copy todir="${dist.javadoc.dir}/${application.title}/doc-files">
      <fileset dir="${src.dir}/${application.title}/doc-files" />
   </copy>
</target>