RFR: 8266666: Implementation for snippets [v23]

[Pavel Rappo]

On Mon, 13 Sep 2021 11:59:06 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Remove trailing whitespace to satisfy jcheck
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1193:
> 
>> 1191:             }
>> 1192:         } else if (refMemName == null) {
>> 1193:             // Must be a class reference since refClass is not null and refMemName is null.
> 
> One problem with the code duplication introduced with this method is that fixes in `seeTagToContent` are not picked up in this method. One instance where this might already have occurred is JDK-8259499, which affected the code below. I would propose to go through changes in `seeTagToContent` since the snippet branch was created and look for simple fixes to "port". 
> 
> As a long term solution, the best way to go may not be to unify these methods but rather extract common pieces of code that can be used by both methods. They are way too long and convoluted anyway. It may be a good idea to file a JBS issue for this.

The reason I extracted a separate method rather than reused the existing one is not because I disagree with what you are saying. It's because I couldn't find an easy way to reuse the existing method.

`seeTagToContent` uses the tree node corresponding to a link/see tag, for example, to construct a tree path. In snippet `@link` markup tag, there's no corresponding `LinkTree`. When I tried to quickly fabricate it, I found out that it cannot be easily done. For deep fabrication, one needs to embed a fake node into the tree structure at least for the duration of call to `seeTagToContent`. At that stage I decided not to explore that further.

I filed a bug as you suggested: https://bugs.openjdk.java.net/browse/JDK-8273721.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 138:
> 
>> 136:         return treeFactory.newLinkPlainTree(ref, List.of(makeTextTree(label)));
>> 137:     }
>> 138: 
> 
> It looks like these two new methods aren't used anywhere (according to IntelliJ).

These two methods are what has left of my failed attempt to fabricate a `LinkTree` node to process the `@link` snippet markup tag. I will remove them, thanks.

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

PR: https://git.openjdk.java.net/jdk/pull/4795