vim-patch:85f054a: runtime(java): Recognise the CommonMark form (///) of Javadoc comments

Complement "g:java_ignore_javadoc" with "g:java_ignore_html"
and "g:java_ignore_markdown" to allow selectively disabling
the recognition of HTML and CommonMark respectively.

(Note that this is not a preview feature.)

======================== LIMITATION ========================

According to the syntactical details of JEP 467:

> Any leading whitespace and the three initial / characters
> are removed from each line.
>
> The lines are shifted left, by removing leading whitespace
> characters, until the non-blank line with the least
> leading whitespace has no remaining leading whitespace.
>
> Additional leading whitespace and any trailing whitespace
> in each line is preserved, because it may be significant.

the following example:
------------------------------------------------------------
///    A summary sentence.
///     A list:
///      - Item A.
///     - Item B.
///
///     Some code span, starting here `
///      1 + 2 ` and ending at the previous \`.
------------------------------------------------------------

should be interpreted as if it were written thus:
------------------------------------------------------------
///A summary sentence.
/// A list:
///  - Item A.
/// - Item B.
///
/// Some code span, starting here `
///  1 + 2 ` and ending at the previous \`.
------------------------------------------------------------

Since automatic line rewriting will not be pursued, parts of
such comments having significant whitespace may be ‘wrongly’
highlighted.  For convenience, a &fex function is defined to
‘correct’ it: g:javaformat#RemoveCommonMarkdownWhitespace()
(:help ft-java-plugin).

References:
https://openjdk.org/jeps/467
https://spec.commonmark.org/0.31.2

closes: vim/vim#15740

https://github.com/vim/vim/commit/85f054aa3f0fb9530712d0897e3c8ba29946fad4

Co-authored-by: Aliaksei Budavei <0x000c70@gmail.com>
Co-authored-by: Tim Pope <code@tpope.net>

5 files changed, 277 insertions, 31 deletions

diff --git a/runtime/autoload/javaformat.vim b/runtime/autoload/javaformat.vim
new file mode 100644
index 0000000000..4d7d32cf19
--- /dev/null
+++ b/runtime/autoload/javaformat.vim
@@ -0,0 +1,92 @@
+" Vim formatting plugin file
+" Language:		Java
+" Maintainer:		Aliaksei Budavei <0x000c70 AT gmail DOT com>
+" Repository:		https://github.com/zzzyxwvut/java-vim.git
+" Last Change:		2024 Sep 26
+
+" Documented in ":help ft-java-plugin".
+if &cp || exists("g:loaded_javaformat") || exists("g:java_ignore_javadoc") || exists("g:java_ignore_markdown")
+    finish
+endif
+
+let g:loaded_javaformat = 1
+
+"""" STRIVE TO REMAIN COMPATIBLE FOR AT LEAST VIM 7.0.
+
+function! javaformat#RemoveCommonMarkdownWhitespace() abort
+    if mode() != 'n'
+	return 0
+    endif
+
+    let pattern = '\(^\s*///\)\(\s*\)\(.*\)'
+
+    " E121 for v:numbermax before v8.2.2388.
+    " E15 for expr-<< before v8.2.5003.
+    let common = 0x7fffffff
+    let comments = []
+
+    for n in range(v:lnum, (v:lnum + v:count - 1))
+	let parts = matchlist(getline(n), pattern)
+	let whitespace = get(parts, 2, '')
+	let nonwhitespace = get(parts, 3, '')
+
+	if !empty(whitespace)
+	    let common = min([common, strlen(whitespace)])
+	elseif !empty(nonwhitespace) || empty(parts)
+	    " No whitespace prefix or not a Markdown comment.
+	    return 0
+	endif
+
+	call add(comments, [whitespace, parts[1], nonwhitespace])
+    endfor
+
+    let cursor = v:lnum
+
+    for line in comments
+	call setline(cursor, join(line[1 :], strpart(line[0], common)))
+	let cursor += 1
+    endfor
+
+    return 0
+endfunction
+
+" See ":help vim9-mix".
+if !has("vim9script")
+    finish
+endif
+
+def! g:javaformat#RemoveCommonMarkdownWhitespace(): number
+    if mode() != 'n'
+	return 0
+    endif
+
+    const pattern: string = '\(^\s*///\)\(\s*\)\(.*\)'
+    var common: number = v:numbermax
+    var comments: list<list<string>> = []
+
+    for n in range(v:lnum, (v:lnum + v:count - 1))
+	const parts: list<string> = matchlist(getline(n), pattern)
+	const whitespace: string = get(parts, 2, '')
+	const nonwhitespace: string = get(parts, 3, '')
+
+	if !empty(whitespace)
+	    common = min([common, strlen(whitespace)])
+	elseif !empty(nonwhitespace) || empty(parts)
+	    # No whitespace prefix or not a Markdown comment.
+	    return 0
+	endif
+
+	add(comments, [whitespace, parts[1], nonwhitespace])
+    endfor
+
+    var cursor: number = v:lnum
+
+    for line in comments
+	setline(cursor, join(line[1 :], strpart(line[0], common)))
+	cursor += 1
+    endfor
+
+    return 0
+enddef
+
+" vim: fdm=syntax sw=4 ts=8 noet sta
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index cdb6f1d7f0..a577b0c5fb 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -661,6 +661,27 @@ Remember to manually trigger the |FileType| event from a buffer with a Java
 file loaded in it each time after assigning a new value to the variable: >
 	doautocmd FileType
 <
+Markdown documentation comments may contain common runs of vertical leading
+whitespace following the comment marks (`///`) for aesthetic reasons; however,
+some horizontal runs of leading whitespace are significant in Markdown because
+they denote code blocks etc.  For convenience, a 'formatexpr' function is
+provided for the |gq| operator.  As long as neither "g:java_ignore_javadoc"
+nor "g:java_ignore_markdown" is defined, the reformatting of Markdown comments
+can be enabled on demand with: >
+	setlocal formatexpr=g:javaformat#RemoveCommonMarkdownWhitespace()
+<
+Or for Vim versions less than `7.4.265`, with: >
+	setlocal formatexpr=javaformat#RemoveCommonMarkdownWhitespace()
+<
+This function accepts a range of lines, removes a common run of vertical
+leading whitespace, and rewrites the lines of the range.  Depending on the
+author's layout style and the comment contents, which lines to select for
+reformatting can vary from the whole comment to only some portion of it.
+To enable the recognition of Markdown comments each time after removing
+"g:java_ignore_markdown" or "g:java_ignore_javadoc", remember to manually
+re-source "javaformat.vim" for Vim versions greater than `8.2.1397`: >
+	runtime autoload/javaformat.vim
+<
 
 MAIL							*ft-mail-plugin*
 
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index d8b41b6429..aae806f826 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1634,7 +1634,8 @@ respectively.
 Javadoc is a program that takes special comments out of Java program files and
 creates HTML pages.  The standard configuration will highlight this HTML code
 similarly to HTML files (see |html.vim|).  You can even add JavaScript and CSS
-inside this code (see below).  The HTML rendering diverges as follows:
+inside this code (see below).  The HTML rendering and the Markdown rendering
+diverge as follows:
   1. The first sentence (all characters up to the first period `.`, which is
      followed by a whitespace character or a line terminator, or up to the
      first block tag, e.g. `@param`, `@return`) is colored as
@@ -1647,8 +1648,13 @@ inside this code (see below).  The HTML rendering diverges as follows:
 	`*Special`	special symbols
      and some of their arguments are colored as
 	`*Function`	function names.
-To turn this feature off, add the following line to your startup file: >
+To turn this feature off for both HTML and Markdown, add the following line to
+your startup file: >
 	:let g:java_ignore_javadoc = 1
+Alternatively, only suppress HTML comments or Markdown comments: >
+	:let g:java_ignore_html = 1
+	:let g:java_ignore_markdown = 1
+See |ft-java-plugin| for additional support available for Markdown comments.
 
 If you use the special Javadoc comment highlighting described above, you can
 also turn on special highlighting for JavaScript, Visual Basic scripts, and
diff --git a/runtime/ftplugin/java.vim b/runtime/ftplugin/java.vim
index eee7ef0153..55b358374f 100644
--- a/runtime/ftplugin/java.vim
+++ b/runtime/ftplugin/java.vim
@@ -3,18 +3,29 @@
 " Maintainer:		Aliaksei Budavei <0x000c70 AT gmail DOT com>
 " Former Maintainer:	Dan Sharp
 " Repository:		https://github.com/zzzyxwvut/java-vim.git
-" Last Change:		2024 Apr 18
+" Last Change:		2024 Sep 26
 "			2024 Jan 14 by Vim Project (browsefilter)
 "			2024 May 23 by Riley Bruins <ribru17@gmail.com> ('commentstring')
 
-if exists("b:did_ftplugin") | finish | endif
-let b:did_ftplugin = 1
-
 " Make sure the continuation lines below do not cause problems in
 " compatibility mode.
 let s:save_cpo = &cpo
 set cpo-=C
 
+if (exists("g:java_ignore_javadoc") || exists("g:java_ignore_markdown")) &&
+	\ exists("*javaformat#RemoveCommonMarkdownWhitespace")
+    delfunction javaformat#RemoveCommonMarkdownWhitespace
+    unlet! g:loaded_javaformat
+endif
+
+if exists("b:did_ftplugin")
+    let &cpo = s:save_cpo
+    unlet s:save_cpo
+    finish
+endif
+
+let b:did_ftplugin = 1
+
 " For filename completion, prefer the .java extension over the .class
 " extension.
 set suffixes+=.class
@@ -27,6 +38,8 @@ setlocal suffixesadd=.java
 " Clean up in case this file is sourced again.
 unlet! s:zip_func_upgradable
 
+"""" STRIVE TO REMAIN COMPATIBLE FOR AT LEAST VIM 7.0.
+
 " Documented in ":help ft-java-plugin".
 if exists("g:ftplugin_java_source_path") &&
 		\ type(g:ftplugin_java_source_path) == type("")
@@ -59,8 +72,9 @@ endif
 " and insert the comment leader when hitting <CR> or using "o".
 setlocal formatoptions-=t formatoptions+=croql
 
-" Set 'comments' to format dashed lists in comments. Behaves just like C.
-setlocal comments& comments^=sO:*\ -,mO:*\ \ ,exO:*/
+" Set 'comments' to format Markdown Javadoc comments and dashed lists
+" in other multi-line comments (it behaves just like C).
+setlocal comments& comments^=:///,sO:*\ -,mO:*\ \ ,exO:*/
 
 setlocal commentstring=//\ %s
 
@@ -103,3 +117,4 @@ endif
 " Restore the saved compatibility options.
 let &cpo = s:save_cpo
 unlet s:save_cpo
+" vim: fdm=syntax sw=4 ts=8 noet sta
diff --git a/runtime/syntax/java.vim b/runtime/syntax/java.vim
index 800faa40a0..737219afce 100644
--- a/runtime/syntax/java.vim
+++ b/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 Sep 19
+" Last Change:		2024 Sep 28
 
 " Please check :help java.vim for comments on some of the options available.
 
@@ -156,6 +156,10 @@ else
   let [s:ff.PeekTo, s:ff.PeekFrom, s:ff.GroupArgs] = repeat([s:ff.RightConstant], 3)
 endif
 
+let s:with_html = !exists("g:java_ignore_html")
+let s:with_markdown = !exists("g:java_ignore_markdown")
+lockvar s:with_html s:with_markdown
+
 " Java module declarations (JLS-17, §7.7).
 "
 " Note that a "module-info" file will be recognised with an arbitrary
@@ -172,7 +176,7 @@ if fnamemodify(bufname("%"), ":t") =~ '^module-info\>\%(\.class\>\)\@!'
   hi def link javaModuleStmt		Statement
   hi def link javaModuleExternal	Include
 
-  if !exists("g:java_ignore_javadoc") && g:main_syntax != 'jsp'
+  if !exists("g:java_ignore_javadoc") && (s:with_html || s:with_markdown) && 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
@@ -335,18 +339,52 @@ syn match   javaCommentMarkupTagAttr contained "\<region\>" nextgroup=javaCommen
 exec 'syn region javaCommentMarkupTagAttr contained transparent matchgroup=javaHtmlArg start=/\<\%(re\%(gex\|gion\|placement\)\|substring\|t\%(arget\|ype\)\)\%(\s*=\)\@=/ matchgroup=javaHtmlString end=/\%(=\s*\)\@' . s:ff.Peek('80', '') . '<=\%("[^"]\+"\|' . "\x27[^\x27]\\+\x27" . '\|\%([.-]\|\k\)\+\)/ nextgroup=javaCommentMarkupTagAttr,javaSpaceError skipwhite oneline'
 syn match   javaCommentError contained "/\*"me=e-1 display
 
-if !exists("g:java_ignore_javadoc") && g:main_syntax != 'jsp'
-  " The overridable "html*" default links must be defined _before_ the
-  " inclusion of the same default links from "html.vim".
-  hi def link htmlComment	Special
-  hi def link htmlCommentPart	Special
-  hi def link htmlArg		Type
-  hi def link htmlString	String
+if !exists("g:java_ignore_javadoc") && (s:with_html || s:with_markdown) && g:main_syntax != 'jsp'
+  " The overridable "html*" and "markdown*" default links must be
+  " defined _before_ the inclusion of the same default links from
+  " "html.vim" and "markdown.vim".
+  if s:with_html || s:with_markdown
+    hi def link htmlComment		Special
+    hi def link htmlCommentPart		Special
+    hi def link htmlArg			Type
+    hi def link htmlString		String
+  endif
+
+  if s:with_markdown
+    hi def link markdownCode		Special
+    hi def link markdownCodeBlock	Special
+    hi def link markdownCodeDelimiter	Special
+    hi def link markdownLinkDelimiter	Comment
+  endif
+
   syntax case ignore
 
+  " Note that javaDocSeeTag is valid in HTML and Markdown.
+  let s:ff.WithMarkdown = s:ff.RightConstant
+
   " Include HTML syntax coloring for Javadoc comments.
-  syntax include @javaHtml syntax/html.vim
-  unlet b:current_syntax
+  if s:with_html
+    syntax include @javaHtml syntax/html.vim
+    unlet b:current_syntax
+  endif
+
+  " Include Markdown syntax coloring (v7.2.437) for Javadoc comments.
+  if s:with_markdown
+    try
+      syntax include @javaMarkdown syntax/markdown.vim
+      unlet b:current_syntax
+      let s:ff.WithMarkdown = s:ff.LeftConstant
+    catch /\<E48[45]:/
+      call s:ReportOnce(v:exception)
+      unlockvar s:with_markdown
+      let s:with_markdown = 0
+      lockvar s:with_markdown
+      hi clear markdownCode
+      hi clear markdownCodeBlock
+      hi clear markdownCodeDelimiter
+      hi clear markdownLinkDelimiter
+    endtry
+  endif
 
   " HTML enables spell checking for all text that is not in a syntax
   " item (:syntax spell toplevel); instead, limit spell checking to
@@ -357,10 +395,71 @@ 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,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'
-  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 javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*\s*\r\=\n\=\s*\**\s*\%({@summary\>\)\@=" matchgroup=javaCommentTitle end="}" contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,@javaDocTags,javaTitleSkipBlock
+  if s:with_markdown
+    syn region javaMarkdownComment	start="///" skip="^\s*///.*$" end="^" keepend contains=javaMarkdownCommentTitle,javaMarkdownShortcutLink,@javaMarkdown,@javaDocTags,javaTodo,@Spell nextgroup=javaMarkdownCommentTitle fold
+    syn match javaMarkdownCommentMask	contained "^\s*///"
+    exec 'syn region javaMarkdownCommentTitle contained matchgroup=javaMarkdownComment start="\%(///.*\r\=\n\s*\)\@' . s:ff.Peek('80', '') . '<!///" matchgroup=javaMarkdownCommentTitle end="\.$" end="\.[ \t\r]\@=" end="\n\%(\s*///\s*$\)\@=" end="\%(^\s*///\s*\)\@' . s:ff.Peek('80', '') . '<=@"me=s-2,he=s-1 contains=javaMarkdownShortcutLink,@javaMarkdown,javaMarkdownCommentMask,javaTodo,@Spell,@javaDocTags'
+    exec 'syn region javaMarkdownCommentTitle contained matchgroup=javaMarkdownComment start="\%(///.*\r\=\n\s*\)\@' . s:ff.Peek('80', '') . '<!///\s*\%({@return\>\)\@=" matchgroup=javaMarkdownCommentTitle end="}\%(\s*\.*\)*" contains=javaMarkdownShortcutLink,@javaMarkdown,javaMarkdownCommentMask,javaTodo,@Spell,@javaDocTags,javaTitleSkipBlock'
+    exec 'syn region javaMarkdownCommentTitle contained matchgroup=javaMarkdownComment start="\%(///.*\r\=\n\s*\)\@' . s:ff.Peek('80', '') . '<!///\s*\%({@summary\>\)\@=" matchgroup=javaMarkdownCommentTitle end="}" contains=javaMarkdownShortcutLink,@javaMarkdown,javaMarkdownCommentMask,javaTodo,@Spell,@javaDocTags,javaTitleSkipBlock'
+
+    syn clear markdownId markdownLineStart markdownH1 markdownH2 markdownHeadingRule markdownRule markdownCode markdownCodeBlock markdownIdDeclaration
+    " REDEFINE THE MARKDOWN ITEMS ANCHORED WITH "^", OBSERVING THE
+    " DEFINITION ORDER.
+    syn match markdownLineStart		contained "^\s*///\s*[<@]\@!" contains=@markdownBlock,javaMarkdownCommentTitle,javaMarkdownCommentMask nextgroup=@markdownBlock,htmlSpecialChar
+    " See https://spec.commonmark.org/0.31.2/#setext-headings.
+    syn match markdownH1		contained "^\s*/// \{,3}.\+\r\=\n\s*/// \{,3}=\+\s*$" contains=@markdownInline,markdownHeadingRule,markdownAutomaticLink,javaMarkdownCommentMask
+    syn match markdownH2		contained "^\s*/// \{,3}.\+\r\=\n\s*/// \{,3}-\+\s*$" contains=@markdownInline,markdownHeadingRule,markdownAutomaticLink,javaMarkdownCommentMask
+    " See https://spec.commonmark.org/0.31.2/#atx-headings.
+    syn region markdownH1		contained matchgroup=markdownH1Delimiter start=" \{,3}#\s" end="#*\s*$" keepend contains=@markdownInline,markdownAutomaticLink oneline
+    syn region markdownH2		contained matchgroup=markdownH2Delimiter start=" \{,3}##\s" end="#*\s*$" keepend contains=@markdownInline,markdownAutomaticLink oneline
+    syn match markdownHeadingRule	contained "^\s*/// \{,3}[=-]\+\s*$" contains=javaMarkdownCommentMask
+    " See https://spec.commonmark.org/0.31.2/#thematic-breaks.
+    syn match markdownRule		contained "^\s*/// \{,3}\*\s*\*\%(\s*\*\)\+\s*$" contains=javaMarkdownCommentMask
+    syn match markdownRule		contained "^\s*/// \{,3}_\s*_\%(\s*_\)\+\s*$" contains=javaMarkdownCommentMask
+    syn match markdownRule		contained "^\s*/// \{,3}-\s*-\%(\s*-\)\+\s*$" contains=javaMarkdownCommentMask
+    " See https://spec.commonmark.org/0.31.2/#indented-code-blocks.
+    syn region markdownCodeBlock	contained start="^\s*///\%( \{4,}\|\t\)" end="^\ze\s*///\%(\s*$\| \{,3}\S\)" keepend contains=javaMarkdownCommentMask
+    " See https://spec.commonmark.org/0.31.2/#code-spans.
+    syn region markdownCode		contained matchgroup=markdownCodeDelimiter start="\z(`\+\) \=" end=" \=\z1" keepend contains=markdownLineStart,javaMarkdownCommentMask
+    " See https://spec.commonmark.org/0.31.2/#fenced-code-blocks.
+    syn region markdownCodeBlock	contained start="^\s*/// \{,3}\z(```\+\)\%(.\{-}[^`]`\)\@!" end="^\s*/// \{,3}\z1`*" keepend contains=javaMarkdownCommentMask
+    syn region markdownCodeBlock	contained start="^\s*/// \{,3}\z(\~\~\~\+\)" end="^\s*/// \{,3}\z1\~*" keepend contains=javaMarkdownCommentMask
+    " See https://spec.commonmark.org/0.31.2/#link-reference-definitions.
+    syn region markdownIdDeclaration	contained matchgroup=markdownLinkDelimiter start="^\s*/// \{,3\}!\=\[" end="\]:" keepend contains=javaMarkdownCommentMask nextgroup=markdownUrl oneline skipwhite
+    " See https://spec.commonmark.org/0.31.2/#link-label.
+    syn region markdownId		contained matchgroup=markdownIdDelimiter start="\[\%([\t ]\]\)\@!" end="\]" contains=javaMarkdownSkipBrackets,javaMarkdownCommentMask
+    " Note that escaped brackets can be unbalanced.
+    syn match javaMarkdownSkipBrackets	contained transparent "\\\[\|\\\]"
+    " See https://spec.commonmark.org/0.31.2/#shortcut-reference-link.
+    syn region javaMarkdownShortcutLink	contained matchgroup=markdownLinkTextDelimiter start="!\=\[^\@!\%(\_[^][]*\%(\[\_[^][]*\]\_[^][]*\)*]\%([[(]\)\@!\)\@=" end="\]\%([[(]\)\@!" contains=@markdownInline,markdownLineStart,javaMarkdownSkipBrackets,javaMarkdownCommentMask nextgroup=markdownLink,markdownId skipwhite
+
+    for s:name in ['markdownFootnoteDefinition', 'markdownFootnote']
+      if hlexists(s:name)
+	exec 'syn clear ' . s:name
+      endif
+    endfor
+
+    unlet s:name
+
+    " COMBAK: Footnotes are recognised by "markdown.vim", but are not
+    " in CommonMark.  See https://pandoc.org/MANUAL.html#footnotes.
+""""syn match markdownFootnoteDefinition contained "^\s*///\s*\[^[^\]]\+\]:" contains=javaMarkdownCommentMask
+
+    hi def link javaMarkdownComment	Comment
+    hi def link javaMarkdownCommentMask	javaMarkdownComment
+    hi def link javaMarkdownCommentTitle SpecialComment
+    hi def link javaMarkdownShortcutLink htmlLink
+  endif
+
+  if s:with_html
+    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'
+    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 javaCommentTitle	contained matchgroup=javaDocComment start="/\*\*\s*\r\=\n\=\s*\**\s*\%({@summary\>\)\@=" matchgroup=javaCommentTitle end="}" contains=@javaHtml,javaCommentStar,javaTodo,javaCommentError,javaSpaceError,@Spell,@javaDocTags,javaTitleSkipBlock
+    hi def link javaDocComment		Comment
+    hi def link javaCommentTitle	SpecialComment
+  endif
+
   " The members of javaDocTags are sub-grouped according to the Java
   " version of their introduction, and sub-group members in turn are
   " arranged in alphabetical order, so that future newer members can
@@ -403,13 +502,29 @@ if !exists("g:java_ignore_javadoc") && g:main_syntax != 'jsp'
   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 javaDocSeeTag contained "@see\>\s*" nextgroup=javaDocSeeTag1,javaDocSeeTag2,javaDocSeeTag3,javaDocSeeTag4,javaDocSeeTagStar,javaDocSeeTagSlash skipwhite skipempty
+
+  if s:with_html
+    syn match  javaDocSeeTagStar contained "^\s*\*\+\%(\s*{\=@\|/\|$\)\@!" nextgroup=javaDocSeeTag1,javaDocSeeTag2,javaDocSeeTag3,javaDocSeeTag4 skipwhite skipempty
+    hi def link javaDocSeeTagStar javaDocComment
+  endif
+
+  if s:with_markdown
+    syn match  javaDocSeeTagSlash contained "^\s*///\%(\s*{\=@\|$\)\@!" nextgroup=javaDocSeeTag1,javaDocSeeTag2,javaDocSeeTag3,javaDocSeeTag4 skipwhite skipempty
+    hi def link javaDocSeeTagSlash javaMarkdownComment
+  endif
+
   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
+  exec 'syn match javaDocSeeTag3 contained @[' . s:ff.WithMarkdown('[', '') . '"< \t]\@!\%(\k\|[/.]\)*\%(##\=\k\+\%((\_[^)]*)\)\=\)\=@ nextgroup=javaDocSeeTag3Label skipwhite skipempty'
   syn match  javaDocSeeTag3Label contained @\k\%(\k\+\s*\)*$@
 
+  " COMBAK: No support for type javaDocSeeTag2 in Markdown.
+""if s:with_markdown
+""  syn match  javaDocSeeTag4	contained @\[.\+\]\s\=\%(\[.\+\]\|(.\+)\)@ contains=@javaMarkdown extend
+""  hi def link javaDocSeeTag4	Special
+""endif
+
   syn region javaCodeSkipBlock	contained transparent start="{\%(@code\>\)\@!" end="}" contains=javaCodeSkipBlock,javaDocCodeTag
   syn region javaDocCodeTag	contained start="{@code\>" end="}" contains=javaDocCodeTag,javaCodeSkipBlock
 
@@ -418,9 +533,6 @@ if !exists("g:java_ignore_javadoc") && g:main_syntax != 'jsp'
   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 javaDocParam		Function
 
   hi def link javaDocAuthorTag		Special
@@ -729,7 +841,7 @@ endif
 
 let b:spell_options = "contained"
 let &cpo = s:cpo_save
-unlet s:ff s:cpo_save
+unlet s:cpo_save s:ff s:with_html s:with_markdown
 
 " See ":help vim9-mix".
 if !has("vim9script")
@@ -757,4 +869,4 @@ if exists("g:java_foldtext_show_first_or_second_line")
   setlocal foldtext=s:JavaSyntaxFoldTextExpr()
   delfunction! g:JavaSyntaxFoldTextExpr
 endif
-" vim: sw=2 ts=8 noet sta
+" vim: fdm=syntax sw=2 ts=8 noet sta