runtime(java): Recognise the {@snippet} documentation tag (#14271)

Remember that ‘code fragments are typically Java source
code, but they may also be fragments of properties files,
source code in other languages, or plain text.’  Therefore,
with these changes, markup tags are highlighted in the Java
source files (as external snippets) and in the {@snippet}
tags.

Also:

- Improve matching of the multi-line {@code} documentation
  tag with any contained balanced braces.
- Recognise the {@literal} documentation tag.
- Highlight stray blanks in comments.

Related to an enhancement proposal for PCRE-like callouts
discussed at https://github.com/vim/vim/issues/11217.

References:
https://openjdk.org/jeps/413
https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html

Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

4 files changed, 85 insertions, 0 deletions

diff --git a/runtime/syntax/testdir/dumps/java_comments_00.dump b/runtime/syntax/testdir/dumps/java_comments_00.dump
new file mode 100644
index 0000000000..bc1f359d9d
--- /dev/null
+++ b/runtime/syntax/testdir/dumps/java_comments_00.dump
@@ -0,0 +1,20 @@
+>/+0#0000e05#ffffff0@1| |V|I|M|_|T|E|S|T|_|S|E|T|U|P| |u|n|l|e|t|!| |g+0&#5fd7ff255|:+0&#ffffff0|j|a|v|a|_|i|g|n|o|r|e|_|j+0&#ffd7d7255|a|v|a|d|o|c| +0&#ffffff0|g|:|j|a|v|a|_|n|o|_|t|r|a|i|l|_|s|p|a|c|e|_|e|r@1|o|r| +0#ffffff16#ff404010
+|/+0#0000e05#ffffff0@1| |V|I|M|_|T|E|S|T|_|S|E|T|U|P| |u|n|l|e|t|!| |g+0&#5fd7ff255|:+0&#ffffff0|j|a|v|a|_|n|o|_|t|a|b|_|s|p|a|c|e|_|e|r@1|o|r| +0#ffffff16#ff404010@1| +0#0000000#ffffff0@22
+|/+0#0000e05&@1| |V|I|M|_|T|E|S|T|_|S|E|T|U|P| |l|e|t| |[|g|:|j|a|v|a|_|s|p|a|c|e|_|e|r@1|o|r|s|,|g|:|j|a|v|a|_|c|o|m@1|e|n|t|_|s|t|r|i|n|g|s|]| |=| |[|1+0#e000002&|,+0#0000e05&|1+0#e000002&|]+0#0000e05&| +0#0000000&
+|/+0#0000e05&@1| +0#ffffff16#ff404010| +0#0000e05#ffffff0|V|I|M|_|T|E|S|T|_|S|E|T|U|P| |s+0&#ffd7d7255|e|t|l|o|c|a|l| +0&#ffffff0|s|p|e|l@1| +0#0000000&@41
+|c+0#00e0003&|l|a|s@1| +0#0000000&|C|o|m@1|e|n|t|s|T|e|s|t|s| @55
+|{| @2|/+0#0000e05&|*| +0#ffffff16#ff404010| +0#0000e05#ffffff0|T|R|A|I|L|I|N|G| |B|L|A|N|K|S| |A|N|D| |M+0&#ffd7d7255|E|S@1|P|I|L@1|I|N|G|S| +0&#ffffff0|A|R|E| |S|I|G|N|I|F|I|C|A|N|T|!| |*|/| +0#ffffff16#ff404010@3| +0#0000000#ffffff0@10
+@4|/+0#0000e05&|*@1| +0#ffffff16#ff404010| +0#0000000#ffffff0@66
+| +0#0000e05&@4|*| +0#e000e06&|T|h|e| |m|e|t|h|o|d| |{|@|c|o|d|e| |m|a|i|n|}| |m|u|s|t| |b|e| |d|e|c|l|a|r|e|d| |{|@|c|o|d|e| |p|u|b|l|i|c|}|,| |{|@|c|o|d|e| +0#0000000&@4
+| +0#e000e06&@4|*| |s|t|a|t|i|c|}|,| |a|n|d| |{|@|c|o|d|e| |v|o|i|d|}|.| +0#0000e05&@1|I|t| |m|u|s|t| |s|p|e|c|i|f|y| |a| |f|o|r|m|a|l| |p|a|r|a|m|e|t|e|r| +0#0000000&@5
+| +0#0000e05&@4|*| |w|h|o|s|e| |d|e|c|l|a|r|e|d| |t|y|p|e| |i|s| |a|r@1|a|y| |o|f| |{+0#e000e06&|@|l|i|n|k| |S|t|r|i|n|g|}|.+0#0000e05&| @1|T|h|e|r|e|f|o|r|e|,| +0#0000000&@8
+| +0#0000e05&@4|*| |e|i|t|h|e|r| |o|f| |t|h|e| |f|o|l@1|o|w|i|n|g| |d|e|c|l|a|r|a|t|i|o|n|s| |i|s| |a|c@1|e|p|t|a|b|l|e|:| +0#0000000&@16
+| +0#0000e05&@4|*| +0#ffffff16#ff404010| +0#0000e05#ffffff0|{+0#e000e06&|@|s|n|i|p@1|e|t| |l+0#00e0003&|a|n|g|=+0#e000e06&|"+0#e000002&|j|a|v|a|"|:+0#e000e06&| +0#0000000&@44
+| +0#e000e06&@4|*| |/@1| |@+0#0000000&|h|i|g|h|l|i|g|h|t| +0#e000e06&|s+0#00e0003&|u|b|s|t|r|i|n|g|=+0#e000e06&|"+0#e000002&|m|a|i|n|"| +0#e000e06&|t+0#00e0003&|y|p|e|=+0#e000e06&|"+0#e000002&|i|t|a|l|i|c|"|:+0#e000e06&| +0#0000000&@22
+| +0#e000e06&@4|*| |p|u|b|l|i|c| |s|t|a|t|i|c| |v|o|i|d| |m|a|i|n|(|S|t|r|i|n|g|[|]| |a|r|g|s|)| |{| |}| +0#0000000&@25
+| +0#e000e06&@4|*| |}|<+0#00e0e07&|b+0#af5f00255&|r| +0#00e0e07&|/|>|<|p+0#af5f00255&|r|e| +0#00e0e07&|c+0#00e0003&|l|a|s@1|=+0#00e0e07&|"+0#e000002&|s|n|i|p@1|e|t|"|>+0#00e0e07&| +0#0000000&@39
+| +0#0000e05&@4|*|{+0#e000e06&|@|c|o|d|e| |p|u|b|l|i|c| |s|t|a|t|i|c| |v|o|i|d| |m|a|i|n|(|S|t|r|i|n|g|.@2| |a|r|g|s|)| |{| |}@1|<+0#00e0e07&|/|p+0#af5f00255&|r|e|>+0#00e0e07&| +0#0000000&@11
+| +0#0000e05&@4|*| +0#0000000&@68
+| +0#0000e05&@4|*| |@+0#e000e06&|p|a|r|a|m| +0#00e0e07&|a|r|g|s| +0#0000e05&|o|p|t|i|o|n|a|l| |c+0&#ffd7d7255|o|m@1|a|n|d|e|-+0&#ffffff0|l|i|n|e| |a|r|g|u|m|e|n|t|s| +0#ffffff16#ff404010| +0#0000000#ffffff0@22
+| +0#0000e05&@4|*| |@|j+0&#ffd7d7255|l|s| +0&#ffffff0|1|2|.|1|.|4| |I|n|v|o|k|e| |{+0#e000e06&|@|c|o|d|e| |T|e|s|t|.|m|a|i|n|}| +0#0000000&@31
+@57|1|,|1| @10|T|o|p| 
diff --git a/runtime/syntax/testdir/dumps/java_comments_01.dump b/runtime/syntax/testdir/dumps/java_comments_01.dump
new file mode 100644
index 0000000000..9f92f83b81
--- /dev/null
+++ b/runtime/syntax/testdir/dumps/java_comments_01.dump
@@ -0,0 +1,20 @@
+| +0#e000e06#ffffff0@4|*| |p|u|b|l|i|c| |s|t|a|t|i|c| |v|o|i|d| |m|a|i|n|(|S|t|r|i|n|g|[|]| |a|r|g|s|)| |{| |}| +0#0000000&@25
+| +0#e000e06&@4|*| |}|<+0#00e0e07&|b+0#af5f00255&|r| +0#00e0e07&|/|>|<|p+0#af5f00255&|r|e| +0#00e0e07&|c+0#00e0003&|l|a|s@1|=+0#00e0e07&|"+0#e000002&|s|n|i|p@1|e|t|"|>+0#00e0e07&| +0#0000000&@39
+| +0#0000e05&@4|*|{+0#e000e06&|@|c|o|d|e| |p|u|b|l|i|c| |s|t|a|t|i|c| |v|o|i|d| |m|a|i|n|(|S|t|r|i|n|g|.@2| |a|r|g|s|)| |{| |}@1|<+0#00e0e07&|/|p+0#af5f00255&|r|e|>+0#00e0e07&| +0#0000000&@11
+| +0#0000e05&@4|*| +0#0000000&@68
+| +0#0000e05&@4|*| |@+0#e000e06&|p|a|r|a|m| +0#00e0e07&|a|r|g|s| +0#0000e05&|o|p|t|i|o|n|a|l| |c+0&#ffd7d7255|o|m@1|a|n|d|e|-+0&#ffffff0|l|i|n|e| |a|r|g|u|m|e|n|t|s| +0#ffffff16#ff404010| +0#0000000#ffffff0@22
+| +0#0000e05&@4>*| |@|j+0&#ffd7d7255|l|s| +0&#ffffff0|1|2|.|1|.|4| |I|n|v|o|k|e| |{+0#e000e06&|@|c|o|d|e| |T|e|s|t|.|m|a|i|n|}| +0#0000000&@31
+| +0#0000e05&@4|*|/| +0#0000000&@67
+@4|/+0#0000e05&@1| |@+0#0000000&|s|t|a|r|t| +0#0000e05&|r+0#00e0003&|e|g|i|o|n| +0#0000e05&|=| |m+0#e000002&|a|i|n| +0#0000000&@47
+@4|/+0#0000e05&@1| |@+0#0000000&|l|i|n|k| +0#0000e05&|s+0#00e0003&|u|b|s|t|r|i|n|g| +0#0000e05&|=| |'+0#e000002&|S|t|r|i|n|g|'| +0#0000e05&|t+0#00e0003&|a|r|g|e|t| +0#0000e05&|=| |'+0#e000002&|j|a|v|a|.|l|a|n|g|.|S|t|r|i|n|g|'| +0#0000e05&|:| +0#0000000&@11
+@4|p+0#00e0003&|u|b|l|i|c| +0#0000000&|s+0#00e0003&|t|a|t|i|c| +0#0000000&|v+0#00e0003&|o|i|d| +0#0000000&|m|a|i|n|(|S|t|r|i|n|g|[|]| |a|r|g|s|)| |{| |}| @28
+@4|/+0#0000e05&@1| |@+0#0000000&|e|n|d| @63
+|}| @73
+|~+0#4040ff13&| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+| +0#0000000&@56|1|9|,|3|-|6| @7|B|o|t| 
diff --git a/runtime/syntax/testdir/dumps/java_comments_99.dump b/runtime/syntax/testdir/dumps/java_comments_99.dump
new file mode 100644
index 0000000000..024dc4888e
--- /dev/null
+++ b/runtime/syntax/testdir/dumps/java_comments_99.dump
@@ -0,0 +1,20 @@
+| +0&#ffffff0@3|/+0#0000e05&|*@1| +0#ffffff16#ff404010| +0#0000000#ffffff0@66
+| +0#0000e05&@4|*| +0#e000e06&|T|h|e| |m|e|t|h|o|d| |{|@|c|o|d|e| |m|a|i|n|}| |m|u|s|t| |b|e| |d|e|c|l|a|r|e|d| |{|@|c|o|d|e| |p|u|b|l|i|c|}|,| |{|@|c|o|d|e| +0#0000000&@4
+| +0#e000e06&@4|*| |s|t|a|t|i|c|}|,| |a|n|d| |{|@|c|o|d|e| |v|o|i|d|}|.| +0#0000e05&@1|I|t| |m|u|s|t| |s|p|e|c|i|f|y| |a| |f|o|r|m|a|l| |p|a|r|a|m|e|t|e|r| +0#0000000&@5
+| +0#0000e05&@4|*| |w|h|o|s|e| |d|e|c|l|a|r|e|d| |t|y|p|e| |i|s| |a|r@1|a|y| |o|f| |{+0#e000e06&|@|l|i|n|k| |S|t|r|i|n|g|}|.+0#0000e05&| @1|T|h|e|r|e|f|o|r|e|,| +0#0000000&@8
+| +0#0000e05&@4|*| |e|i|t|h|e|r| |o|f| |t|h|e| |f|o|l@1|o|w|i|n|g| |d|e|c|l|a|r|a|t|i|o|n|s| |i|s| |a|c@1|e|p|t|a|b|l|e|:| +0#0000000&@16
+| +0#0000e05&@4|*| +0#ffffff16#ff404010| +0#0000e05#ffffff0|{+0#e000e06&|@|s|n|i|p@1|e|t| |l+0#00e0003&|a|n|g|=+0#e000e06&|"+0#e000002&|j|a|v|a|"|:+0#e000e06&| +0#0000000&@44
+| +0#e000e06&@4|*| |/@1| |@+0#0000000&|h|i|g|h|l|i|g|h|t| +0#e000e06&|s+0#00e0003&|u|b|s|t|r|i|n|g|=+0#e000e06&|"+0#e000002&|m|a|i|n|"| +0#e000e06&|t+0#00e0003&|y|p|e|=+0#e000e06&|"+0#e000002&|i|t|a|l|i|c|"|:+0#e000e06&| +0#0000000&@22
+| +0#e000e06&@4|*| |p|u|b|l|i|c| |s|t|a|t|i|c| |v|o|i|d| |m|a|i|n|(|S|t|r|i|n|g|[|]| |a|r|g|s|)| |{| |}| +0#0000000&@25
+| +0#e000e06&@4|*| |}|<+0#00e0e07&|b+0#af5f00255&|r| +0#00e0e07&|/|>|<|p+0#af5f00255&|r|e| +0#00e0e07&|c+0#00e0003&|l|a|s@1|=+0#00e0e07&|"+0#e000002&|s|n|i|p@1|e|t|"|>+0#00e0e07&| +0#0000000&@39
+| +0#0000e05&@4|*|{+0#e000e06&|@|c|o|d|e| |p|u|b|l|i|c| |s|t|a|t|i|c| |v|o|i|d| |m|a|i|n|(|S|t|r|i|n|g|.@2| |a|r|g|s|)| |{| |}@1|<+0#00e0e07&|/|p+0#af5f00255&|r|e|>+0#00e0e07&| +0#0000000&@11
+| +0#0000e05&@4|*| +0#0000000&@68
+| +0#0000e05&@4|*| |@+0#e000e06&|p|a|r|a|m| +0#00e0e07&|a|r|g|s| +0#0000e05&|o|p|t|i|o|n|a|l| |c+0&#ffd7d7255|o|m@1|a|n|d|e|-+0&#ffffff0|l|i|n|e| |a|r|g|u|m|e|n|t|s| +0#ffffff16#ff404010| +0#0000000#ffffff0@22
+| +0#0000e05&@4|*| |@|j+0&#ffd7d7255|l|s| +0&#ffffff0|1|2|.|1|.|4| |I|n|v|o|k|e| |{+0#e000e06&|@|c|o|d|e| |T|e|s|t|.|m|a|i|n|}| +0#0000000&@31
+| +0#0000e05&@4|*|/| +0#0000000&@67
+@4|/+0#0000e05&@1| |@+0#0000000&|s|t|a|r|t| +0#0000e05&|r+0#00e0003&|e|g|i|o|n| +0#0000e05&|=| |m+0#e000002&|a|i|n| +0#0000000&@47
+@4|/+0#0000e05&@1| |@+0#0000000&|l|i|n|k| +0#0000e05&|s+0#00e0003&|u|b|s|t|r|i|n|g| +0#0000e05&|=| |'+0#e000002&|S|t|r|i|n|g|'| +0#0000e05&|t+0#00e0003&|a|r|g|e|t| +0#0000e05&|=| |'+0#e000002&|j|a|v|a|.|l|a|n|g|.|S|t|r|i|n|g|'| +0#0000e05&|:| +0#0000000&@11
+@4|p+0#00e0003&|u|b|l|i|c| +0#0000000&|s+0#00e0003&|t|a|t|i|c| +0#0000000&|v+0#00e0003&|o|i|d| +0#0000000&|m|a|i|n|(|S|t|r|i|n|g|[|]| |a|r|g|s|)| |{| |}| @28
+@4|/+0#0000e05&@1| |@+0#0000000&|e|n|d| @63
+>}| @73
+@57|2|5|,|1| @9|B|o|t| 
diff --git a/runtime/syntax/testdir/input/java_comments.java b/runtime/syntax/testdir/input/java_comments.java
new file mode 100644
index 0000000000..be347d7eb5
--- /dev/null
+++ b/runtime/syntax/testdir/input/java_comments.java
@@ -0,0 +1,25 @@
+// VIM_TEST_SETUP unlet! g:java_ignore_javadoc g:java_no_trail_space_error 
+// VIM_TEST_SETUP unlet! g:java_no_tab_space_error	
+// VIM_TEST_SETUP let [g:java_space_errors,g:java_comment_strings] = [1,1]
+// 	VIM_TEST_SETUP setlocal spell
+class CommentsTests
+{	/* 	TRAILING BLANKS AND MESSPILLINGS ARE SIGNIFICANT! */ 	
+	/**	
+	 * The method {@code main} must be declared {@code public}, {@code
+	 * static}, and {@code void}.  It must specify a formal parameter
+	 * whose declared type is array of {@link String}.  Therefore,
+	 * either of the following declarations is acceptable:
+	 * 	{@snippet lang="java":
+	 * // @highlight substring="main" type="italic":
+	 * public static void main(String[] args) { }
+	 * }<br /><pre class="snippet">
+	 *{@code public static void main(String... args) { }}</pre>
+	 *
+	 * @param args optional commande-line arguments 
+	 * @jls 12.1.4 Invoke {@code Test.main}
+	 */
+	// @start region = main
+	// @link substring = 'String' target = 'java.lang.String' :
+	public static void main(String[] args) { }
+	// @end
+}