Bug 221041

Description Jeremy 2008-03-01 15:51:22 EST

Build ID: M20071023-1652

Steps To Reproduce:
1. Ensure that Eclipse > Java > Compiler > Javadoc settings are set with all checkboxes checked; all potential problems set to "warnings" and members considered up to "private".
2. Copy and paste the two classes below into Eclipse.
3. Observe that Eclipse shows 3 javadoc warnings for the "SubClass" class.
4. Run Project > Generate Javadoc... and create javadoc for visibility up to private.
5. Observe that the javadoc generation produced exactly one warning, "SubClass.java:25: warning - Tag @link: can't find foo(String) in javadoc.generics.SubClass" and that it is NOT one of the warnings observed in step 3.  Thus Eclipse has made four mistakes.

More information:
I have attempted to put sufficient information in the documentation in the classes below.  Basically there are two points in the following.  One is that type erasure means that SuperClass contains the method foo(Object).  But, from within SubClass, Eclipse thinks that it is foo(String), even though it is not overridden in SubClass.  Therefore, Eclipse is not generating javadoc warnings for the nonexistent method foo(String) but it is generating javadoc warnings for the method foo(Object).  This is backwards.

The second point, illustrated using SuperClass.bar(), is that Eclipse seems to be confused with regards to static methods which take generic arguments whose specification includes '&'.  Again, type erasure means that the method is really bar(Number).  But because Number is not Comparable, 
Eclipse doesn't seem to accept this.  Interestingly, Eclipse does not complain for instance methods, though.

file javadoc/generics/SuperClass.java:

package javadoc.generics;

/**
 * a placeholder class with some methods for illustrating problems
 * with some Eclipse javadoc warnings, related to generics.
 * This class is required to set up the generics.
 * The spurious and missing javadoc warnings all appear in {@link SubClass}.   
 * 
 * @param <T> some type
 * 
 * @see SubClass
 */
public class SuperClass<T> {
    
    /**
     * a generic method
     * 
     * @param t a placeholder argument of generic type
     */
    protected void foo(T t) {
    }
    
    /**
     * a generic method, for which the generic type has definite
     * superclass, but also additional restrictions.
     * 
     * @param <N> the type of the argument
     * @param n a placeholder argument of a particular generic type
     */
    public static <N extends Number & Comparable<? super N>> void bar(N n) {
    }
    
}

file javadoc/generics/SubClass.java:

package javadoc.generics;

/**
 * A class for illustrating problems with some Eclipse javadoc warnings.
 * For example, Eclipse gives a warning here, even though
 * type erasure implies that {@link #foo(Object)} exists.
 * Note that {@code javadoc} itself has no problem creating this link.
 * Also note that because of inheritance, there is no need to specify
 * the superclass in these links.  It appears, however, that referring
 * to {@link SuperClass#foo(Object)} can be done without problem.
 * 
 * @see SuperClass
 */
public class SubClass extends SuperClass<String> {
    
    /**
     * This method exists for the following comment.
     * Because of type erasure,
     * {@link #foo(String)} does not exist,
     * yet, unlike the correct link in the description of this class,
     * Eclipse gives no warning here.
     * 
     * 
     */
    protected void foobar() {
    }
    
    /**
     * This method exists for the following comment.
     * Because of type erasure,
     * {@link #bar(Number)} exists, yet we get an Eclipse
     * warning here.  Interestingly, there was no warning until I made
     * {@link SuperClass#bar(Number)} {@code public static}
     * (from {@code protected} and instance).  Notice that here,
     * specifying the class explicitly is irrelevant--although good form
     * demands specifying the superclass since static methods are strictly
     * speaking not inherited.
     */
    protected void barfoo() {
    }

}