8266666: Implementation for snippets

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java

@@ -49,7 +49,6 @@
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
 import com.sun.source.doctree.IdentifierTree;
-import com.sun.source.doctree.LinkTree;
 import com.sun.source.doctree.LiteralTree;
 import com.sun.source.doctree.ParamTree;
 import com.sun.source.doctree.ReferenceTree;
@@ -126,16 +125,6 @@ public DocTree makeSeeTree(String sig, Element e) {
         return treeFactory.newSeeTree(List.of(treeFactory.newReferenceTree(sig)));
     }
 
-    public LinkTree makeLinkTree(String sig, String label) {
-        ReferenceTree ref = treeFactory.newReferenceTree(sig);
-        return treeFactory.newLinkTree(ref, List.of(makeTextTree(label)));
-    }
-
-    public LinkTree makeLinkPlainTree(String sig, String label) {
-        ReferenceTree ref = treeFactory.newReferenceTree(sig);
-        return treeFactory.newLinkPlainTree(ref, List.of(makeTextTree(label)));
-    }
-
     public TextTree makeTextTree(String content) {
         return treeFactory.newTextTree(content);
     }

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

@@ -289,21 +289,20 @@ private Pattern createRegexPattern(Optional<Attribute.Valued> substring,
             // this Pattern.compile *should not* throw an exception
             pattern = Pattern.compile(defaultRegex);
         } else {
-            // Unlike string literals in Java source, attribute values in
-            // snippet markup do not use escapes. This is why indices of
-            // characters in the regex pattern directly map to their
-            // corresponding positions in snippet source.
             final String value = regex.get().value();
-            assert value.equals(Pattern.compile(value).pattern()) : value;
             try {
                 pattern = Pattern.compile(value);
             } catch (PatternSyntaxException e) {
+                // Unlike string literals in Java source, attribute values in
+                // snippet markup do not use escape sequences. This is why
+                // indices of characters in the regex pattern directly map to
+                // their corresponding positions in snippet source. Refine
+                // position using e.getIndex() only if that index is relevant to
+                // the regex in the attribute value. Index might be irrelevant
+                // because it refers to an internal representation of regex,
+                // e.getPattern(), which might be a normalized or partial view
+                // of the original pattern.
                 int pos = offset + regex.get().valueStartPosition();
-                // Refine position using e.getIndex() only if that index is
-                // relevant to the regex in the attribute value. Index might be
-                // irrelevant because it refers to an internal representation of
-                // regex, e.getPattern(), which might be a normalized or partial
-                // view of the original pattern.
                 if (e.getIndex() > -1 && value.equals(e.getPattern())) {
                     pos += e.getIndex();
                 }

test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java

@@ -243,8 +243,7 @@ public void testBadTagSyntax(Path base) throws IOException {
         class Capture {
             static final AtomicInteger counter = new AtomicInteger();
 
-            record TestCase(String input, String expectedError) {
-            }
+            record TestCase(String input, String expectedError) { }
 
             void testErrors(List<TestCase> testCases) throws IOException {
                 List<String> inputs = testCases.stream().map(s -> s.input).toList();
@@ -2144,4 +2143,88 @@ record TestCase(Snippet snippet, String expectedOutput) { }
                         </div>""".formatted(index, t.expectedOutput()));
         });
     }
+
+    @Test
+    public void testInvalidRegexDiagnostics(Path base) throws Exception {
+
+        record TestCase(String input, String expectedError) { }
+
+        // WARNING: debugging these test cases by reading .jtr files might prove
+        // confusing. This is because of how jtharness, which is used by jtreg,
+        // represents special symbols it encounters in standard streams. While
+        // CR, LR and TAB are output as they are, \ is output as \\ and the rest
+        // of the escape sequences are output using the \\uxxxx notation. This
+        // might affect relative symbol positioning on adjacent lines. For
+        // example, it might be hard to judge the true (i.e. console) position
+        // of the caret. Try using -show:System.out jtreg option to remediate
+        // that.
+
+        final var testCases = List.of(
+                new TestCase("""
+{@snippet :
+hello there //   @highlight   regex ="\t**"
+}""",
+                             """
+error: snippet markup error: "Dangling meta character '*'"
+hello there //   @highlight   regex ="\t**"
+                                      \t ^
+"""),
+                new TestCase("""
+{@snippet :
+hello there //   @highlight   regex ="\\t**"
+}""",
+                        """
+error: snippet markup error: "Dangling meta character '*'"
+hello there //   @highlight   regex ="\\t**"
+                                         ^
+"""),
+                new TestCase("""
+{@snippet :
+hello there // @highlight regex="\\.\\*\\+\\E"
+}""",
+                             """
+error: snippet markup error: "Illegal/unsupported escape sequence"
+hello there // @highlight regex="\\.\\*\\+\\E"
+                                 \s\s\s\s   ^
+"""), // use \s to counteract shift introduced by \\ so as to visually align ^ right below E
+                new TestCase("""
+{@snippet :
+hello there //   @highlight  type="italics" regex ="  ["
+}""",
+                        """
+error: snippet markup error: "Unclosed character class"
+hello there //   @highlight  type="italics" regex ="  ["
+                                                      ^
+""")
+                );
+
+        List<String> inputs = testCases.stream().map(s -> s.input).toList();
+        StringBuilder methods = new StringBuilder();
+        forEachNumbered(inputs, (i, n) -> {
+            methods.append(
+                    """
+
+                    /**
+                    %s*/
+                    public void case%s() {}
+                    """.formatted(i, n));
+        });
+
+        String classString =
+                """
+                public class A {
+                %s
+                }
+                """.formatted(methods.toString());
+
+        Path src = Files.createDirectories(base.resolve("src"));
+        tb.writeJavaFiles(src, classString);
+
+        javadoc("-d", base.resolve("out").toString(),
+                "-sourcepath", src.toString(),
+                src.resolve("A.java").toString());
+        checkExit(Exit.ERROR);
+        checkOrder(Output.OUT, testCases.stream().map(TestCase::expectedError).toArray(String[]::new));
+        checkNoCrashes();
+    }
 }