0
0
mirror of https://github.com/vim/vim.git synced 2025-07-25 10:54:51 -04:00

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>
This commit is contained in:
Aliaksei Budavei 2024-07-31 22:13:25 +02:00 committed by Christian Brabandt
parent d88ebcbd9f
commit 3749dff093
No known key found for this signature in database
GPG Key ID: F3F92DA383FDDE09
3 changed files with 80 additions and 70 deletions

View File

@ -2031,23 +2031,23 @@ idlsyntax_showerror_soft Use softer colours by default for errors
JAVA *java.vim* *ft-java-syntax* 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. 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 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: you write Java code. Two formats are recognized:
1) If you write function declarations that are consistently indented by either 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. 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 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 are supposed to be named (with respect to upper- and lowercase) and there is
any amount of indentation, you may want to set > 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 to have the name of a function with its parameter list parens distinctly
highlighted from its type parameters, return type, and formal parameters; and highlighted from its type parameters, return type, and formal parameters; and
to have the parameter list parens of a lambda expression with its arrow 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 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 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 > 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 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 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 :hi link javaParen Comment
or > or >
:hi javaParen ctermfg=blue guifg=#0000ff :hi javaParen ctermfg=blue guifg=#0000ff
If you notice highlighting errors while scrolling backwards, which are fixed 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 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 displayed line. The default value is 10. The disadvantage of using a larger
number is that redrawing can become slow. number is that redrawing can become slow.

View File

@ -3,7 +3,7 @@
" Maintainer: Aliaksei Budavei <0x000c70 AT gmail DOT com> " Maintainer: Aliaksei Budavei <0x000c70 AT gmail DOT com>
" Former Maintainer: Claudio Fleiner <claudio@fleiner.com> " Former Maintainer: Claudio Fleiner <claudio@fleiner.com>
" Repository: https://github.com/zzzyxwvut/java-vim.git " 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. " 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 hi def link javaCommentStart javaComment
if !exists("java_ignore_javadoc") && main_syntax != 'jsp' 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 syntax case ignore
" Include HTML syntax coloring for Javadoc comments. " Include HTML syntax coloring for Javadoc comments.
@ -601,10 +607,6 @@ hi def link javaCommentStar javaComment
hi def link javaType Type hi def link javaType Type
hi def link javaExternal Include 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 hi def link javaSpaceError Error
if s:module_info_cur_buf if s:module_info_cur_buf

View File

@ -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 | +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 @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 @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 | +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 @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 @75