[jdk17] RFR: JDK-8259499: Handling type arguments from outer classes for inner class in javadoc [v2]

[Hannes Wallnöfer]

On Mon, 12 Jul 2021 16:43:33 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> This change adds support for generating HTML links to the type arguments of enclosing classes when creating a link to an inner class. Previously, only a link to the inner class was created and the type arguments were even omitted from the link label.
>> 
>> The new feature to create separate links to the enclosing class and its type arguments is only activated if the enclosing class has type arguments. If the enclosing class is non-generic, the old behavior is preserved to create a single link to the inner class. The reason for this is that a dedicated link to the enclosing class itself provides little benefit, since it can be easily reached via the "Enclosing class" link of the inner class. Also, linking the enclosing type in absence of type arguments makes it hard to see that there are two links and easy to click on the wrong link by mistake.
>> 
>> On the other hand, for type arguments a separate link should be useful since it is often not a "nearby" type. It is also easier to detect the different links than for non-generic nested classes. I came to like this "mixed" solution best after trying several other approaches.
>
> Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains four additional commits since the last revision:
> 
>  - JDK-8259499: Add newline at end of new test
>  - JDK-8259499: Refactor code to use new Utils.isGenericType method, add workaround and test for JDK-8269706
>  - Merge branch 'master' into JDK-8259499
>  - JDK-8259499: Handling type arguments from outer classes for inner class in javadoc

I have added a commit to this PR to add a Utils#isGenericType(TypeMirror) method that is used from `LinkInfo`, `LinkFactory` and `HtmlDocletWriter`. I think the code is actually a bit nicer now.

Interestingly, I stumbled over a NPE caused by JDK-8269706 when a generic reference is inherited from an overridden method. This bug existed before the last commit (and I think before this PR, although I didn't test this). Since we do not have the time to fix the root problem for 17, I added a workaround (triple null check in `CommentHelper`) as well as a test for the condition in `TestGenericTypeLink.java`.

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

PR: https://git.openjdk.java.net/jdk17/pull/195