vim-patch:a9ae38d: runtime(java): Recognise all available standard doclet tags

* Complement the tag set with @spec, {@systemProperty},
  {@summary}, @provides, @uses, @hidden, and {@index}.
* Do not hoard all tags under a single highlighting group.
* Skip over nested balanced braces in inline tags.
* Observe that tag names are case sensitive: both {@docRoot}
  and {@inheritDoc} are valid, whereas {@inheritdoc} and
  {@docroot} are not.
* In the @see tag arguments, allow for:
  - module name prefixes (e.g. java.base/java.lang.String);
  - references to arbitrary URI fragments (e.g. ##foo);
  - matching any tag variation arguments on the next line.
* Test directives and tags for Java module declarations.
* Enforce the word end for "module-info" candidates.

References:
https://bugs.openjdk.org/browse/JDK-8226279 (@spec)
https://bugs.openjdk.org/browse/JDK-8214559 ({@systemProperty})
https://bugs.openjdk.org/browse/JDK-8173425 ({@summary})
https://bugs.openjdk.org/browse/JDK-8160196 (@provides & @uses)
https://bugs.openjdk.org/browse/JDK-8073100 (@hidden)
https://bugs.openjdk.org/browse/JDK-8044243 ({@index})
https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html
https://github.com/openjdk/jdk/blob/jdk-21-ga/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java

closes: vim/vim#15652

a9ae38dc3f

Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>

runtime/syntax/java.vim

@@ -3,7 +3,7 @@
 " Maintainer:		Aliaksei Budavei <0x000c70 AT gmail DOT com>
 " Former Maintainer:	Claudio Fleiner <claudio@fleiner.com>
 " Repository:		https://github.com/zzzyxwvut/java-vim.git
-" Last Change:		2024 Aug 26
+" Last Change:		2024 Sep 10
 
 " Please check :help java.vim for comments on some of the options available.
 
@@ -157,13 +157,20 @@ endif
 " testing in a project without attendant confusion for IDEs, with the
 " ".java\=" extension used for a production version and an arbitrary
 " extension used for a testing version.
-if fnamemodify(bufname("%"), ":t") =~ '^module-info\%(\.class\>\)\@!'
+if fnamemodify(bufname("%"), ":t") =~ '^module-info\>\%(\.class\>\)\@!'
   syn keyword javaModuleStorageClass	module transitive
   syn keyword javaModuleStmt		open requires exports opens uses provides
   syn keyword javaModuleExternal	to with
   hi def link javaModuleStorageClass	StorageClass
   hi def link javaModuleStmt		Statement
   hi def link javaModuleExternal	Include
+
+  if !exists("g:java_ignore_javadoc") && g:main_syntax != 'jsp'
+    syn match javaDocProvidesTag	contained "@provides\_s\+\S\+" contains=javaDocParam
+    syn match javaDocUsesTag		contained "@uses\_s\+\S\+" contains=javaDocParam
+    hi def link javaDocProvidesTag	Special
+    hi def link javaDocUsesTag		Special
+  endif
 endif
 
 " Fancy parameterised types (JLS-17, §4.5).
@@ -335,29 +342,99 @@ if !exists("g:java_ignore_javadoc") && g:main_syntax != 'jsp'
     call s:ReportOnce(v:exception)
   endtry
 
-  syn region javaDocComment	start="/\*\*" end="\*/" keepend contains=javaCommentTitle,@javaHtml,javaDocTags,javaDocSeeTag,javaDocCodeTag,javaDocSnippetTag,javaTodo,javaCommentError,javaSpaceError,@Spell fold
+  syn region javaDocComment	start="/\*\*" end="\*/" keepend contains=javaCommentTitle,@javaHtml,@javaDocTags,javaTodo,javaCommentError,javaSpaceError,@Spell fold
-  exec 'syn region javaCommentTitle contained matchgroup=javaDocComment start="/\*\*" matchgroup=javaCommentTitle end="\.$" end="\.[ \t\r]\@=" end="\%(^\s*\**\s*\)\@' . s:ff.Peek('80', '') . '<=@"me=s-2,he=s-1 end="\*/"me=s-1,he=s-1 contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,javaDocTags,javaDocSeeTag,javaDocCodeTag,javaDocSnippetTag'
+  exec 'syn region javaCommentTitle contained matchgroup=javaDocComment start="/\*\*" matchgroup=javaCommentTitle end="\.$" end="\.[ \t\r]\@=" end="\%(^\s*\**\s*\)\@' . s:ff.Peek('80', '') . '<=@"me=s-2,he=s-1 end="\*/"me=s-1,he=s-1 contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,@javaDocTags'
-  syn region javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*\s*\r\=\n\=\s*\**\s*\%({@return\>\)\@=" matchgroup=javaCommentTitle end="}\%(\s*\.*\)*" contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,javaDocTags,javaDocSeeTag,javaDocCodeTag,javaDocSnippetTag
+  syn region javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*\s*\r\=\n\=\s*\**\s*\%({@return\>\)\@=" matchgroup=javaCommentTitle end="}\%(\s*\.*\)*" contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,@javaDocTags,javaTitleSkipBlock
-  syn region javaDocTags	contained start="{@\%(li\%(teral\|nk\%(plain\)\=\)\|inherit[Dd]oc\|doc[rR]oot\|value\)\>" end="}"
+  syn region javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*\s*\r\=\n\=\s*\**\s*\%({@summary\>\)\@=" matchgroup=javaCommentTitle end="}" contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,@javaDocTags,javaTitleSkipBlock
-  syn match  javaDocTags	contained "@\%(param\|exception\|throws\|since\)\s\+\S\+" contains=javaDocParam
+  " The members of javaDocTags are sub-grouped according to the Java
-  syn match  javaDocParam	contained "\s\S\+"
+  " version of their introduction, and sub-group members in turn are
-  syn match  javaDocTags	contained "@\%(version\|author\|return\|deprecated\|serial\%(Field\|Data\)\=\)\>"
+  " arranged in alphabetical order, so that future newer members can
-  syn region javaDocSeeTag	contained matchgroup=javaDocTags start="@see\s\+" matchgroup=NONE end="\_."re=e-1 contains=javaDocSeeTagParam
+  " be pre-sorted and appended without disturbing the current member
-  syn match  javaDocSeeTagParam	contained @"\_[^"]\+"\|<a\s\+\_.\{-}</a>\|\%(\k\|\.\)*\%(#\k\+\%((\_[^)]*)\)\=\)\=@ contains=@javaHtml extend
+  " placement.
+  " Since they only have significance in javaCommentTitle, neither
+  " javaDocSummaryTag nor javaDocReturnTitleTag are defined.
+  syn cluster javaDocTags	contains=javaDocAuthorTag,javaDocDeprecatedTag,javaDocExceptionTag,javaDocParamTag,javaDocReturnTag,javaDocSeeTag,javaDocVersionTag,javaDocSinceTag,javaDocLinkTag,javaDocSerialTag,javaDocSerialDataTag,javaDocSerialFieldTag,javaDocThrowsTag,javaDocDocRootTag,javaDocInheritDocTag,javaDocLinkplainTag,javaDocValueTag,javaDocCodeTag,javaDocLiteralTag,javaDocHiddenTag,javaDocIndexTag,javaDocProvidesTag,javaDocUsesTag,javaDocSystemPropertyTag,javaDocSnippetTag,javaDocSpecTag
+
+  " Anticipate non-standard inline tags in {@return} and {@summary}.
+  syn region javaTitleSkipBlock	contained transparent start="{\%(@\%(return\|summary\)\>\)\@!" end="}"
+  syn match  javaDocDocRootTag	contained "{@docRoot}"
+  syn match  javaDocInheritDocTag contained "{@inheritDoc}"
+  syn region javaIndexSkipBlock	contained transparent start="{\%(@index\>\)\@!" end="}" contains=javaIndexSkipBlock,javaDocIndexTag
+  syn region javaDocIndexTag	contained start="{@index\>" end="}" contains=javaDocIndexTag,javaIndexSkipBlock
+  syn region javaLinkSkipBlock	contained transparent start="{\%(@link\>\)\@!" end="}" contains=javaLinkSkipBlock,javaDocLinkTag
+  syn region javaDocLinkTag	contained start="{@link\>" end="}" contains=javaDocLinkTag,javaLinkSkipBlock
+  syn region javaLinkplainSkipBlock contained transparent start="{\%(@linkplain\>\)\@!" end="}" contains=javaLinkplainSkipBlock,javaDocLinkplainTag
+  syn region javaDocLinkplainTag contained start="{@linkplain\>" end="}" contains=javaDocLinkplainTag,javaLinkplainSkipBlock
+  syn region javaLiteralSkipBlock contained transparent start="{\%(@literal\>\)\@!" end="}" contains=javaLiteralSkipBlock,javaDocLiteralTag
+  syn region javaDocLiteralTag	contained start="{@literal\>" end="}" contains=javaDocLiteralTag,javaLiteralSkipBlock
+  syn region javaSystemPropertySkipBlock contained transparent start="{\%(@systemProperty\>\)\@!" end="}" contains=javaSystemPropertySkipBlock,javaDocSystemPropertyTag
+  syn region javaDocSystemPropertyTag contained start="{@systemProperty\>" end="}" contains=javaDocSystemPropertyTag,javaSystemPropertySkipBlock
+  syn region javaValueSkipBlock	contained transparent start="{\%(@value\>\)\@!" end="}" contains=javaValueSkipBlock,javaDocValueTag
+  syn region javaDocValueTag	contained start="{@value\>" end="}" contains=javaDocValueTag,javaValueSkipBlock
+
+  syn match  javaDocParam	contained "\s\zs\S\+"
+  syn match  javaDocExceptionTag contained "@exception\s\+\S\+" contains=javaDocParam
+  syn match  javaDocParamTag	contained "@param\s\+\S\+" contains=javaDocParam
+  syn match  javaDocSinceTag	contained "@since\s\+\S\+" contains=javaDocParam
+  syn match  javaDocThrowsTag	contained "@throws\s\+\S\+" contains=javaDocParam
+  syn match  javaDocSpecTag	contained "@spec\_s\+\S\+\ze\_s\+\S\+" contains=javaDocParam
+
+  syn match  javaDocAuthorTag	contained "@author\>"
+  syn match  javaDocDeprecatedTag contained "@deprecated\>"
+  syn match  javaDocHiddenTag	contained "@hidden\>"
+  syn match  javaDocReturnTag	contained "@return\>"
+  syn match  javaDocSerialTag	contained "@serial\>"
+  syn match  javaDocSerialDataTag contained "@serialData\>"
+  syn match  javaDocSerialFieldTag contained "@serialField\>"
+  syn match  javaDocVersionTag	contained "@version\>"
+
+  syn match  javaDocSeeTag	contained "@see\>" nextgroup=javaDocSeeTag1,javaDocSeeTag2,javaDocSeeTag3,javaDocSeeTagStar skipwhite skipempty
+  syn match  javaDocSeeTagStar	contained "^\s*\*\+\%(\s*{\=@\|/\|$\)\@!" nextgroup=javaDocSeeTag1,javaDocSeeTag2,javaDocSeeTag3 skipwhite skipempty
+  syn match  javaDocSeeTag1	contained @"\_[^"]\+"@
+  syn match  javaDocSeeTag2	contained @<a\s\+\_.\{-}</a>@ contains=@javaHtml extend
+  syn match  javaDocSeeTag3	contained @["< \t]\@!\%(\k\|[/.]\)*\%(##\=\k\+\%((\_[^)]*)\)\=\)\=@ nextgroup=javaDocSeeTag3Label skipwhite skipempty
+  syn match  javaDocSeeTag3Label contained @\k\%(\k\+\s*\)*$@
+
   syn region javaCodeSkipBlock	contained transparent start="{\%(@code\>\)\@!" end="}" contains=javaCodeSkipBlock,javaDocCodeTag
   syn region javaDocCodeTag	contained start="{@code\>" end="}" contains=javaDocCodeTag,javaCodeSkipBlock
+
   exec 'syn region javaDocSnippetTagAttr contained transparent matchgroup=javaHtmlArg start=/\<\%(class\|file\|id\|lang\|region\)\%(\s*=\)\@=/ matchgroup=javaHtmlString end=/:$/ end=/\%(=\s*\)\@' . s:ff.Peek('80', '') . '<=\%("[^"]\+"\|' . "\x27[^\x27]\\+\x27" . '\|\%([.\\/-]\|\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
   hi def link javaDocComment		Comment
+  hi def link javaDocSeeTagStar		javaDocComment
   hi def link javaCommentTitle		SpecialComment
-  hi def link javaDocTags		Special
-  hi def link javaDocCodeTag		Special
-  hi def link javaDocSnippetTag		Special
-  hi def link javaDocSeeTagParam	Function
   hi def link javaDocParam		Function
+
+  hi def link javaDocAuthorTag		Special
+  hi def link javaDocCodeTag		Special
+  hi def link javaDocDeprecatedTag	Special
+  hi def link javaDocDocRootTag		Special
+  hi def link javaDocExceptionTag	Special
+  hi def link javaDocHiddenTag		Special
+  hi def link javaDocIndexTag		Special
+  hi def link javaDocInheritDocTag	Special
+  hi def link javaDocLinkTag		Special
+  hi def link javaDocLinkplainTag	Special
+  hi def link javaDocLiteralTag		Special
+  hi def link javaDocParamTag		Special
+  hi def link javaDocReturnTag		Special
+  hi def link javaDocSeeTag		Special
+  hi def link javaDocSeeTag1		String
+  hi def link javaDocSeeTag2		Special
+  hi def link javaDocSeeTag3		Function
+  hi def link javaDocSerialTag		Special
+  hi def link javaDocSerialDataTag	Special
+  hi def link javaDocSerialFieldTag	Special
+  hi def link javaDocSinceTag		Special
+  hi def link javaDocSnippetTag		Special
+  hi def link javaDocSpecTag		Special
+  hi def link javaDocSystemPropertyTag	Special
+  hi def link javaDocThrowsTag		Special
+  hi def link javaDocValueTag		Special
+  hi def link javaDocVersionTag		Special
 endif
 
 " match the special comment /**/