LSP: implement documentHighlight (#11638)

* implement documentHighlight
* fix bug
* document highlight groups
* use uppercase for help section title
* documentation

runtime/doc/lsp.txt

@@ -76,21 +76,6 @@ FAQ                                                     *lsp-faq*
   set the option in an |after-directory| ftplugin, e.g.
   "after/ftplugin/python.vim".
 
-================================================================================
-LSP HIGHLIGHT                                           *lsp-highlight*
-
-When LSP is activated these highlight groups are defined:
-
-  LspDiagnosticsError
-  LspDiagnosticsHint
-  LspDiagnosticsInformation
-  LspDiagnosticsUnderline
-  LspDiagnosticsUnderlineError
-  LspDiagnosticsUnderlineHint
-  LspDiagnosticsUnderlineInformation
-  LspDiagnosticsUnderlineWarning
-  LspDiagnosticsWarning
-
 ================================================================================
 LSP API                                                 *lsp-api*
 
@@ -173,6 +158,25 @@ name: >
   vim.lsp.protocol.TextDocumentSyncKind.Full == 1
   vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
 
+================================================================================
+LSP HIGHLIGHT                                                    *lsp-highlight*
+
+                                                        *hl-LspDiagnosticsError*
+LspDiagnosticsError       used for "Error" diagnostic virtual text
+                                                      *hl-LspDiagnosticsWarning*
+LspDiagnosticsWarning     used for "Warning" diagnostic virtual text
+                                                  *hl-LspDiagnosticsInformation*
+LspDiagnosticInformation  used for "Information" diagnostic virtual text
+                                                         *hl-LspDiagnosticsHint*
+LspDiagnosticHint         used for "Hint" diagnostic virtual text
+                                                           *hl-LspReferenceText*
+LspReferenceText          used for highlighting "text" references
+                                                           *hl-LspReferenceRead*
+LspReferenceRead          used for highlighting "read" references
+                                                          *hl-LspReferenceWrite*
+LspReferenceWrite         used for highlighting "write" references
+
+
 ================================================================================
 LSP EXAMPLE                                            *lsp-extension-example*
 
@@ -720,6 +724,9 @@ declaration()                                      *vim.lsp.buf.declaration()*
 definition()                                        *vim.lsp.buf.definition()*
                 TODO: Documentation
 
+document_highlight()                        *vim.lsp.buf.document_highlight()*
+                TODO: Documentation
+
 formatting({options})                               *vim.lsp.buf.formatting()*
                 TODO: Documentation
 
@@ -897,6 +904,9 @@ apply_workspace_edit({workspace_edit})
 buf_clear_diagnostics({bufnr})          *vim.lsp.util.buf_clear_diagnostics()*
                 TODO: Documentation
 
+buf_clear_references({bufnr})            *vim.lsp.util.buf_clear_references()*
+                TODO: Documentation
+
                                *vim.lsp.util.buf_diagnostics_save_positions()*
 buf_diagnostics_save_positions({bufnr}, {diagnostics})
                 TODO: Documentation

runtime/lua/vim/lsp/buf.lua

@@ -134,5 +134,23 @@ function M.references(context)
   request('textDocument/references', params)
 end
 
+--- Send request to server to resolve document highlights for the
+--- current text document position. This request can be associated
+--- to key mapping or to events such as `CursorHold`, eg:
+---
+--- <pre>
+--- vim.api.nvim_command [[autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()]]
+--- vim.api.nvim_command [[autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()]]
+--- vim.api.nvim_command [[autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()]]
+--- </pre>
+function M.document_highlight()
+  local params = util.make_position_params()
+  request('textDocument/documentHighlight', params)
+end
+
+function M.clear_references()
+  util.buf_clear_references()
+end
+
 return M
 -- vim:sw=2 ts=2 et

runtime/lua/vim/lsp/callbacks.lua

@@ -196,6 +196,12 @@ M['textDocument/peekDefinition'] = function(_, _, result, _)
   api.nvim_buf_add_highlight(headbuf, -1, 'Keyword', 0, -1)
 end
 
+M['textDocument/documentHighlight'] = function(_, _, result, _)
+  if not result then return end
+  local bufnr = api.nvim_get_current_buf()
+  util.buf_highlight_references(bufnr, result)
+end
+
 local function log_message(_, _, result, client_id)
   local message_type = result.type
   local message = result.message

runtime/lua/vim/lsp/util.lua

@@ -569,6 +569,7 @@ do
   local all_buffer_diagnostics = {}
 
   local diagnostic_ns = api.nvim_create_namespace("vim_lsp_diagnostics")
+  local reference_ns = api.nvim_create_namespace("vim_lsp_references")
 
   local underline_highlight_name = "LspDiagnosticsUnderline"
   vim.cmd(string.format("highlight default %s gui=underline cterm=underline", underline_highlight_name))
@@ -602,7 +603,6 @@ do
 
   function M.buf_clear_diagnostics(bufnr)
     validate { bufnr = {bufnr, 'n', true} }
-    bufnr = bufnr == 0 and api.nvim_get_current_buf() or bufnr
     api.nvim_buf_clear_namespace(bufnr, diagnostic_ns, 0, -1)
   end
 
@@ -683,7 +683,6 @@ do
     end
   end
 
-
   function M.buf_diagnostics_underline(bufnr, diagnostics)
     for _, diagnostic in ipairs(diagnostics) do
       local start = diagnostic.range["start"]
@@ -705,6 +704,25 @@ do
     end
   end
 
+  function M.buf_clear_references(bufnr)
+    validate { bufnr = {bufnr, 'n', true} }
+    api.nvim_buf_clear_namespace(bufnr, reference_ns, 0, -1)
+  end
+
+  function M.buf_highlight_references(bufnr, references)
+    validate { bufnr = {bufnr, 'n', true} }
+    for _, reference in ipairs(references) do
+      local start_pos = {reference["range"]["start"]["line"], reference["range"]["start"]["character"]}
+      local end_pos = {reference["range"]["end"]["line"], reference["range"]["end"]["character"]}
+      local document_highlight_kind = {
+        [protocol.DocumentHighlightKind.Text] = "LspReferenceText";
+        [protocol.DocumentHighlightKind.Read] = "LspReferenceRead";
+        [protocol.DocumentHighlightKind.Write] = "LspReferenceWrite";
+      }
+      highlight_range(bufnr, reference_ns, document_highlight_kind[reference["kind"]], start_pos, end_pos)
+    end
+  end
+
   function M.buf_diagnostics_virtual_text(bufnr, diagnostics)
     local buffer_line_diagnostics = all_buffer_diagnostics[bufnr]
     if not buffer_line_diagnostics then