United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4694497 BDoclet API: Bad ClassDoc for nested classes when built from .class files
JDK-4694497 : BDoclet API: Bad ClassDoc for nested classes when built from .class files

Details
Type:
Bug
Submit Date:
2002-05-30
Status:
Resolved
Updated Date:
2002-11-07
Project Name:
JDK
Resolved Date:
2002-11-07
Component:
tools
OS:
windows_98
Sub-Component:
javadoc(tool)
CPU:
x86
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.3.1
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

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
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
                                     
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
                                     
2002-09-09
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis
mantis-b07


                                     
2004-06-14



Hardware and Software, Engineered to Work Together