Mistaken warning for @see in private serialized nested class to private method

Name: rmT116609 Date: 01/16/2003


FULL PRODUCT VERSION :
java version "1.4.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01)
Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode)


Linux dhcppc3 2.4.18-18.7.x #1 Wed Nov 13 20:29:30 EST 2002
i686 unknown
glibc-2.3.1-6
Red Hat Linux release 7.2 (Enigma)


A DESCRIPTION OF THE PROBLEM :
The javadoc tool when run in default mode (public/protected
only) will sometimes warn about a @see tag pointing to a
private member, which is a broken link since the member will
not be documented, even though the @see tag is in the
comment block for a private nested class.

This only happens when the nested and outer classes are
serializable, so I suspect some bug in the code to generate
the Serialized Form pages - probably it is forcing doc
generation to occur even for classes/members that will not
be documented and do not need it. JDK 1.4.x only.

Especially of interest in the example case is that the
serializable nested class is static and does not even appear
in the Serializable Form page (only a.X does, with no data
fields). I.e. there is no reason to have been processing its
comment block whatsoever.

FYI, source code in which I ran across this bug:

http://www.netbeans.org/source/browse/openide/src/org/openide/awt/ListPane.java?rev=1.24&content-type=text/x-cvsweb-markup

With warnings along the lines of:

warning - Tag @see: can't find createDataListener in
org.openide.awt.ListPane.DataListener
warning - Tag @see: can't find createInputListener in
org.openide.awt.ListPane.InputListener
warning - Tag @see: can't find registerKeyboardActions in
org.openide.awt.ListPane.InputListener
warning - Tag @see: can't find createPropertyListener in
org.openide.awt.ListPane.PropertyListener

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Create a file a/X.java with indicated contents.

2. Run "javadoc a" and look at log messages.

EXPECTED VERSUS ACTUAL BEHAVIOR :
Expected: no warnings. More generally, that @see references
to a private member from another private member should be
honored when running with -private and completely ignored
otherwise. Normally this is the case, just not in this
unusual case.

Actual: one warning, q.v.

ERROR MESSAGES/STACK TRACES THAT OCCUR :
Complete log including gratuitous warning:

Loading source files for package a...
Constructing Javadoc information...
Standard Doclet version 1.4.1

Generating constant-values.html...
Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating packages.html...
Generating a/package-frame.html...
Generating a/package-summary.html...
Generating a/package-tree.html...
Generating a/X.html...
Generating serialized-form.html...
/tmp/javadocseetest/./a/X.java:6: warning - Tag @see: can't find m in a.X.P
Generating package-list...
Generating help-doc.html...
Generating stylesheet.css...
1 warning

The problem is not reproducible with JDK1.3.1_06.

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
package a;
import java.io.Serializable;
public class X implements Serializable {
    private void m() {}
    /** @see #m */
    private static class P implements Serializable {}
}

---------- END SOURCE ----------

CUSTOMER WORKAROUND :
None known, except deleting the @see tag.
(Review ID: 179453)
======================================================================