runtime(java): Make the bundled &foldtext function optional

- Obtain and pass through translated messages with this
  function.
- If "g:java_foldtext_show_first_or_second_line" is defined,
  assign this function to &foldtext.

closes: #15549

Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

Author: zzzyxwvut

runtime/doc/syntax.txt

@@ -1,4 +1,4 @@
-*syntax.txt*	For Vim version 9.1.  Last change: 2024 Aug 13
+*syntax.txt*	For Vim version 9.1.  Last change: 2024 Aug 22
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -2135,6 +2135,14 @@ Note that these three variables are maintained in the HTML syntax file.
 Numbers and strings can be recognized in non-Javadoc comments with >
 	:let g:java_comment_strings = 1
 
+When 'foldmethod' is set to "syntax", blocks of code and multi-line comments
+will be folded.  No text is usually written in the first line of a multi-line
+comment, making folded contents of Javadoc comments less informative with the
+default 'foldtext' value; you may opt for showing the contents of a second
+line for any comments written in this way, and showing the contents of a first
+line otherwise, with >
+	:let g:java_foldtext_show_first_or_second_line = 1
+
 Trailing whitespace characters or a run of space characters before a tab
 character can be marked as an error with >
 	:let g:java_space_errors = 1

runtime/syntax/java.vim

@@ -3,7 +3,7 @@
 " Maintainer:		Aliaksei Budavei <0x000c70 AT gmail DOT com>
 " Former Maintainer:	Claudio Fleiner <claudio@fleiner.com>
 " Repository:		https://github.com/zzzyxwvut/java-vim.git
-" Last Change:		2024 Jul 30
+" Last Change:		2024 Aug 22
 
 " Please check :help java.vim for comments on some of the options available.
 
@@ -39,17 +39,27 @@ else
   endfunction
 endif
 
-function! JavaSyntaxFoldTextExpr() abort
-  return getline(v:foldstart) !~ '/\*\+\s*$'
-    \ ? foldtext()
-    \ : printf('+-%s%3d lines: ',
-	  \ v:folddashes,
-	  \ (v:foldend - v:foldstart + 1)) .
-	\ getline(v:foldstart + 1)
-endfunction
+if exists("g:java_foldtext_show_first_or_second_line")
+  function! s:LazyPrefix(prefix, dashes, count) abort
+    return empty(a:prefix)
+      \ ? printf('+-%s%3d lines: ', a:dashes, a:count)
+      \ : a:prefix
+  endfunction
+
+  function! JavaSyntaxFoldTextExpr() abort
+    " Piggyback on NGETTEXT.
+    let summary = foldtext()
+    return getline(v:foldstart) !~ '/\*\+\s*$'
+      \ ? summary
+      \ : s:LazyPrefix(matchstr(summary, '^+-\+\s*\d\+\s.\{-1,}:\s'),
+			\ v:folddashes,
+			\ (v:foldend - v:foldstart + 1)) .
+	  \ getline(v:foldstart + 1)
+  endfunction
 
-" E120 for "fdt=s:JavaSyntaxFoldTextExpr()" before v8.2.3900.
-setlocal foldtext=JavaSyntaxFoldTextExpr()
+  " E120 for "fdt=s:JavaSyntaxFoldTextExpr()" before v8.2.3900.
+  setlocal foldtext=JavaSyntaxFoldTextExpr()
+endif
 
 " Admit the ASCII dollar sign to keyword characters (JLS-17, §3.8):
 try
@@ -624,15 +634,25 @@ if !has("vim9script")
   finish
 endif
 
-def! s:JavaSyntaxFoldTextExpr(): string
-  return getline(v:foldstart) !~ '/\*\+\s*$'
-    ? foldtext()
-    : printf('+-%s%3d lines: ',
-	  v:folddashes,
-	  (v:foldend - v:foldstart + 1)) ..
-	getline(v:foldstart + 1)
-enddef
-
-setlocal foldtext=s:JavaSyntaxFoldTextExpr()
-delfunction! g:JavaSyntaxFoldTextExpr
+if exists("g:java_foldtext_show_first_or_second_line")
+  def! s:LazyPrefix(prefix: string, dashes: string, count: number): string
+    return empty(prefix)
+      ? printf('+-%s%3d lines: ', dashes, count)
+      : prefix
+  enddef
+
+  def! s:JavaSyntaxFoldTextExpr(): string
+    # Piggyback on NGETTEXT.
+    const summary: string = foldtext()
+    return getline(v:foldstart) !~ '/\*\+\s*$'
+      ? summary
+      : LazyPrefix(matchstr(summary, '^+-\+\s*\d\+\s.\{-1,}:\s'),
+			v:folddashes,
+			(v:foldend - v:foldstart + 1)) ..
+	  getline(v:foldstart + 1)
+  enddef
+
+  setlocal foldtext=s:JavaSyntaxFoldTextExpr()
+  delfunction! g:JavaSyntaxFoldTextExpr
+endif
 " vim: sw=2 ts=8 noet sta

runtime/syntax/testdir/dumps/java_enfoldment_00.dump

@@ -1,5 +1,5 @@
 | +0#0000e05#a8a8a8255@1>/+0&#ffffff0@1| |V|I|M|_|T|E|S|T|_|S|E|T|U|P| |s|e|t|l|o|c|a|l| |f|o|l|d|e|n|a|b|l|e| |f|o|l|d|c|o|l|u|m|n|=|2| |f|o|l|d|m|e|t|h|o|d|=|s|y|n|t|a|x| +0#0000000&@4
-| +0#0000e05#a8a8a8255@1| +0#0000000#ffffff0@72
+| +0#0000e05#a8a8a8255@1|/+0&#ffffff0@1| |V|I|M|_|T|E|S|T|_|S|E|T|U|P| |l|e|t| |g|:|j|a|v|a|_|f|o|l|d|t|e|x|t|_|s|h|o|w|_|f|i|r|s|t|_|o|r|_|s|e|c|o|n|d|_|l|i|n|e| |=| |1| +0#0000000&@5
 | +0#0000e05#a8a8a8255@1| +0#0000000#ffffff0@72
 |++0#0000e05#a8a8a8255| |+|-@1| |1|6| |l|i|n|e|s|:| |@|S|u|p@1|r|e|s@1|W|a|r|n|i|n|g|s|(|{|-@39
 | @1|c+0#00e0003#ffffff0|l|a|s@1| +0#0000000&|F|o|l|d|i|n|g|T|e|s|t|s| |{| @52

runtime/syntax/testdir/input/java_enfoldment.java

@@ -1,5 +1,5 @@
 // VIM_TEST_SETUP setlocal foldenable foldcolumn=2 foldmethod=syntax
-
+// VIM_TEST_SETUP let g:java_foldtext_show_first_or_second_line = 1
 
 	@SuppressWarnings({
 	"""