RFR: JDK-8299896: Reduce enum values of HtmlLinkInfo.Kind

[Jonathan Gibbons]

On Thu, 12 Jan 2023 16:20:10 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review this change to drastically reduce the number of enum values in `HtmlLinkInfo.Kind` used to describe the format of a JavaDoc link. Previously the enum values were specific to the context in which a link was used. The new values describe the link format, such as whether to include preview information or type parameters or bounds. Other link properties that previously depended on this enum were moved into separate boolean flags as they are orthogonal to the link format and would have needlessly inflated the enum class. In some other cases the calling code had to be adapted slightly to generate the desired output. 
> 
> Apart from passing the tests, I made sure the new code generates the exact same output for the JDK documentation as the old code. Doing so I noticed that some generated links were not previously covered by tests. I added tests for these in the existing `TestInterface.java`.

Generally, very nice; it's nice to see abstractions being simplified and improved.

I didn't analyze the replacements in low-level detail; I'm OK with the tests being unchanged and you say the generated docs are unchanged.

I appreciate this is mostly just simplifying the `Kind` enum (and that's good!) but I think there  are possibilities for another round of cleanup on the `[Html]LinkInfo` item at some point down the road.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 127:

> 125:                 paramType).varargs(isVarArg);
> 126:         linkInfo.showTypeParameterAnnotations = true;
> 127:         Content link = writer.getLink(linkInfo);

How about providing and using a fluent setter method on `HtmlLinkInfo` ?

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

> 980:                 .fragment(id.name())
> 981:                 .style(style)
> 982:                 .targetMember(element));

Yay, I like this style.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java line 207:

> 205:         typeLinkInfo.addLineBreaksInTypeParameters = linkInfo.addLineBreaksInTypeParameters;
> 206:         typeLinkInfo.showTypeParameterAnnotations = linkInfo.showTypeParameterAnnotations;
> 207:         return getLink(typeLinkInfo);

It seems like there out to be a more convenient constructor or "copy"-ish sort of method on `HtmlLinkInfo`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkInfo.java line 44:

> 42:  * HTML-specific information about a link.
> 43:  */
> 44: public class HtmlLinkInfo extends LinkInfo {

OK, the diffs on this enum are sorta useless ;-). But the new code looks OK

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

> 70:      * True if we should print the type bounds for the type parameter.
> 71:      */
> 72:     public boolean showTypeBounds = true;

Maybe this and other fields on this class should be encapsulated, maybe with fluent setter methods? Maybe not now, but later?

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

Marked as reviewed by jjg (Reviewer).

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