JDK-4492654 : Want to use package.html file for packages that contain no classes
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.3.0
  • Priority: P4
  • Status: Closed
  • Resolution: Won't Fix
  • OS: solaris_2.6
  • CPU: sparc
  • Submitted: 2001-08-16
  • Updated: 2002-10-18
  • Resolved: 2002-10-18
Description
We'd like to have an overview document at a package level (below
the top level) that contains no classes.

In order to get my package.html doc to get assimilated into the
javadocs, I have to have a class in the package.  Otherwise, javadoc
seems to ignore the package.html (even though there are subpackages 
containing numerous classes).  To work around this, we add a 
placeholder class to the package:
 
  class Placeholder {
  }
  
Then as long as you don't specify -package or -private on the Javadoc
invocation line, it won't include the package scope class, but it will
include the package.html in that package directory.
 
What happens is we have a package that extends Swing functionality 
for our GUI API (AppWorks).  We have a package AWComponents that
are extensions to our AppWorks package:

Landmark.AWComponents.actions
Landmark.AWComponents.actions.edit

However there are no classes in the Landmark.AWComponents top level
package. But, we have a package.html in that package that
explains what the structure of the hierarchy is and the
purpose of the whole package.

so ... I put a PlaceHolder.java file in there and the package.html 
gets javadoc'd into the package-summary.html like a champ now. 
Again, so long as you don't -package or -private the javadoc, 
you never see the otherwise useless class.

Comments
PUBLIC COMMENTS ..
10-06-2004

EVALUATION Makes sense to me to lift this restriction, if we can. I suppose it would require, for the example given, that the user pass in Landmark.AWComponents (or that -subpackages would automatically find it). Would this feature be possible when passing in source filenames? ###@###.### 2001-08-15 This problem was reported against 1.3. I could not reproduce this problem in 1.4.1 or later. See below. This should address your need, so I'm closing as will not fix (we won't fix the 1.3 product line). If it doesn't satisfy your need, please reopen this or open a new report against 1.4.x. ==========> ls -lR total 2 -rw-r--r-- 1 gafter 133 Oct 18 13:31 Makefile drwxr-sr-x 3 gafter 512 Oct 18 12:17 src src: total 1 drwxr-sr-x 3 gafter 512 Oct 18 13:28 a src/a: total 2 drwxr-sr-x 2 gafter 512 Oct 18 13:28 b -rw-r--r-- 1 gafter 72 Oct 18 13:26 package.html src/a/b: total 1 -rw-r--r-- 1 gafter 32 Oct 18 12:16 T.java ==========> cat Makefile all: rm -rf dest mkdir dest /java/re/j2se/1.4.1/promoted/latest/binaries/solaris-sparc/bin/javadoc -d dest -sourcepath src a a.b ==========> cat src/a/package.html <body> A silly package. <p>The package "a" is a silly package. </body> ==========> cat src/a/b/T.java package a.b; public class T {} ==========> make rm -rf dest mkdir dest /java/re/j2se/1.4.1/promoted/latest/binaries/solaris-sparc/bin/javadoc -d dest -sourcepath src a a.b Loading source files for package a... javadoc: warning - No source files for package a Loading source files for package a.b... Constructing Javadoc information... Standard Doclet version 1.4.1 Generating dest/constant-values.html... Building tree for all the packages and classes... Building index for all the packages and classes... Generating dest/overview-tree.html... Generating dest/index-all.html... Generating dest/deprecated-list.html... Building index for all classes... Generating dest/allclasses-frame.html... Generating dest/allclasses-noframe.html... Generating dest/index.html... Generating dest/packages.html... Generating dest/overview-summary.html... Generating dest/overview-frame.html... Generating dest/a/package-frame.html... Generating dest/a/package-summary.html... Generating dest/a/package-tree.html... Generating dest/a/b/package-frame.html... Generating dest/a/b/package-summary.html... Generating dest/a/b/package-tree.html... Generating dest/a/b/T.html... Generating dest/package-list... Generating dest/help-doc.html... Generating dest/stylesheet.css... 1 warning ==========> grep silly dest/a/package-summary.html A silly package. A silly package. <p>The package "a" is a silly package. ==========> ###@###.### 2002-10-18
18-10-2002