RFR: JDK-8302324: Inheritance tree does not show correct type parameters/arguments

[Pavel Rappo]

On Mon, 13 Feb 2023 20:22:59 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a simple change to show the correct type parameters or arguments in the inheritance list in the class documentation header. The solution is simply to move the implementation of `Utils.getFirstVisibleSuperClass(...)` from the method with a `TypeElement` parameter to the one with a `TypeMirror` parameter, thereby preserving the type arguments.
> 
> I compared JDK API docs with and without this change, and the only change is that inheritance with generic superclasses is now rendered correctly. For instance, the inheritance list for `java.util.Properties` used to look like this:
> 
> 
> java.lang.Object
>     java.util.Dictionary<K,V>
>         java.util.Hashtable<Object,Object>
>             java.util.Properties
> 
> Now it is generated as follows:
> 
> java.lang.Object
>     java.util.Dictionary<Object,Object>
>         java.util.Hashtable<Object,Object>
>             java.util.Properties

This looks good. I've spotted a few places that warrant a deep cleanup, which accidentally I'm doing at the moment.

test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java line 65:

> 63:                      * @param <P> param P
> 64:                      */
> 65:                     public class B<O, P>  extends A<O, P> { private B() { } }

Suggestion:

                    public class B<O, P> extends A<O, P> { private B() { } }

test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java line 65:

> 63:                      * @param <P> param P
> 64:                      */
> 65:                     public class B<O, P>  extends A<O, P> { private B() { } }

The source is non-compilable due to constructors being private; is it done on purpose?

test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java line 73:

> 71:                      * @param <Q> param Q
> 72:                      */
> 73:                     public class C<Q>  extends B<String, Q>{ private C() { } }

Suggestion:

                    public class C<Q> extends B<String, Q> { private C() { } }

test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java line 82:

> 80:                      * @param <S> param S
> 81:                      */
> 82:                     public class D<R, S>  extends B<S, B>{ private D() { } }

Suggestion:

                    public class D<R, S> extends B<S, B> { private D() { } }

test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java line 82:

> 80:                      * @param <S> param S
> 81:                      */
> 82:                     public class D<R, S>  extends B<S, B>{ private D() { } }

While it's good for testing, recursive parametrization `B<B>` might not be what it seems. The second occurrence of B is a raw type.

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

Marked as reviewed by prappo (Reviewer).

PR: https://git.openjdk.org/jdk/pull/12544