JDK-4492178 : stddoclet: javadoc incorrectly lists hidden fields
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.3.1,1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2001-08-15
  • Updated: 2014-05-05
  • Resolved: 2002-09-02
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
Related Reports
Duplicate :  
Description

Name: ssR10172			Date: 08/15/2001



javadoc tool incorrectly lists fields which are hidden by private
field declaration. See JLS $8.2.1.3 for more details.

For example JDK 1.3.1 JavaDoc documentation lists following fields in
"Fields inherited from class XXX " table: 

In class javax.swing.JTree$AccessibleJTree$AccessibleJTreeNode: 
protected javax.accessibility.Accessible 
javax.swing.JTree$AccessibleJTree$AccessibleJTreeNode.accessibleParent

In class javax.swing.plaf.metal.MetalInternalFrameUI:
protected javax.swing.plaf.basic.BasicInternalFrameTitlePane 
javax.swing.plaf.metal.MetalInternalFrameUI.titlePane

In class javax.swing.plaf.metal.MetalScrollBarUI:
protected java.awt.Color javax.swing.plaf.metal.MetalScrollBarUI.thumbColor
protected java.awt.Color 
javax.swing.plaf.metal.MetalScrollBarUI.thumbHighlightColor

In class javax.naming.directory.BasicAttribute:
public static final long javax.naming.directory.BasicAttribute.serialVersionUID

But in all this classes we can find these variables declared as private:
In src/javax/swing/JTree.java:
	private Accessible accessibleParent = null;                                                                                     
In javax/swing/plaf/metal/MetalInternalFrameUI.java:
	private MetalInternalFrameTitlePane titlePane;
In javax/swing/plaf/metal/MetalScrollBarUI.java
	private static Color thumbColor;
	private static Color thumbHighlightColor;
In javax/naming/directory/BasicAttribute.java
	private static final long serialVersionUID = 6743528196119291326L;

If variable is declared as private it can not be listed as inherited,
since it's hidden and can not be mentioned as a public API.

Also the same problem with inherited inner classes:

In classes:
	java.security.Provider
	java.util.HashMap
	java.util.Hashtable
	java.util.Properties
	java.util.TreeMap
	java.util.WeakHashMap
	javax.swing.UIDefaults
there is a "Inner classes inherited from class XXX" table, which lists
"Map.Entry" inner class which is inherited from java.util.Map
But all this classes which implement java.util.Map also have their
one private innerclass "Entry" class. So all these classes should not
list "Map.Entry" as inherited inner class.

-------------------------------------------------------

======================================================================

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

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
03-06-2002

PUBLIC COMMENTS This bug has been fixed. The standard doclet now detects member hiding and does not list hidden members as inherited. ###@###.### 2002-06-03
03-06-2002