Replace document_highlight_scopes setting with better default scopes

This removes the user setting for the scopes used to color highlighted
regions of the textDocument/documentHighlight request. Users (or color
scheme authors) can configure their desired style via rules in the color
scheme instead. To easily allow fine-tuned colors, the more specific
scopes `markup.highlight.{text|read|write}.lsp` were added to the
corresponding DocumentHighlightKinds.

Additionally, the `Unknown` kind was removed, because it doesn't exist
in the specification. Complying with the specs, the default kind `Text`
is used now in case the highlight kind is omitted in the response.

LSP.sublime-settings

@@ -86,13 +86,6 @@
   // When set to the empty string (""), no document highlighting is requested.
   "document_highlight_style": "underline",
 
-  "document_highlight_scopes": {
-    "unknown": "text",
-    "text": "text",
-    "read": "markup.inserted",
-    "write": "markup.changed"
-  },
-
   // Gutter marker for code diagnostics.
   // Valid values are "dot", "circle", "bookmark", "sign" or ""
   "diagnostics_gutter_marker": "dot",

docs/src/features.md

@@ -182,11 +182,61 @@ Add these settings to LSP settings, your Sublime settings, Syntax-specific setti
 * `diagnostics_highlight_style` `"underline"` *highlight style of code diagnostics: "box", "underline", "stippled", "squiggly" or ""*
 * `highlight_active_signature_parameter`: *highlight the active parameter of the currently active signature*
 * `document_highlight_style`: *document highlight style: "box", "underline", "stippled", "squiggly" or ""*
-* `document_highlight_scopes`: *customize your sublime text scopes for document highlighting*
 * `diagnostics_gutter_marker` `"dot"` *gutter marker for code diagnostics: "dot", "circle", "bookmark", "sign" or ""*
 * `show_symbol_action_links` `false` *show links to symbol actions like go to, references and rename in the hover popup*
 * `disabled_capabilities`, `[]` *Turn off client capabilities (features): "hover", "completion", "documentHighlight", "colorProvider", "signatureHelp", "codeLensProvider", "codeActionProvider"*
 * `log_debug` `false` *show debug logging in the sublime console*
 * `log_server` `[]` *log communication from and to language servers*
 * `log_stderr` `false` *show language server stderr output in the console*
 * `log_max_size` `8192` *max  number of characters of payloads to print*
+
+### Color configurations
+
+Some features use TextMate scopes to control the colors (underline, background or text color) of styled regions in a document or popup.
+Colors can be customized by adding a rule for these scopes into your color scheme, see https://www.sublimetext.com/docs/3/color_schemes.html#customization.
+
+The following tables give an overview about the scope names used by LSP.
+
+#### Document Highlights
+
+!!! info "This feature is only available if the server has the *documentHighlightProvider* capability."
+    Highlights other occurrences of the symbol at a given cursor position.
+
+| scope | DocumentHighlightKind | description |
+| ----- | --------------------- | ----------- |
+| `markup.highlight.text.lsp` | Text | A textual occurrence |
+| `markup.highlight.read.lsp` | Read | Read-access of a symbol, like reading a variable |
+| `markup.highlight.write.lsp` | Write | Write-access of a symbol, like writing to a variable |
+
+If `document_highlight_style` is set to "fill" in the LSP settings, additionally `meta.fill.lsp` gets prepended to the listed scopes.
+
+#### Diagnostics
+
+=== "Sublime Text 4"
+| scope | DiagnosticSeverity | description |
+| ----- | ------------------ | ----------- |
+| `region.redish` | Error | Reports an error |
+| `region.yellowish` | Warning | Reports a warning |
+| `region.bluish` | Information | Reports an information |
+| `region.bluish` | Hint | Reports a hint |
+
+=== "Sublime Text 3"
+| scope | DiagnosticSeverity | description |
+| ----- | ------------------ | ----------- |
+| `markup.error.lsp` | Error | Reports an error |
+| `markup.warning.lsp` | Warning | Reports a warning |
+| `markup.info.lsp` | Information | Reports an information |
+| `markup.info.suggestion.lsp` | Hint | Reports a hint |
+
+#### Signature Help
+
+| scope | description |
+| ----- | ----------- |
+| `entity.name.function.sighelp.lsp` | Function name in the signature help popup |
+| `variable.parameter.sighelp.lsp` | Function argument in the signature help popup |
+
+#### Code Lens
+
+| scope | description |
+| ----- | ----------- |
+| `markup.codelens.accent` | Accent color for code lens annotations |

plugin/core/protocol.py

@@ -30,7 +30,6 @@ class InsertTextFormat:
 
 
 class DocumentHighlightKind:
-    Unknown = 0
     Text = 1
     Read = 2
     Write = 3

plugin/core/types.py

@@ -155,7 +155,6 @@ class Settings:
     diagnostics_highlight_style = None  # type: str
     diagnostics_panel_include_severity_level = None  # type: int
     disabled_capabilities = None  # type: List[str]
-    document_highlight_scopes = None  # type: Dict[str, str]
     document_highlight_style = None  # type: str
     inhibit_snippet_completions = None  # type: bool
     inhibit_word_completions = None  # type: bool
@@ -191,7 +190,6 @@ def r(name: str, default: Union[bool, int, str, list, dict]) -> None:
         r("diagnostics_highlight_style", "underline")
         r("diagnostics_panel_include_severity_level", 4)
         r("disabled_capabilities", [])
-        r("document_highlight_scopes", {"unknown": "text", "text": "text", "read": "markup.inserted", "write": "markup.changed"})  # noqa
         r("document_highlight_style", "stippled")
         r("log_debug", False)
         r("log_max_size", 8 * 1024)

plugin/documents.py

@@ -46,12 +46,17 @@
 SUBLIME_WORD_MASK = 515
 
 _kind2name = {
-    DocumentHighlightKind.Unknown: "unknown",
     DocumentHighlightKind.Text: "text",
     DocumentHighlightKind.Read: "read",
     DocumentHighlightKind.Write: "write"
 }
 
+_kind2scope = {
+    DocumentHighlightKind.Text: "text markup.highlight.text.lsp",
+    DocumentHighlightKind.Read: "markup.inserted markup.highlight.read.lsp",
+    DocumentHighlightKind.Write: "markup.changed markup.highlight.write.lsp"
+}
+
 ResolveCompletionsFn = Callable[[List[sublime.CompletionItem], int], None]
 
 
@@ -559,12 +564,12 @@ def _unresolved_code_lenses(
     # --- textDocument/documentHighlight -------------------------------------------------------------------------------
 
     def _clear_highlight_regions(self) -> None:
-        for kind in userprefs().document_highlight_scopes.keys():
-            self.view.erase_regions("lsp_highlight_{}".format(kind))
+        for kind in range(1, 4):
+            self.view.erase_regions("lsp_highlight_{}".format(_kind2name[kind]))
 
     def _is_in_higlighted_region(self, point: int) -> bool:
-        for kind in userprefs().document_highlight_scopes.keys():
-            regions = self.view.get_regions("lsp_highlight_{}".format(kind))
+        for kind in range(1, 4):
+            regions = self.view.get_regions("lsp_highlight_{}".format(_kind2name[kind]))
             for r in regions:
                 if r.contains(point):
                     return True
@@ -584,23 +589,30 @@ def _on_highlights(self, response: Optional[List]) -> None:
         if not response:
             self._clear_highlight_regions()
             return
-        kind2regions = {}  # type: Dict[str, List[sublime.Region]]
-        for kind in range(0, 4):
-            kind2regions[_kind2name[kind]] = []
+        kind2regions = {}  # type: Dict[int, List[sublime.Region]]
+        for kind in range(1, 4):
+            kind2regions[kind] = []
         for highlight in response:
             r = range_to_region(Range.from_lsp(highlight["range"]), self.view)
-            kind = highlight.get("kind", DocumentHighlightKind.Unknown)
-            if kind is not None:
-                kind2regions[_kind2name[kind]].append(r)
+            kind = highlight.get("kind", DocumentHighlightKind.Text)
+            if kind in kind2regions:
+                kind2regions[kind].append(r)
+            else:
+                debug("unknown DocumentHighlightKind", kind)
 
         def render_highlights_on_main_thread() -> None:
             self._clear_highlight_regions()
             flags = userprefs().document_highlight_style_to_add_regions_flags()
-            for kind_str, regions in kind2regions.items():
+            for kind, regions in kind2regions.items():
                 if regions:
-                    scope = userprefs().document_highlight_scopes.get(kind_str, None)
-                    if scope:
-                        self.view.add_regions("lsp_highlight_{}".format(kind_str), regions, scope=scope, flags=flags)
+                    scope = _kind2scope[kind]
+                    if not flags & sublime.DRAW_NO_FILL:
+                        scope = "meta.fill.lsp " + scope
+                    self.view.add_regions(
+                        "lsp_highlight_{}".format(_kind2name[kind]),
+                        regions,
+                        scope=scope,
+                        flags=flags)
 
         sublime.set_timeout(render_highlights_on_main_thread)