LSP: implement documentHighlight (#11638)

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

3 files changed, 44 insertions, 2 deletions

diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 19deb5df45..52fa2ec93b 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/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
diff --git a/runtime/lua/vim/lsp/callbacks.lua b/runtime/lua/vim/lsp/callbacks.lua
index e76e07ca96..d7d74862b6 100644
--- a/runtime/lua/vim/lsp/callbacks.lua
+++ b/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
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index b7c7b7f75d..9c67f62e21 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/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