JDK-4034280 : Allow package-level comments in topmost packages.html file
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.1,1.1.3
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: solaris_2.5.1,windows_95
  • CPU: generic,x86
  • Submitted: 1997-02-25
  • Updated: 2014-05-05
  • Resolved: 1999-01-19
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
1.2.0 1.2beta3Fixed
Related Reports
Relates :  
Relates :  
Relates :  
Relates :  
Description
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
==============================================================

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: generic FIXED IN: 1.2beta3 INTEGRATED IN: 1.2beta3 VERIFIED IN: 1.2beta4
14-06-2004

EVALUATION Dupe. chris.bucchere@Eng 1997-09-19 ---- Want to re-open because it's not really a dupe of 4034756, and not yet fixed. That was about the Package-<package>.html files, while this is about the packages.html file. doug.kramer@Eng 1997-10-06 ----- Done in doclet API and Standard doclet. robert.field@Eng 1998-01-06
06-10-1997

PUBLIC COMMENTS This rfe was closed as a duplicate of 4034756. Please see that rfe for more information. chris.bucchere@Eng 1997-09-19 Verified in JDK1.2Beta4-G. dianne.jiao@East 1998-05-26
19-09-1997

SUGGESTED FIX Implementing this could be a bit tricky. Since the packages.html file is a function of how javadoc is invoked, it probably makes the most sense to add an option (such as "-preamble <filename>") to indicate where the user-specified text is to come from that gets inserted into the packages.html file. Since there is a one-to-one correspondence between packages and Package-<package-name>.html files, one possibility is to have a convention whereby some specially named file in each package's directory (e.g., preamble.html or <package-name>-preamble.html) is automatically inserted into each Package-<package-name>.html file. -- Again, jdtl is not capable of this. Please see my comments on 4034759. chris.bucchere@Eng 1997-09-18
18-09-1997