runtime(java): Optionally highlight parameterised types

In the presence of parameterised types whose names begin
with a capital letter and end with a less-than sign "<" that
introduces a type argument or a list of comma-separated type
arguments, followed by a greater-than sign ">", a variable
"g:java_highlight_generics" can be defined to have some
components of such types uniformly coloured (by picking
highlight groups for javaGenericsC{1,2}, javaWildcardBound).

For example,
------------------------------------------------------------
java.io.InputStream stream = java.io.InputStream.nullInputStream();
java.util.function.Function<String,
    java.util.function.BiFunction<String, String, String>> updater =
	property -> (oldValue, newValue) -> oldValue;
java.util.logging.LogManager.getLogManager()
    .updateConfiguration(stream, updater);
------------------------------------------------------------

Note that the diamond form and explicit type arguments do
not qualify for this kind of recognition.

For example,
------------------------------------------------------------
new java.util.HashSet<>().<String>toArray(new String[0]);
------------------------------------------------------------

References:
https://docs.oracle.com/javase/specs/jls/se21/html/jls-4.html#jls-4.5
https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.9
https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.12.2.1

closes: #15050

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

1 files changed, 10 insertions, 6 deletions

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index c07c3a4ea6..1460edd449 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 Jun 17
+*syntax.txt*	For Vim version 9.1.  Last change: 2024 Jun 19
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -2014,7 +2014,7 @@ Check the javaid.vim file for a list of all the packages that are supported.
 
 Function names are not highlighted, as the way to find functions depends on
 how you write Java code.  The syntax file knows two possible ways to highlight
-functions:
+headers of function declarations:
 
 If you write function declarations that are consistently indented by either
 a tab, or a space . . . or eight space character(s), you may want to set >
@@ -2032,10 +2032,14 @@ However, if you follow the Java guidelines about how functions and classes are
 supposed to be named (with respect to upper- and lowercase) and there is any
 amount of indentation, you may want to set >
 	:let java_highlight_functions="style"
-If neither setting does work for you, but you would still want function
-declarations to be highlighted, create your own definitions by changing the
-definitions in java.vim or by creating your own java.vim that includes the
-original one and then adds the code to highlight functions.
+If neither setting does work for you, but you would still want headers of
+function declarations to be highlighted, modify the current syntax definitions
+or compose new ones.
+
+Higher-order function types can be hard to parse by eye, so uniformly toning
+down some of their components may be of value.  Provided that such type names
+conform to the Java naming guidelines, you may arrange it with >
+	:let java_highlight_generics=1
 
 In Java 1.1 the functions System.out.println() and System.err.println() should
 only be used for debugging.  Therefore it is possible to highlight debugging