Mercurial > vim

changeset 34613:b0d91b836400

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
runtime(java): Recognise the {@snippet} documentation tag (#14271) Commit: https://github.com/vim/vim/commit/3e72bf10a0a2fc34f01ff9663ed3324c2a140228 Author: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com> Date: Fri Mar 22 21:32:48 2024 +0300 runtime(java): Recognise the {@snippet} documentation tag (https://github.com/vim/vim/issues/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>
author Christian Brabandt <cb@256bit.org>
date Fri, 22 Mar 2024 19:45:04 +0100
parents f127e95333b3
children fafb4eb10619
files runtime/syntax/java.vim runtime/syntax/testdir/dumps/java_comments_00.dump runtime/syntax/testdir/dumps/java_comments_01.dump runtime/syntax/testdir/dumps/java_comments_99.dump runtime/syntax/testdir/input/java_comments.java
diffstat 5 files changed, 104 insertions(+), 7 deletions(-) [+]
line wrap: on
line diff
--- 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") && mai
   " 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()
new file mode 100644
--- /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| 
new file mode 100644
--- /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| 
new file mode 100644
--- /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| 
new file mode 100644
--- /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
+}