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

[Jonathan Gibbons]

On Thu, 1 Jul 2021 13:50:25 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.

What is the type arguments are themselves type variables: e.g. `@see Map<P,Q>`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1082:

> 1080:             // Must be a class reference since refClass is not null and refMemName is null.
> 1081:             if (labelContent.isEmpty()) {
> 1082:                 if (seeText.contains("<")) {

Hmmm, string-based checks are generally something of a red-flag, as compared to more abstract methods on appropriate classes. And, this is a string operation on the output of  `CommentHelper.getText`. Is there a way that we have may this a more robust test ... for example introduce `CommentHelper.isGeneric(ReferenceTree)` or something like that?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/links/LinkInfo.java line 132:

> 130:         // from the documentation of an inner class, so rendering it as separate link would
> 131:         // add little benefit but add considerable noise, while type arguments may not
> 132:         // otherwise be reachable from the documentation of the inner class.

Do you render the _enclosing types_ as separate links, or just  the _type arguments of enclosing types_?

Even if the enclosing type has type arguments, your argument about the noise from linking the name of the enclosing type is still valid.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/links/LinkInfo.java line 154:

> 152:         } else if (isLinkable()) {
> 153:             Content tlabel = newContent();
> 154:             tlabel.add(type instanceof DeclaredType dt && linkEnclosingTypes(dt)

There's a philosophical discussion to be had, separately, with Joe, about using `instanceof` with Language Model types. since the beginning, i`nstanceof` has been discouraged in favor of using `getKind()` but the reasons for that may have faded, and "instanced patterns" may be enough of a reason to change the guidelines.

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

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