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

24
runtime/doc/filetype.txt
View File

@ -1,4 +1,4 @@
*filetype.txt* For Vim version 9.1. Last change: 2024 Aug 21
*filetype.txt* For Vim version 9.1. Last change: 2024 Sep 29
VIM REFERENCE MANUAL by Bram Moolenaar
@ -698,6 +698,28 @@ 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
<
JSON-FORMAT *ft-json-plugin*