United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4492654 : Want to use package.html file for packages that contain no classes

Details
Type:
Enhancement
Submit Date:
2001-08-16
Status:
Closed
Updated Date:
2002-10-18
Project Name:
JDK
Resolved Date:
2002-10-18
Component:
tools
OS:
solaris_2.6
Sub-Component:
javadoc(tool)
CPU:
sparc
Priority:
P4
Resolution:
Won't Fix
Affected Versions:
1.3.0
Fixed Versions:

Related Reports

Sub Tasks

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
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
                                     
2002-10-18
PUBLIC COMMENTS

..
                                     
2004-06-10



Hardware and Software, Engineered to Work Together