EVALUATION
Name: siR10004 Date: 11/05/2001
This bug is reproduced in all JDK's from version 1.2.
See the following report from IBM.
----------------------
IBM have recently come across a problem with the Swing Signature Test
in the JCK-13a. Running it against one of their implementations they
get the following errors:
SignatureTest report
Tested version: 1.3.1_01
Added Fields
------------
javax.swing.JTree$AccessibleJTree$AccessibleJTreeNode: field
protected
javax.accessibility.Accessible accessibleParent
javax.swing.plaf.metal.MetalInternalFrameUI: field
protected
javax.swing.plaf.basic.BasicInternalFrameTitlePane titlePane
javax.swing.plaf.metal.MetalScrollBarUI:field protected java.awt.Color
thumbColor
javax.swing.plaf.metal.MetalScrollBarUI:field protected java.awt.Color
thumbHighlightColor
result: Failed. 4 errors
After investigation of these failures we find the following:-
These fields are defined in the API documentation as being inherited
from their superclasses i.e. these protected fields should be made
available as part of the API Specification for these classes.
The Sun reference implementations overwrites these fields with private
equivalents, thus hiding these fields. Therefore the reference
implementation, and any implementation that used the reference class
libraries, is not consistent with the API Specification (but is
consistent with the Swing Signature Test.)
----------------------
IBM is right - javadoc documentation doesn't correspond to the reference
implementation. I believe that this bug is the cause of the problem.
Pointed by IBM problem exists in javadoc documentation for JDK versions
1.2, 1.3 and 1.4.
To reproduce it, generate javadoc documentation for
the following example:
------- X.java -------
package test;
public class X {
public int x;
}
----------------------
------- XX.java ------
package test;
public class XX extends X {
private int x;
}
----------------------
javadoc documentation for the class XX will contain
----------------------
public class XX
extends X
Field Summary
Fields inherited from class test.X
x
----------------------
Field x in class test.XX should not be listed as inherited from class test.X
because it is hidden by private field with the same name in the class test.XX.
If this problem will not be fixed, there can be similar reports
from licensees for merlin.
======================================================================
Name: siR10004 Date: 11/12/2001
Here are the numbers of hidden public/protected fields and inner classes
in JDK's in packages java,javax and org.
All these cases affected the javadoc documentation.
version hidden count
1.2.2 9
1.3 10
1.3.1 10
1.4.0(b84) 13
For the JDK 1.4 beta3 (b84) the full hiding list is as follows.
INNER static java.util.HashMap.Entry
HIDES public static interface abstract java.util.Map.Entry
INNER private static java.util.Hashtable.Entry
HIDES public static interface abstract java.util.Map.Entry
INNER private static java.util.LinkedHashMap.Entry
HIDES public static interface abstract java.util.Map.Entry
INNER static java.util.TreeMap.Entry
HIDES public static interface abstract java.util.Map.Entry
INNER private static java.util.WeakHashMap.Entry
HIDES public static interface abstract java.util.Map.Entry
FIELD private static final
javax.naming.directory.BasicAttribute.serialVersionUID
HIDES public static final javax.naming.directory.Attribute.serialVersionUID
FIELD private
javax.swing.JTree.AccessibleJTree.AccessibleJTreeNode.accessibleParent
HIDES protected javax.accessibility.AccessibleContext.accessibleParent
FIELD private javax.swing.plaf.metal.MetalInternalFrameUI.titlePane
HIDES protected javax.swing.plaf.basic.BasicInternalFrameUI.titlePane
FIELD private static javax.swing.plaf.metal.MetalScrollBarUI.thumbColor
HIDES protected javax.swing.plaf.basic.BasicScrollBarUI.thumbColor
FIELD private static
javax.swing.plaf.metal.MetalScrollBarUI.thumbHighlightColor
HIDES protected javax.swing.plaf.basic.BasicScrollBarUI.thumbHighlightColor
FIELD private static final org.apache.xalan.lib.sql.SQLDocument.S_NAMESPACE
HIDES protected static final org.apache.xalan.lib.sql.DTMDocument.S_NAMESPACE
FIELD private org.apache.xalan.transformer.KeyIterator.m_name
HIDES protected org.apache.xpath.patterns.NodeTest.m_name
FIELD private final org.apache.xalan.transformer.KeyRefIterator.m_name
HIDES protected org.apache.xpath.patterns.NodeTest.m_name
======================================================================
This will not be easy to fix. Right now javadoc lists inherited
members by listing members in the superclass. That's not right
because of hiding. But the doclet doesn't have any information
about the private members so it can't properly compute the hiding.
Fixing this may involve extending the javadoc API.
Rather than fixing it, I would prefer to first make javadoc
complain (and javac warn) whenever there is hiding of this sort.
And second, I would want to fix all of the APIs where this happens
to remove the hiding.
###@###.### 2001-12-03
I added methods to ClassDoc that can be used to detect member hiding.
If a member is overriden and declared private, the doclet no longer
documents that the member is inherited.
###@###.### 2002-06-03
|
Java
