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





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.

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

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

N/A

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.



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




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.

 xxxxx@xxxxx  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.
 xxxxx@xxxxx  2002-06-03