From 7d82aaa6f5a6403f3c4e330dcaba9bb36ecbef28 Mon Sep 17 00:00:00 2001 From: Chris Kipp Date: Wed, 24 Feb 2021 17:23:47 +0100 Subject: [PATCH] [LSP] Add in more docs for highlight groups with document_highlight() (#13614) Currently it's not 100% clear that without setting these, using the autocomds to utilize the `textDocument/documentHighlight` functionality, nothing will actually be visible since the highlight groups don't have any details. This just adds in a couple simple extra notes to make sure that's done --- runtime/doc/lsp.txt | 17 ++++++++++++++--- runtime/lua/vim/lsp/buf.lua | 12 +++++++++--- 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 06666c3a27..e4350576a4 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -397,6 +397,11 @@ LSP HIGHLIGHT *lsp-highlight* Reference Highlights: +Highlight groups that are meant to be used by |vim.lsp.buf.document_highlight()|. + +You can see more about the differences in types here: +https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight + *hl-LspReferenceText* LspReferenceText used for highlighting "text" references *hl-LspReferenceRead* @@ -932,15 +937,21 @@ definition() *vim.lsp.buf.definition()* Jumps to the definition of the symbol under the cursor. document_highlight() *vim.lsp.buf.document_highlight()* - 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: + Send request to the server to resolve document highlights for + the current text document position. This request can be + triggered by a key mapping or by events such as `CursorHold` , + eg: > vim.api.nvim_command [[autocmd CursorHold lua vim.lsp.buf.document_highlight()]] vim.api.nvim_command [[autocmd CursorHoldI lua vim.lsp.buf.document_highlight()]] vim.api.nvim_command [[autocmd CursorMoved lua vim.lsp.buf.clear_references()]] < + Note: Usage of |vim.lsp.buf.document_highlight()| requires the + following highlight groups to be defined or you won't be able + to see the actual highlights. |LspReferenceText| + |LspReferenceRead| |LspReferenceWrite| + document_symbol() *vim.lsp.buf.document_symbol()* Lists all symbols in the current buffer in the quickfix window. diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua index 00219b6d98..31116985e2 100644 --- a/runtime/lua/vim/lsp/buf.lua +++ b/runtime/lua/vim/lsp/buf.lua @@ -310,15 +310,21 @@ function M.workspace_symbol(query) request('workspace/symbol', 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: +--- Send request to the server to resolve document highlights for the current +--- text document position. This request can be triggered by a key mapping or +--- by events such as `CursorHold`, eg: --- --- 
 --- vim.api.nvim_command [[autocmd CursorHold   lua vim.lsp.buf.document_highlight()]]
 --- vim.api.nvim_command [[autocmd CursorHoldI  lua vim.lsp.buf.document_highlight()]]
 --- vim.api.nvim_command [[autocmd CursorMoved  lua vim.lsp.buf.clear_references()]]
 ---
+--- +--- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups +--- to be defined or you won't be able to see the actual highlights. +--- |LspReferenceText| +--- |LspReferenceRead| +--- |LspReferenceWrite| function M.document_highlight() local params = util.make_position_params() request('textDocument/documentHighlight', params)