runtime(java): Tidy up the documentation for "ft-java-syntax"

- Reword a few sentences and reformat a few paragraphs.
- Supply absent capitalisation and punctuation.
- Make listed highlighting groups and code stand out.
- Prefix all Java-related global variables with "g:".
- Add spaces around each variable assignment operator.
- Acknowledge that some Javadoc variables are maintained in
  the HTML syntax file.

Also, move the overridable _default_ HTML group links before
the HTML syntax file inclusion in order to implement the
documented diverged settings.

related: #15399

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

runtime/doc/syntax.txt

@@ -2031,23 +2031,23 @@ idlsyntax_showerror_soft	Use softer colours by default for errors
 
 JAVA						*java.vim* *ft-java-syntax*
 
-The java.vim syntax highlighting file offers several options:
+The java.vim syntax highlighting file offers several options.
 
-In Java 1.0.2 it was never possible to have braces inside parens, so this was
+In Java 1.0.2, it was never possible to have braces inside parens, so this was
-flagged as an error.  Since Java 1.1 this is possible (with anonymous
+flagged as an error.  Since Java 1.1, this is possible (with anonymous
-classes), and therefore is no longer marked as an error.  If you prefer the
+classes); and, therefore, is no longer marked as an error.  If you prefer the
-old way, put the following line into your vim startup file: >
+old way, put the following line into your Vim startup file: >
-	:let java_mark_braces_in_parens_as_errors=1
+	:let g:java_mark_braces_in_parens_as_errors = 1
 
-All identifiers in java.lang.* are always visible in all classes.  To
+All (exported) public types declared in `java.lang` are always automatically
-highlight them use: >
+imported and available as simple names.  To highlight them, use: >
-	:let java_highlight_java_lang_ids=1
+	:let g:java_highlight_java_lang_ids = 1
 
-You can also highlight identifiers of most standard Java packages if you
+You can also highlight types of most standard Java packages if you download
-download the javaid.vim script at http://www.fleiner.com/vim/download.html.
+the javaid.vim script at http://www.fleiner.com/vim/download.html.  If you
-If you prefer to only highlight identifiers of a certain package, say java.io
+prefer to only highlight types of a certain package, say `java.io`, use the
-use the following: >
+following: >
-	:let java_highlight_java_io=1
+	:let g:java_highlight_java_io = 1
 Check the javaid.vim file for a list of all the packages that are supported.
 
 Headers of indented function declarations can be highlighted (along with parts
@@ -2055,25 +2055,26 @@ of lambda expressions and method reference expressions), but it depends on how
 you write Java code.  Two formats are recognized:
 
 1) 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 >
+a tab, or a space . . . or eight space character(s), you may want to set one
-	:let java_highlight_functions="indent"
+of >
-	:let java_highlight_functions="indent1"
+	:let g:java_highlight_functions = "indent"
-	:let java_highlight_functions="indent2"
+	:let g:java_highlight_functions = "indent1"
-	:let java_highlight_functions="indent3"
+	:let g:java_highlight_functions = "indent2"
-	:let java_highlight_functions="indent4"
+	:let g:java_highlight_functions = "indent3"
-	:let java_highlight_functions="indent5"
+	:let g:java_highlight_functions = "indent4"
-	:let java_highlight_functions="indent6"
+	:let g:java_highlight_functions = "indent5"
-	:let java_highlight_functions="indent7"
+	:let g:java_highlight_functions = "indent6"
-	:let java_highlight_functions="indent8"
+	:let g:java_highlight_functions = "indent7"
+	:let g:java_highlight_functions = "indent8"
 Note that in terms of 'shiftwidth', this is the leftmost step of indentation.
 
 2) However, if you follow the Java guidelines about how functions and types
 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"
+	:let g:java_highlight_functions = "style"
 
-In addition, you can combine any value of "java_highlight_functions" with >
+In addition, you can combine any value of "g:java_highlight_functions" with >
-	:let java_highlight_signature=1
+	:let g:java_highlight_signature = 1
 to have the name of a function with its parameter list parens distinctly
 highlighted from its type parameters, return type, and formal parameters; and
 to have the parameter list parens of a lambda expression with its arrow
@@ -2086,54 +2087,61 @@ 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
+	:let g:java_highlight_generics = 1
 
-In Java 1.1 the functions System.out.println() and System.err.println() should
+In Java 1.1, the functions `System.out.println()` and `System.err.println()`
-only be used for debugging.  Therefore it is possible to highlight debugging
+should only be used for debugging.  Consider adding the following definition
-statements differently.  To do this you must add the following definition in
+in your startup file: >
-your startup file: >
+	:let g:java_highlight_debug = 1
-	:let java_highlight_debug=1
+to have the bulk of those statements colored as
-The result will be that those statements are highlighted as 'Special'
+	*Debug		debugging statements,
-characters.  If you prefer to have them highlighted differently you must define
+and to make some of their own items further grouped and linked:
-new highlightings for the following groups.:
+	*Special	as DebugSpecial,
-    Debug, DebugSpecial, DebugString, DebugBoolean, DebugType
+	*String		as DebugString,
-which are used for the statement itself, special characters used in debug
+	*Boolean	as DebugBoolean,
-strings, strings, boolean constants and types (this, super) respectively.  I
+	*Type		as DebugType,
-have opted to choose another background for those statements.
+which are used for special characters appearing in strings, strings proper,
+boolean literals, and special instance references (`super`, `this`, `null`),
+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
+similarly to HTML files (see |html.vim|).  You can even add JavaScript and CSS
-and CSS inside this code (see below).  There are four differences however:
+inside this code (see below).  The HTML rendering diverges as follows:
-  1. The title (all characters up to the first '.' which is followed by
+  1. The first sentence (all characters up to the first period `.`, which is
-     some white space or up to the first '@') is colored differently (to change
+     followed by a whitespace character or a line terminator, or up to the
-     the color change the group CommentTitle).
+     first block tag, e.g. `@param`, `@return`) is colored as
-  2. The text is colored as 'Comment'.
+	*SpecialComment	special comments.
-  3. HTML comments are colored as 'Special'
+  2. The text is colored as
-  4. The special Javadoc tags (@see, @param, ...) are highlighted as specials
+	*Comment	comments.
-     and the argument (for @see, @param, @exception) as Function.
+  3. HTML comments are colored as
-To turn this feature off add the following line to your startup file: >
+	*Special	special symbols.
-	:let java_ignore_javadoc=1
+  4. The standard Javadoc tags (`@code`, `@see`, etc.) are colored as
+	*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: >
+	:let g:java_ignore_javadoc = 1
 
-If you use the special Javadoc comment highlighting described above you
+If you use the special Javadoc comment highlighting described above, you can
-can also turn on special highlighting for Javascript, visual basic
+also turn on special highlighting for JavaScript, Visual Basic scripts, and
-scripts and embedded CSS (stylesheets).  This makes only sense if you
+embedded CSS (stylesheets).  This only makes sense if any of these languages
-actually have Javadoc comments that include either Javascript or embedded
+actually appear in Javadoc comments.  The variables to use are >
-CSS.  The options to use are >
+	:let g:java_javascript = 1
-	:let java_javascript=1
+	:let g:java_css = 1
-	:let java_css=1
+	:let g:java_vb = 1
-	:let java_vb=1
+Note that these three variables are maintained in the HTML syntax file.
 
-In order to highlight nested parens with different colors define colors
+In order to highlight nested parens with different colors, define colors for
-for javaParen, javaParen1 and javaParen2, for example with >
+`javaParen`, `javaParen1`, and `javaParen2`.  For example, >
 	:hi link javaParen Comment
 or >
 	:hi javaParen ctermfg=blue guifg=#0000ff
 
 If you notice highlighting errors while scrolling backwards, which are fixed
-when redrawing with CTRL-L, try setting the "java_minlines" internal variable
+when redrawing with CTRL-L, try setting the "g:java_minlines" variable to
-to a larger number: >
+a larger number: >
-	:let java_minlines = 50
+	:let g:java_minlines = 50
 This will make the syntax synchronization start 50 lines before the first
 displayed line.  The default value is 10.  The disadvantage of using a larger
 number is that redrawing can become slow.

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 23
+" Last Change:		2024 Jul 30
 
 " Please check :help java.vim for comments on some of the options available.
 
@@ -309,6 +309,12 @@ hi def link javaCommentError javaError
 hi def link javaCommentStart javaComment
 
 if !exists("java_ignore_javadoc") && main_syntax != 'jsp'
+  " The overridable "html*" default links must be defined _before_ the
+  " inclusion of the same default links from "html.vim".
+  hi def link htmlComment	Special
+  hi def link htmlCommentPart	Special
+  hi def link htmlArg		Type
+  hi def link htmlString	String
   syntax case ignore
 
   " Include HTML syntax coloring for Javadoc comments.
@@ -601,10 +607,6 @@ hi def link javaCommentStar		javaComment
 hi def link javaType			Type
 hi def link javaExternal		Include
 
-hi def link htmlComment		Special
-hi def link htmlCommentPart		Special
-hi def link htmlArg			Type
-hi def link htmlString			String
 hi def link javaSpaceError		Error
 
 if s:module_info_cur_buf

runtime/syntax/testdir/dumps/java_comments_02.dump

@@ -1,7 +1,7 @@
 | +0#0000e05#ffffff0@3|*| |@+0#e000e06&|r|e|t|u|r|n| +0#0000e05&|{+0#e000e06&|@|c|o|d|e| |n|u|l@1|}| +0#0000e05&|*|/| +0#0000000&@45
 @4|V|o|i|d| |n|o|O|p|4|(|)| |{| |r+0#af5f00255&|e|t|u|r|n| +0#0000000&|n+0#e000002&|u|l@1|;+0#0000000&| |}| @41
 @75
-@4|/+0#0000e05&|*@1| +0#e000e06&|N|o|-|o|p|,| |i|.|e|.|<+0#0000e05&|!|-@1| |-@1|>| +0#e000e06&|n|o| |o|p|e|r|a|t|i|o|n|.| +0#0000000&@33
+@4|/+0#0000e05&|*@1| +0#e000e06&|N|o|-|o|p|,| |i|.|e|.|<|!|-@1| |-@1|>| |n|o| |o|p|e|r|a|t|i|o|n|.| +0#0000000&@33
 | +0#0000e05&@3|*| |@+0#e000e06&|r|e|t|u|r|n| +0#0000e05&|{+0#e000e06&|@|c|o|d|e| |n|u|l@1|}| +0#0000e05&|*|/| +0#0000000&@45
 @4>V|o|i|d| |n|o|O|p|5|(|)| |{| |r+0#af5f00255&|e|t|u|r|n| +0#0000000&|n+0#e000002&|u|l@1|;+0#0000000&| |}| @41
 @75