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 Availabitlity Release.

To download the current JDK release, click here.
1.4.2 mantisFixed

Name: nt126004			Date: 05/30/2002

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

Windows 98 [versione 4.10.2222]


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
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

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) 

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

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

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