runtime(java): Tidy up the documentation for "ft-java-syntax"
Commit:
https://github.com/vim/vim/commit/3749dff093d8c3ba0cd34cebf42bd4d3d93afe26
Author: Aliaksei Budavei <0x000...@gmail.com>
Date: Wed Jul 31 22:13:25 2024 +0200
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 <0x000...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 9449b7577..8af731fb1 100644
--- a/runtime/doc/syntax.txt
+++ b/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:
-
-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
-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: >
- :let java_mark_braces_in_parens_as_errors=1
-
-All identifiers in java.lang.* are always visible in all classes. To
-highlight them use: >
- :let java_highlight_java_lang_ids=1
-
-You can also highlight identifiers of most standard Java packages if you
-download the javaid.vim script at http://www.fleiner.com/vim/download.html.
-If you prefer to only highlight identifiers of a certain package, say java.io
-use the following: >
- :let java_highlight_java_io=1
+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
+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
+old way, put the following line into your Vim startup file: >
+ :let g:java_mark_braces_in_parens_as_errors = 1
+
+All (exported) public types declared in `java.lang` are always automatically
+imported and available as simple names. To highlight them, use: >
+ :let g:java_highlight_java_lang_ids = 1
+
+You can also highlight types of most standard Java packages if you download
+the javaid.vim script at http://www.fleiner.com/vim/download.html. If you
+prefer to only highlight types of a certain package, say `java.io`, use the
+following: >
+ :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 >
- :let java_highlight_functions="indent"
- :let java_highlight_functions="indent1"
- :let java_highlight_functions="indent2"
- :let java_highlight_functions="indent3"
- :let java_highlight_functions="indent4"
- :let java_highlight_functions="indent5"
- :let java_highlight_functions="indent6"
- :let java_highlight_functions="indent7"
- :let java_highlight_functions="indent8"
+a tab, or a space . . . or eight space character(s), you may want to set one
+of >
+ :let g:java_highlight_functions = "indent"
+ :let g:java_highlight_functions = "indent1"
+ :let g:java_highlight_functions = "indent2"
+ :let g:java_highlight_functions = "indent3"
+ :let g:java_highlight_functions = "indent4"
+ :let g:java_highlight_functions = "indent5"
+ :let g:java_highlight_functions = "indent6"
+ :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 >
- :let java_highlight_signature=1
+In addition, you can combine any value of "g:java_highlight_functions" with >
+ :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
-
-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
-statements differently. To do this you must add the following definition in
-your startup file: >
- :let java_highlight_debug=1
-The result will be that those statements are highlighted as 'Special'
-characters. If you prefer to have them highlighted differently you must define
-new highlightings for the following groups.:
- Debug, DebugSpecial, DebugString, DebugBoolean, DebugType
-which are used for the statement itself, special characters used in debug
-strings, strings, boolean constants and types (this, super) respectively. I
-have opted to choose another background for those statements.
+ :let g:java_highlight_generics = 1
+
+In Java 1.1, the functions `System.out.println()` and `System.err.println()`
+should only be used for debugging. Consider adding the following definition
+in your startup file: >
+ :let g:java_highlight_debug = 1
+to have the bulk of those statements colored as
+ *Debug debugging statements,
+and to make some of their own items further grouped and linked:
+ *Special as DebugSpecial,
+ *String as DebugString,
+ *Boolean as DebugBoolean,
+ *Type as DebugType,
+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
-and CSS inside this code (see below). There are four differences however:
- 1. The title (all characters up to the first '.' which is followed by
- some white space or up to the first '@') is colored differently (to change
- the color change the group CommentTitle).
- 2. The text is colored as 'Comment'.
- 3. HTML comments are colored as 'Special'
- 4. The special Javadoc tags (@see, @param, ...) are highlighted as specials
- and the argument (for @see, @param, @exception) as Function.
-To turn this feature off add the following line to your startup file: >
- :let java_ignore_javadoc=1
-
-If you use the special Javadoc comment highlighting described above you
-can also turn on special highlighting for Javascript, visual basic
-scripts and embedded CSS (stylesheets). This makes only sense if you
-actually have Javadoc comments that include either Javascript or embedded
-CSS. The options to use are >
- :let java_javascript=1
- :let java_css=1
- :let java_vb=1
-
-In order to highlight nested parens with different colors define colors
-for javaParen, javaParen1 and javaParen2, for example with >
+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:
+ 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
+ *SpecialComment special comments.
+ 2. The text is colored as
+ *Comment comments.
+ 3. HTML comments are colored as
+ *Special special symbols.
+ 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 can
+also turn on special highlighting for JavaScript, Visual Basic scripts, and
+embedded CSS (stylesheets). This only makes sense if any of these languages
+actually appear in Javadoc comments. The variables to use are >
+ :let g:java_javascript = 1
+ :let g:java_css = 1
+ :let g: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 for
+`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
-to a larger number: >
- :let java_minlines = 50
+when redrawing with CTRL-L, try setting the "g:java_minlines" variable to
+a larger number: >
+ :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.
diff --git a/runtime/syntax/java.vim b/runtime/syntax/java.vim
index 9c4964db7..a63ae0216 100644
--- a/runtime/syntax/java.vim
+++ b/runtime/syntax/java.vim
@@ -3,7 +3,7 @@
" Maintainer: Aliaksei Budavei <0x000c70 AT gmail DOT com>
" Former Maintainer: Claudio Fleiner <clau...@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
diff --git a/runtime/syntax/testdir/dumps/java_comments_02.dump
b/runtime/syntax/testdir/dumps/java_comments_02.dump
index 008a3e0d1..25babc766 100644
--- a/runtime/syntax/testdir/dumps/java_comments_02.dump
+++ b/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
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/vim_dev/E1sZFxU-006RM2-TP%40256bit.org.
