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: #15740

Co-authored-by: Tim Pope <code@tpope.net>
Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

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