Javadoc'ing Large Java Libraries
			================================

				John Visosky
			Hummingbird Communications Ltd.


Javadoc reaches memory limits when processing a large number of
packages and classes, and fails to produce output.  The approach
outlined below enables the javadoc'ing of an arbitrarily large
library.  It includes a batch file and a makefile that you can 
copy and paste into your own files and modify.

In addition to processing large libraries, this approach can
also be used to ensure successful javadoc'ing of class libraries
developed with java.* classes provided by parties other than Sun.
In other words, this approach shows how you tell javadoc to use 
-classpath to load its classes.zip file from one place (to execute 
javadoc) while using -sourcepath to locate the .java files from
another place (from which to generate the documentation).

This approach has been tested under NT 4.0, using JDK 1.1.4,
and Microsoft's Java classes as released with Internet Explorer 4.0.


1) MakeDoc.bat -----------------------------------------------------

The following batch file is used to run the makefile, to ensure
correct PATH and CLASSPATH settings, which may differ from the
developer's environment settings.  It is assumed that you have
installed JDK 1.1.4 to 'j:\jdk114'.  A version of 'make' is
assumed to exist in your PATH.  Change these as required.

MakeDoc.bat:

	@rem Batch file to run MakeDoc.mak

	SETLOCAL

	@rem indicate location of the JDK to be used
	set JDK=k:\jdk114

	@rem ensure that PATH includes JDK's bin
	set PATH=%JDK%\bin;%PATH%

	@rem ensure that CLASSPATH includes _only_ JDK's classes
	set CLASSPATH=%JDK%\lib\classes.zip

	@rem make the docs
	make -f MakeDoc.mak

	ENDLOCAL


2) MakeDoc.mak -----------------------------------------------------

The following makefile is used to invoke javadoc for a fictitious
class library known as 'COM.mycompany.lib', with has several sub-packages.

When javadoc generates its output, the HTML files reference a set
of GIF's (for bullets, etc.).  These are copied from:

	$(JDK)\docs\api\images

In other words, from Sun's JDK documentation directory.  If you do
not have this documentation installed, you will have to obtain the
contents of the images directory by downloading the documentation
from: http://java.sun.com/products/jdk/1.1

MakeDoc.mak:

#############################################################################
#
#			Java Library Javadoc Makefile
#
# This makefile creates javadoc-generated HTML documentation for the library.
#
#############################################################################

# Create the macro PACKAGES to list all packages to be included

IO_PKG=$(IO_PKG)   COM.mycompany.lib.io.sub1
IO_PKG=$(IO_PKG)   COM.mycompany.lib.io.sub2
IO_PKG=$(IO_PKG)   COM.mycompany.lib.io.sub3

AWT_PKG=$(AWT_PKG) COM.mycompany.lib.awt.sub1
AWT_PKG=$(AWT_PKG) COM.mycompany.lib.awt.sub2
AWT_PKG=$(AWT_PKG) COM.mycompany.lib.awt.sub3

NET_PKG=$(NET_PKG) COM.mycompany.lib.net.sub1
NET_PKG=$(NET_PKG) COM.mycompany.lib.net.sub2
NET_PKG=$(NET_PKG) COM.mycompany.lib.net.sub3

PACKAGES           = $(IO_PKG) $(AWT_PKG) $(NET_PKG)

#############################################################################

# Set the root of the library (parent directory of COM)

LIB_ROOT           = \MyJavaSource

#############################################################################

# Set the location of the classes.zip the library was compiled with

# For Sun's classes, use:
#JAVA_CLASSES      = $(JDK)\lib\classes.zip

# For Microsoft's classes, use:
JAVA_CLASSES       = c:\winnt4\java\classes\classes.zip

#############################################################################

# Set the location of the 'images' directory containing the
# GIF's referenced by javadoc-generated HTML

DOC_IMAGES         = $(JDK)\docs\api\images

#############################################################################

# Set the desired destination directory for the javadoc-generated HTML

# !!! NOTE !!! This directory will be deleted!
DOC_DEST           = javadoc

#############################################################################

# Run javadoc directly (rather than with javadoc.exe) in order to
# pass the VM some memory flags.  The command below allots 40Meg.
# Adjust it as necessary.

JD                 = java -ms40m -mx40m sun.tools.javadoc.Main

JD_SOURCEPATH      = -sourcepath $(JAVA_CLASSES);$(LIB_ROOT)

JD_INCLUDES        = -version -author

JD_FLAGS           = $(JD_SOURCEPATH) $(JD_INCLUDES) -d $(DOC_DEST)

#############################################################################

all :
	rmdir /s /q $(DOC_DEST)
	mkdir $(DOC_DEST)

	$(JD) $(JD_FLAGS) $(PACKAGES)

	mkdir $(DOC_DEST)\images
	xcopy $(DOC_IMAGES) $(DOC_DEST)\images

	@echo Java Library docs created!

#############################################################################