adam/vim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

runtime(java): Recognise the CommonMark form (///) of Javadoc comments

Browse Source 
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>
This commit is contained in:
Aliaksei Budavei
2024-09-30 19:40:04 +02:00
committed by Christian Brabandt
parent de6c1d1182
commit 85f054aa3f
28 changed files with 706 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
runtime/doc/syntax.txt
View File

@ -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 @@ 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
@ -2119,8 +2120,14 @@ 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