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>

1 files changed, 21 insertions, 6 deletions

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