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>

2 files changed, 29 insertions, 2 deletions

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