Javadoc generates a single packages.html file (which is internally labeled the "Package Index") for each invocation. This is the topmost file and starting point for the documentation.

Currently, there is no provision to insert user-specified text into these files.
Especially when javadoc is once again used to generated hardcopy documentation (such as -doctype MIF), it would be helpful to have such a facility.

For example, pages xix-xx of Frank Yellin's API book would be appropriate for the Package Index corresponding to the core packages. Similarly, the text at the beginning of each chapter of the API book would be appropriate for the Package-<package-name>.html file corresponding to each core package.

==============================================================
Another request:

There are two places where I'd like to be able to include
additional documentation: prior to the "Package Index" and immediately
after the name of a package (and prior to its Interface or Class index).
If I create a package, consisting of a number of classes I need a
place to describe what this whole package does and how it works before
getting into the details of each interface or class. In the current
paradigm I can only include documentation associated with a specific
interface or class. For example, let's say I have a package called "server"
which consists of many interfaces and classes. Using javadoc I'll get a
file which looks like this:

Package server
                 <--- Here is where I'd like to talk about this
                      whole package.
  Interface Index
  Class Index

brian.klock@eng 1997-11-13
==============================================================