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>
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 4a5b07c..ff80936 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1,4 +1,4 @@
-*syntax.txt* For Vim version 9.1. Last change: 2024 Sep 19
+*syntax.txt* For Vim version 9.1. Last change: 2024 Sep 28
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -2106,7 +2106,8 @@
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
@@ -2119,8 +2120,14 @@
*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