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>

5 files changed, 104 insertions, 7 deletions

diff --git a/runtime/syntax/java.vim b/runtime/syntax/java.vim
index c059de603c..fe0cabf58e 100644
--- a/runtime/syntax/java.vim
+++ b/runtime/syntax/java.vim
@@ -2,7 +2,7 @@
 " Language:	Java
 " Maintainer:	Claudio Fleiner <claudio@fleiner.com>
 " URL:          https://github.com/fleiner/vim/blob/master/runtime/syntax/java.vim
-" Last Change:	2024 Mar 06
+" Last Change:	2024 Mar 22
 
 " Please check :help java.vim for comments on some of the options available.
 
@@ -191,10 +191,14 @@ if exists("java_comment_strings")
   syn cluster javaCommentSpecial2 add=javaComment2String,javaCommentCharacter,javaNumber,javaStrTempl
 endif
 
-syn region  javaComment		 start="/\*"  end="\*/" contains=@javaCommentSpecial,javaTodo,@Spell
+syn region  javaComment		start="/\*" end="\*/" contains=@javaCommentSpecial,javaTodo,javaSpaceError,@Spell
 syn match   javaCommentStar	 contained "^\s*\*[^/]"me=e-1
 syn match   javaCommentStar	 contained "^\s*\*$"
-syn match   javaLineComment	 "//.*" contains=@javaCommentSpecial2,javaTodo,@Spell
+syn match   javaLineComment	"//.*" contains=@javaCommentSpecial2,javaTodo,javaCommentMarkupTag,javaSpaceError,@Spell
+syn match   javaCommentMarkupTag contained "@\%(end\|highlight\|link\|replace\|start\)\>" nextgroup=javaCommentMarkupTagAttr skipwhite
+syn match   javaCommentMarkupTagAttr contained "\<region\>" nextgroup=javaCommentMarkupTagAttr skipwhite
+syn region  javaCommentMarkupTagAttr contained transparent matchgroup=htmlArg start=/\<\%(re\%(gex\|gion\|placement\)\|substring\|t\%(arget\|ype\)\)\%(\s*=\)\@=/ matchgroup=htmlString end=/\%(=\s*\)\@<=\%("[^"]\+"\|'[^']\+'\|\%([.-]\|\k\)\+\)/ nextgroup=javaCommentMarkupTagAttr skipwhite oneline
+hi def link javaCommentMarkupTagAttr htmlArg
 hi def link javaCommentString javaString
 hi def link javaComment2String javaString
 hi def link javaCommentCharacter javaCharacter
@@ -211,15 +215,19 @@ if !exists("java_ignore_javadoc") && main_syntax != 'jsp'
   " here.
   syntax spell default
 
-  syn region  javaDocComment	start="/\*\*"  end="\*/" keepend contains=javaCommentTitle,@javaHtml,javaDocTags,javaDocSeeTag,javaTodo,@Spell
-  syn region  javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*"   matchgroup=javaCommentTitle keepend end="\.$" end="\.[ \t\r<&]"me=e-1 end="[^{]@"me=s-2,he=s-1 end="\*/"me=s-1,he=s-1 contains=@javaHtml,javaCommentStar,javaTodo,@Spell,javaDocTags,javaDocSeeTag
-
-  syn region javaDocTags	 contained start="{@\(code\|link\|linkplain\|inherit[Dd]oc\|doc[rR]oot\|value\)" end="}"
+  syn region javaDocComment	start="/\*\*" end="\*/" keepend contains=javaCommentTitle,@javaHtml,javaDocTags,javaDocSeeTag,javaDocCodeTag,javaDocSnippetTag,javaTodo,javaSpaceError,@Spell
+  syn region javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*" matchgroup=javaCommentTitle keepend end="\.$" end="\.[ \t\r<&]"me=e-1 end="[^{]@"me=s-2,he=s-1 end="\*/"me=s-1,he=s-1 contains=@javaHtml,javaCommentStar,javaTodo,javaSpaceError,@Spell,javaDocTags,javaDocSeeTag,javaDocCodeTag,javaDocSnippetTag
+  syn region javaDocTags	contained start="{@\%(li\%(teral\|nk\%(plain\)\=\)\|inherit[Dd]oc\|doc[rR]oot\|value\)\>" end="}"
   syn match  javaDocTags	 contained "@\(param\|exception\|throws\|since\)\s\+\S\+" contains=javaDocParam
   syn match  javaDocParam	 contained "\s\S\+"
   syn match  javaDocTags	 contained "@\(version\|author\|return\|deprecated\|serial\|serialField\|serialData\)\>"
   syn region javaDocSeeTag	 contained matchgroup=javaDocTags start="@see\s\+" matchgroup=NONE end="\_."re=e-1 contains=javaDocSeeTagParam
   syn match  javaDocSeeTagParam  contained @"\_[^"]\+"\|<a\s\+\_.\{-}</a>\|\(\k\|\.\)*\(#\k\+\((\_[^)]\+)\)\=\)\=@ extend
+  syn region javaCodeSkipBlock	contained transparent start="{\%(@code\>\)\@!" end="}" contains=javaCodeSkipBlock,javaDocCodeTag
+  syn region javaDocCodeTag	contained start="{@code\>" end="}" contains=javaDocCodeTag,javaCodeSkipBlock
+  syn region javaDocSnippetTagAttr contained transparent matchgroup=htmlArg start=/\<\%(class\|file\|id\|lang\|region\)\%(\s*=\)\@=/ matchgroup=htmlString end=/:$/ end=/\%(=\s*\)\@<=\%("[^"]\+"\|'[^']\+'\|\%([.-]\|\k\)\+\)/ nextgroup=javaDocSnippetTagAttr skipwhite skipnl
+  syn region javaSnippetSkipBlock contained transparent start="{\%(@snippet\>\)\@!" end="}" contains=javaSnippetSkipBlock,javaDocSnippetTag,javaCommentMarkupTag
+  syn region javaDocSnippetTag	contained start="{@snippet\>" end="}" contains=javaDocSnippetTag,javaSnippetSkipBlock,javaDocSnippetTagAttr,javaCommentMarkupTag
   syntax case match
 endif
 
@@ -404,6 +412,8 @@ hi def link javaAnnotation		PreProc
 
 hi def link javaCommentTitle		SpecialComment
 hi def link javaDocTags		Special
+hi def link javaDocCodeTag		Special
+hi def link javaDocSnippetTag		Special
 hi def link javaDocParam		Function
 hi def link javaDocSeeTagParam		Function
 hi def link javaCommentStar		javaComment
@@ -413,6 +423,8 @@ hi def link javaExternal		Include
 
 hi def link htmlComment		Special
 hi def link htmlCommentPart		Special
+hi def link htmlArg			Type
+hi def link htmlString			String
 hi def link javaSpaceError		Error
 
 if s:isModuleInfoDeclarationCurrentBuffer()
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
+}