United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4548768 : REGRESSION: Javadoc in JDK 1.4 uses classpath and not just source dir

Details
Type:
Bug
Submit Date:
2001-12-05
Status:
Closed
Updated Date:
2002-06-27
Project Name:
JDK
Resolved Date:
2002-03-08
Component:
tools
OS:
linux,generic
Sub-Component:
javadoc(tool)
CPU:
x86,generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.3.0,1.4.0
Fixed Versions:
1.4.1 (hopper)

Related Reports
Duplicate:

Sub Tasks

Description

Name: nt126004			Date: 12/05/2001


java version "1.4.0-beta3"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-beta3-b84)
Java HotSpot(TM) Client VM (build 1.4.0-beta3-b84, mixed mode)

Javadoc will attempt to document files in the classpath and not just those
that are in the source path as given to the tool. For example, say we're
attempting to document the package foo.bar. The source files in the source
directory that we're attempting to javadoc might be the following:

MyClassA
MyClassB
MyClassC

In earlier versions of the tool, only those three files will be Javadoc'ed.
However, in the JDK1.4 beta3 version of the tool, if the classpath contains
the classes foo.bar.OtherClassA and foo.bar.OtherClassB then Javadoc will
attempt to generate documentation for those classes as well. However, this
process produces strange results since source code for OtherClassA and
OtherClassB is not available.

The versions of Javadoc that shipped with JDK 1.2 and 1.3 work fine. I
can switch back and forth bewteen JDK's (1.4 beta 3 and the others) and
alternatively see the problem/not see it.

The simple test case would be to:

 1) Compile a few source files into a JAR
 2) Create additional source files in the same package as the ones in
the JAR
 3) Call javadoc on the new source files with the JAR in the classpath.

Please let me know if I can be of further assistance. We would really
like to see the bug fixed, so I'm happy to help if you have any troubles
reproducing the error.


It's important to revert to the earlier behavior of Javadoc since:

 1) There may be source files in a package that should not be Javadoc'ed even
if they're in the classpath of the javadoc tool.
 2) Trying to javadoc files that source is not available for fails badly (no
comments). Especially bad results occor with the "-linksource" option enabled.

Release Regression From : 1.3.1
The above release value was the last known release where this 
bug was knwon to work. Since then there has been a regression.

(Review ID: 136615) 
======================================================================

Name: nt126004			Date: 01/08/2002


FULL PRODUCT VERSION :
Standard Doclet version 1.4.0 java version "1.4.0-beta3"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-beta3-b84)
Java HotSpot(TM) Client VM (build 1.4.0-beta3-b84, mixed mode)


FULL OPERATING SYSTEM VERSION :

Linux solomon-csi 2.2.12-20 #1 Wed Jun 14 14:52:43 CDT 2000
i686 unknown



A DESCRIPTION OF THE PROBLEM :
Javadoc seems to look in *all* the directories in the
CLASSPATH for source files.  If the same directory
appears twice, you get an error.  This appears to be
related to bugs 4548768 and 4532612.


REGRESSION.  Last worked in version 1.3.1

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1.setenv CLASSPATH .:.
2.mkdir pack2
3.echo "class Test {}" >pack2/Test.java
4.javadoc pack2

EXPECTED VERSUS ACTUAL BEHAVIOR :
Expected: No error.
Actual: 1 error, two warnings (see below)


ERROR MESSAGES/STACK TRACES THAT OCCUR :
Loading source files for package pack2...
Constructing Javadoc information...
/export/home/solomon/ws.trunk/source/./pack2/Test.java:1:
duplicate class:
Test
class Test {
^
javadoc: warning - No source files for package pack2
Standard Doclet version 1.4.0

Generating constant-values.html...
javadoc: No public or protected classes found to document.
1 error
2 warnings


This bug can be reproduced always.

---------- BEGIN SOURCE ----------
class Test {}

---------- END SOURCE ----------

CUSTOMER WORKAROUND :
Be very careful about your CLASSPATH, or specify the .java
file rather than the package.  However, the latter
work-around (suggested in 4548768) doesn't work, because of
bug 4506980: when .java files are passed in, the package
tree is not generated.  Only the overview tree is generated
in this case.
(Review ID: 137734)
======================================================================

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
hopper

FIXED IN:
hopper

INTEGRATED IN:
hopper

VERIFIED IN:
hopper


                                     
2004-06-14
PUBLIC COMMENTS

..
                                     
2004-06-10
EVALUATION

Notice bug 4532612 was closed as a duplicate of this bug.

###@###.### 2001-12-08

Javadoc provides sufficient information (in the source position) 
for the doclet to distinguish classes that are available in source 
form from those that aren't.  The PackageDoc does indeed provide 
access to all classes, even if those classes are not available in 
source form.  It is the responsibility of the doclet to document 
only the desired classes.

The user can work around this problem by specifying the source files
on the command line instead of the packages.

###@###.### 2001-12-11

PackageDoc.allClasses(), in spite of its name, is supposed to return
only the "included" classes, and should therefore filter out those
classes for which source is unavailable.

###@###.### 2001-12-11

Verified by running 
SourceOnly.sh from regression suite with b10 of hopper.
###@###.### 2002-04-25
                                     
2001-12-11



Hardware and Software, Engineered to Work Together