RFR: 8266666: Implementation for snippets [v23]

[Hannes Wallnöfer]

On Thu, 9 Sep 2021 15:27:34 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This PR implements JEP 413 "Code Snippets in Java API Documentation", which hasn't been yet proposed to target JDK 18. The PR starts as a squashed merge of the https://github.com/openjdk/jdk-sandbox/tree/jdk.javadoc/snippets branch.
>
> 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.

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).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 297:

> 295:             // corresponding positions in snippet source.
> 296:             final String value = regex.get().value();
> 297:             assert value.equals(Pattern.compile(value).pattern()) : value;

What is the purpose of this assertion, and when would it ever fail?

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

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