JDK-4694497 : BDoclet API: Bad ClassDoc for nested classes when built from .class files
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.3.1
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: windows_98
  • CPU: x86
  • Submitted: 2002-05-30
  • Updated: 2002-11-07
  • Resolved: 2002-11-07
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.4.2 mantisFixed
Description

Name: nt126004			Date: 05/30/2002


FULL PRODUCT VERSION :
java version "1.3.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build
1.3.1_01)
Java HotSpot(TM) Client VM (build 1.3.1_01, mixed mode)

FULL OPERATING SYSTEM VERSION :
Windows 98 [versione 4.10.2222]

A DESCRIPTION OF THE PROBLEM :
Hello,

I think there is a bug in Javadoc concerning nested classes
ClassDoc records extracted through the doclet API.

In particular,
ClassDoc records are correct if the container class is directly
specified on the command line as a .java file or part of a package (i.e. the
source is available), but they are (at times) wrong if the records are
built from .jar (.class) files through the classpath.

Example with
"java.io.ObjectOutputStream" from JDK 1.3.1_01:

If the ClassDoc
for this class comes from RootDoc.specifiedClasses(), its nested
classes are correctly listed as:

private static final class java.io.ObjectOutputStream.HandleTable
public abstract static class java.io.ObjectOutputStream.PutField
static final class java.io.ObjectOutputStream.PutFieldImpl
private static final class java.io.ObjectOutputStream.ReplaceTable
private static final class java.io.ObjectOutputStream.Stack

but if the ClassDoc
of the container class is extracted from a method parameter, like in
org.apache.xerces.dom.ParentNode.writeObject(ObjectOutputStream
out), this is the result:

final synchronized class java.io.ObjectOutputStream$HandleTable
public abstract static class java.io.ObjectOutputStream.PutField
static final class java.io.ObjectOutputStream.PutFieldImpl
final synchronized class java.io.ObjectOutputStream$ReplaceTable
final synchronized class java.io.ObjectOutputStream$Stack

According
to my tests, at least ClassDoc.modifiers(), ClassDoc.qualifiedName()
and ClassDoc.containingClass() return incorrect results for
HandleTable, ReplaceTable and Stack.

This behaviour seems common
to both Javadoc 1.3.1_01 and 1.4beta3.

This bug can be reproduced occasionally.
(Review ID: 146941) 
======================================================================

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis mantis-b07
14-06-2004

EVALUATION When a ClassDoc is build from the classpath, a call to innerClasses() returns the wrong results because of this piece of code in DocEnv.java: public boolean shouldDocument(ClassSymbol sym) { return (sym.flags_field & Flags.SYNTHETIC) == 0 && getClassDoc(sym).tree != null && isVisible(sym); } If "getClassDoc(sym).tree != null" is removed, innerClasses() will return the correct list of inner classes. I think that it would be ok to remove this check. The tree is only used in the position() method. If tree is null for a particular inner class, that should not prevent it from being added to the list of inner classes. I don't know enough about the javac/javadoc source code to fix the bug related to modifiers(). I will reassign this bug to Neal. ###@###.### 2002-09-09 I don't think this analysis above is the whole story. We need to take into account the inner class attribute when loading class files. ###@###.### 2002-09-09
09-09-2002

PUBLIC COMMENTS I have verified that this is a bug. I will assign this bug to Neal Gafter since the bug is definitely in the Javadoc tool. When testing with the current version of Javadoc (1.4.2), I get the correct results for qualifiedName() and containingClass(). However, I agree with the bug submitter that the Doclet API returns incorrect results for modifiers() and innerClasses(). ###@###.### 2002-09-09
09-09-2002